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 están disponibles de forma general, pero tu espacio de trabajo debe estar aprovisionado para Cuentas antes de que puedas usar estos endpoints. Para solicitar el aprovisionamiento, ve a Configuración de datos > Cuentas y completa el cuestionario. Una vez completado el aprovisionamiento, los permisos de clave de API de objetos de datos aparecen en Configuración > Claves de API. Para más detalles, consulta Habilitar Cuentas.

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 entre objetos

• 

  GET: Listar relaciones entre objetos
• 

  POST: Crear relación entre objetos
• 

  PUT: Reemplazar relación entre objetos
• 

  PATCH: Actualizar relación entre objetos
• 

  DELETE: Eliminar relación entre objetos

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

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

• Para conocer los hosts de los endpoints, consulta el resumen de la API de Braze.
• Todas las cargas útiles de solicitud y respuesta están en formato JSON.
• Las solicitudes se limitan al espacio de trabajo al que pertenece la clave de API.
• Si la clave tiene una lista de IP permitidas, las direcciones IP que no estén en esa lista devuelven 403.

Permisos de clave de API

Esta sección asigna cada endpoint a su permiso obligatorio para que puedas limitar el alcance de las claves de API de forma segura.

Nota

La lectura de relaciones entre objetos utiliza data_objects.read. No existe el permiso data_objects.object_relationships.read.

Límites de velocidad

En esta sección se explican las cuotas de solicitudes predeterminadas y los encabezados de respuesta para el tráfico de lectura y 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 1000 requests per minute."
    }
  ]
}

Límites del producto

Esta sección enumera los límites que Braze aplica a los objetos de datos y qué puedes esperar cuando alcanzas uno. Para saber cómo se aplican estos límites a los registros de cuentas, consulta Límites de los objetos de cuenta.

Límites de cantidad

Estos límites se aplican a tu empresa en su conjunto, salvo que se indique lo contrario. Son capacidades iniciales. Si necesitas más registros o un límite más alto, ponte en contacto con el equipo de tu cuenta de Braze para solicitar un aumento.

Límites de campos y valores

Estos límites son fijos para todas las empresas.

Qué ocurre cuando alcanzas un límite

Una solicitud que superaría 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 se mantienen: solo se rechaza la solicitud que superaría el límite. Para liberar espacio dentro de un límite, elimina los registros que ya no necesites o quita las relaciones que ya no uses. Para aumentar un límite de cantidad, ponte en contacto con el equipo de tu cuenta de Braze.

Las solicitudes que no superan 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 principales

Esta sección define los identificadores clave que se utilizan 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 que se utiliza en los endpoints de relaciones de usuarios.
• attributes: Datos del objeto o de la relación, con claves por nombre de campo, que se validan con el esquema configurado.

Cómo funcionan las relaciones

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

Resumen del modelo de relaciones

Usa este diagrama para ver cómo encajan los tipos, los registros y las relaciones, y qué te permite hacer en Braze vincularlos. Defines los tipos en el panel y luego escribes 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 los bordes son independientes

• Los tipos de relación definen qué vínculos son válidos y se administran en el panel.
• Los bordes de relación son los vínculos reales entre registros y se crean, actualizan y eliminan a través de estos endpoints de la 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 único globalmente entre 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 eso, las escrituras de relaciones entre objetos requieren tanto rel_kind como related_type_name para identificar el tipo de relación deseado junto con el otro tipo de objeto de la asociación.
• Si related_type_name no coincide con el tipo de relación de 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 el mismo borde desde la perspectiva del anchor opuesto sigue apuntando a una única relación subyacente. Una segunda llamada de creación para el mismo borde devuelve 409 (duplicate-object-relationship).

Asimetría de rutas para las relaciones de usuarios

Las lecturas y escrituras de relaciones de usuarios usan intencionadamente 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 de objeto

• Los endpoints de relaciones devuelven los atributos a nivel de borde en el campo attributes de nivel superior.
• Los atributos de objeto permanecen anidados bajo 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 de cuentas habitual:

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 volver a leer los vínculos:

• 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 salientes entre objetos
• GET /data_objects/objects/account/acct-456/object_relationships?anchor=target para los vínculos entrantes entre objetos

Nota

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

Paginación y actualización de los datos

Esta sección describe el comportamiento de la paginación en las listas y los tiempos esperados 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 restringe 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 inmediato para las lecturas y la personalización con Liquid.
• La pertenencia a un Segment basada en objetos de datos puede tener un retraso de hasta una hora, porque los filtros calculados se actualizan cada hora.

Comportamiento de errores

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

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