Endpoints de objetos de datos

Usa estos endpoints para listar tipos de objetos de datos, gestionar registros de objetos de datos y gestionar relaciones entre objetos y usuarios.

Importante

Los objetos de datos se encuentran actualmente en acceso anticipado. Tu espacio de trabajo debe estar habilitado antes de que los permisos de clave de API de objetos de datos aparezcan en Configuración > Claves de API.

Endpoints de tipos

• 

  GET: Listar tipos de objetos de datos
• 

  GET: Obtener tipo de objeto de datos
• 

  GET: Listar tipos de relación de usuario
• 

  GET: Listar tipos de relación de objeto

Endpoints de objetos

• 

  GET: Listar objetos de datos
• 

  GET: Obtener objeto de datos
• 

  POST: Crear objeto de datos
• 

  PUT: Reemplazar objeto de datos
• 

  PATCH: Actualizar objeto de datos
• 

  DELETE: Eliminar objeto de datos

Endpoints de relaciones de objetos

• 

  GET: Listar relaciones de objetos
• 

  POST: Crear relación de objeto
• 

  PUT: Reemplazar relación de objeto
• 

  PATCH: Actualizar relación de objeto
• 

  DELETE: Eliminar relación de objeto

Endpoints de relaciones de usuarios

• 

  GET: Listar relaciones de usuarios
• 

  POST: Crear relación de usuario
• 

  PUT: Reemplazar relación de usuario
• 

  PATCH: Actualizar relación de usuario
• 

  DELETE: Eliminar relación de usuario

URL base y autenticación

Utiliza el endpoint REST de tu espacio de trabajo y envía Authorization: Bearer YOUR_REST_API_KEY. Esta sección explica dónde se alojan los endpoints de objetos de datos y cómo se autentican las solicitudes.

• Para los hosts de los endpoints, consulta Resumen de la API de Braze.
• Todas las cargas útiles de solicitud y respuesta son JSON.
• Las solicitudes están asociadas al espacio de trabajo propietario de la clave de API.
• Si la clave tiene una lista de IP permitidas, las direcciones IP que no estén en la lista devuelven 403.

Permisos de clave de API

Esta sección asocia cada endpoint con su permiso requerido para que puedas asignar el alcance de las claves de API de forma segura.

Nota

Las lecturas de relaciones entre objetos utilizan data_objects.read. No existe un permiso data_objects.object_relationships.read.

Límites de velocidad

Esta sección explica las cuotas de solicitudes predeterminadas y los encabezados de respuesta tanto para el tráfico de lectura como de escritura.

Cada respuesta incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset.

Para las solicitudes limitadas, Braze devuelve 429 y una carga útil de error con id y message.

1
2
3
4
5
6
7
8

{
  "errors": [
    {
      "id": "rate-limit-exceeded",
      "message": "You have exceeded your limit of 50 requests per minute."
    }
  ]
}

Límites del producto

Esta sección enumera los límites que Braze aplica a los objetos de datos y lo que puedes esperar cuando alcanzas uno.

Límites de cantidad

Estos límites se aplican a tu empresa en su conjunto, salvo que se indique lo contrario. Tu equipo de cuenta de Braze puede ajustar los valores predeterminados para tu empresa.

Límites de campos y valores

Estos límites son fijos para todas las empresas.

Qué sucede cuando alcanzas un límite

Una solicitud que exceda un límite de cantidad devuelve 422 con un id de error que identifica el límite:

1
2
3
4
5
6
7
8

{
  "errors": [
    {
      "id": "data-object-record-limit-exceeded",
      "message": "This company has reached its data object record limit"
    }
  ]
}

Tus registros y relaciones existentes permanecen en su lugar; solo se rechaza la solicitud que excedería el límite. Para liberar espacio dentro de un límite, elimina los registros que ya no necesites o elimina las relaciones que ya no utilices. Para aumentar un límite de cantidad, contacta a tu equipo de cuenta de Braze.

Las solicitudes que no pasan la validación, como un object_id o un valor de atributo demasiado largo, devuelven 400. Las solicitudes que superan el límite de velocidad devuelven 429.

Conceptos fundamentales

Esta sección define los identificadores clave utilizados en todos los endpoints de objetos de datos.

• type_name: El nombre de máquina del tipo de objeto de datos, único dentro de un espacio de trabajo.
• object_id: Tu identificador de objeto, único dentro de un tipo.
• braze_id: El ID de usuario de Braze utilizado en los endpoints de relaciones de usuarios.
• attributes: Objeto con claves de nombres de campo o datos de relación validados contra el esquema configurado.

Cómo funcionan las relaciones

Esta sección explica los tipos de relación, las aristas de relación y el comportamiento de anchor antes de que utilices las páginas de referencia de endpoints.

Modelo de relaciones de un vistazo

Utiliza este diagrama para ver cómo encajan entre sí los tipos, los registros y las relaciones, y lo que vincularlos te permite hacer en Braze. Defines los tipos en el panel y, a continuación, creas los registros y los vínculos entre ellos a través de estos endpoints.

%%{init: {"flowchart": {"wrappingWidth": 400}} }%%
flowchart LR
  subgraph define["Set up in the dashboard"]
    objtype["Data object types define<br/>the fields a record has"]
    reltype["Relationship types determine<br/>which links are allowed"]
  end

  subgraph write["Write with the API"]
    person["A person you<br/>send messages to"]
    record["A business record<br/>they belong to"]
    related["Another record<br/>connected to it"]
    person -- "A user relationship links<br/>a person to a record" --> record
    record -- "An object relationship links<br/>one record to another" --> related
  end

  subgraph unlock["What it unlocks"]
    segment["Segment people by the<br/>records they belong to"]
    liquid["Personalize messages with<br/>data from those records"]
  end

  define -- "decides what you<br/>are allowed to link" --> write
  write -- "makes these<br/>possible" --> unlock

Los tipos y las aristas son elementos separados

• Los tipos de relación definen qué vínculos son válidos y se gestionan en el panel.
• Las aristas de relación son los vínculos reales entre registros y se crean, actualizan y eliminan a través de estos endpoints de API.
• Antes de escribir relaciones, enumera los valores válidos de rel_kind con:
  • GET /data_objects/types/{type_name}/user_relationship_types
  • GET /data_objects/types/{type_name}/object_relationship_types

Por qué las relaciones entre objetos requieren related_type_name

• rel_kind no es globalmente único en todos los pares de tipos de objeto. Por ejemplo, rel_kind puede ser subaccount para un par de tipos de objeto y partner_account para otro.
• Por lo tanto, las escrituras de relaciones entre objetos requieren tanto rel_kind como related_type_name para identificar el tipo de relación previsto junto con el otro tipo de objeto en la asociación.
• Si related_type_name no coincide con el tipo de relación para ese rel_kind, la solicitud devuelve 400.

anchor controla la dirección de la relación

Las relaciones entre objetos son direccionales. El objeto de la URL se interpreta en función de anchor.

Crear la misma arista desde la perspectiva de anchor opuesta sigue apuntando a una única relación subyacente. Una segunda llamada de creación para la misma arista devuelve 409 (duplicate-object-relationship).

Asimetría de rutas en las relaciones de usuarios

Las lecturas y escrituras de relaciones de usuarios utilizan intencionalmente rutas de endpoint diferentes:

• Lectura: GET /data_objects/objects/{type_name}/{object_id}/user_relationships
• Escritura: POST|PUT|PATCH|DELETE /data_objects/objects/{type_name}/{object_id}/users

Los atributos de relación son independientes de los atributos del objeto

• Los endpoints de relación devuelven atributos a nivel de arista en el campo attributes de nivel superior.
• Los atributos del objeto permanecen anidados dentro de to_data_object o from_data_object.
• PUT reemplaza los attributes de la relación, y PATCH fusiona los attributes de la relación.

Ejemplo práctico

Este ejemplo muestra un flujo de trabajo común con cuentas:

1. Crea account/acct-123.
2. Crea account/acct-456 como cuenta secundaria.
3. Vincula un usuario a acct-123 con rel_kind: account_user.
4. Vincula acct-123 a acct-456 con rel_kind: subaccount.

Para leer los vínculos de vuelta:

• GET /data_objects/objects/account/acct-123/user_relationships para los usuarios vinculados
• GET /data_objects/objects/account/acct-123/object_relationships para los vínculos de objeto salientes
• GET /data_objects/objects/account/acct-456/object_relationships?anchor=target para los vínculos de objeto entrantes

Nota

Los endpoints DELETE para relaciones entre objetos y relaciones de usuarios requieren un cuerpo de solicitud JSON.

Paginación y actualización de datos

Esta sección cubre el comportamiento de paginación de listas y el tiempo esperado de visibilidad de los datos después de las escrituras.

• Los endpoints de lista admiten limit y offset.
• limit tiene un valor predeterminado de 100 y se limita a un rango de 1 a 250.
• offset tiene un valor predeterminado de 0, y los valores negativos se redondean a 0.
• Las escrituras son visibles de forma inmediata para las lecturas y la personalización con Liquid.
• La pertenencia a Segments basada en objetos de datos puede retrasarse hasta una hora, ya que los filtros calculados se actualizan cada hora.

Comportamiento de errores

Esta sección resume los patrones de estado y respuesta de error utilizados en los endpoints de objetos de datos.

• 404, 409, 422 y 429 devuelven un array errors con id y message.
• 400, 401 y 403 devuelven una cadena error única.
• 422 significa que la solicitud excedería un límite de producto. Los valores de límite predeterminados varían según el contrato de la empresa.