Ir para o conteúdo

Endpoints de objetos de dados

Use esses endpoints para listar tipos de objetos de dados, gerenciar registros de objetos de dados e gerenciar relacionamentos entre objetos e usuários.

Importante

Objetos de dados está atualmente em acesso antecipado. Seu espaço de trabalho precisa estar ativado antes que as permissões da chave de API de objetos de dados apareçam em Configurações > Chaves de API.

Endpoints de tipo

Endpoints de objeto

Endpoints de relacionamento de objeto

Endpoints de relacionamento de usuário

URL base e autenticação

Use o endpoint REST do seu espaço de trabalho e envie Authorization: Bearer YOUR_REST_API_KEY. Esta seção explica onde os endpoints de Objetos de dados estão hospedados e como as solicitações são autenticadas.

Para os hosts dos endpoints, consulte Visão geral da API da Braze.
Todas as cargas úteis de solicitação e resposta são JSON.
As solicitações são limitadas ao espaço de trabalho que possui a chave de API.
Se a chave tiver uma lista de IPs permitidos, endereços IP fora da lista retornam 403.

Permissões de chave de API

Esta seção mapeia cada endpoint para a permissão necessária, para que você possa definir o escopo das chaves de API com segurança.

Permissão	Grupo de endpoints
`data_objects.read`	Leitura de tipos, objetos e relacionamentos entre objetos
`data_objects.create`	Criação de objetos
`data_objects.update`	Substituição e atualização de objetos
`data_objects.delete`	Exclusão de objetos
`data_objects.user_relationships.read`	Leitura de relacionamentos de usuários
`data_objects.user_relationships.create`	Criação de relacionamentos de usuários
`data_objects.user_relationships.update`	Substituição e atualização de relacionamentos de usuários
`data_objects.user_relationships.delete`	Exclusão de relacionamentos de usuários
`data_objects.object_relationships.create`	Criação de relacionamentos entre objetos
`data_objects.object_relationships.update`	Substituição e atualização de relacionamentos entre objetos
`data_objects.object_relationships.delete`	Exclusão de relacionamentos entre objetos

Nota

A leitura de relacionamentos entre objetos usa data_objects.read. Não existe uma permissão data_objects.object_relationships.read.

Limites de frequência

Esta seção explica as cotas de solicitação padrão e os cabeçalhos de resposta para tráfego de leitura e gravação.

Bucket	Limite padrão
Leitura de Objetos de dados	50 solicitações por minuto
Gravação de Objetos de dados	50 solicitações por minuto

Toda resposta inclui X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset.

Para solicitações limitadas, a Braze retorna 429 e uma carga útil de erro com id e message.

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

Limites do produto

Esta seção lista os limites que a Braze aplica aos Objetos de dados e o que esperar quando você atingir um deles.

Limites de contagem

Esses limites se aplicam à sua empresa como um todo, salvo indicação contrária. A equipe da sua conta Braze pode ajustar os valores padrão para a sua empresa.

Limite	Valor padrão
Registros de objetos de dados por empresa (em todos os espaços de trabalho)	1.000.000
Campos por tipo de objeto de dados	500
Objetos de dados vinculados a um usuário	1.000
Usuários vinculados a um objeto de dados	10.000
Relacionamentos de objeto para um objeto de dados	1.000

Limites de campo e valor

Esses limites são fixos para todas as empresas.

Limite	Valor
Comprimento do valor do atributo	255 caracteres
Comprimento e formato do `object_id`	250 caracteres. Somente letras, números, hifens e underscores.
Comprimento e formato do nome do campo	250 caracteres. Somente letras, números e underscores, e não pode começar com underscore.
Nomes de campo reservados	`id`, `external_id`, `object_id` e `display_name` não podem ser usados como nomes de campos personalizados.

O que acontece quando você atinge um limite

Uma solicitação que excederia um limite de contagem retorna 422 com um id de erro que identifica o limite:

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

Limite	`id` do erro
Registros de objetos de dados por empresa	`data-object-record-limit-exceeded`
Campos por tipo de objeto de dados	`data-object-field-limit-exceeded`
Objetos de dados vinculados a um usuário	`data-objects-per-user-limit-exceeded`
Usuários vinculados a um objeto de dados	`users-per-data-object-limit-exceeded`
Relacionamentos de objeto para um objeto de dados	`data-object-relationship-limit-exceeded`

Seus registros e relacionamentos existentes permanecem intactos — somente a solicitação que excederia o limite é rejeitada. Para liberar espaço dentro de um limite, exclua registros que você não precisa mais ou remova relacionamentos que não são mais utilizados. Para aumentar um limite de contagem, entre em contato com a equipe da sua conta Braze.

Solicitações que falham na validação, como um object_id ou valor de atributo muito longo, retornam 400. Solicitações que excedem o limite de frequência retornam 429.

Conceitos principais

Esta seção define os identificadores principais usados em todos os endpoints de Objetos de dados.

type_name: O nome de máquina do tipo de objeto de dados, exclusivo dentro de um espaço de trabalho.
object_id: O identificador do seu objeto, exclusivo dentro de um tipo.
braze_id: O ID de usuário da Braze usado nos endpoints de relacionamento de usuários.
attributes: Objeto com chaves de nomes de campos ou dados de relacionamento validados conforme o esquema configurado.

Como os relacionamentos funcionam

Esta seção explica os tipos de relacionamento, as arestas de relacionamento e o comportamento de anchor antes de você usar as páginas de referência dos endpoints.

Visão geral do modelo de relacionamento

Use este diagrama para ver como tipos, registros e relacionamentos se encaixam, e o que vinculá-los permite que você faça na Braze. Você define os tipos no dashboard e, em seguida, grava os registros e os vínculos entre eles por meio destes 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

Tipos e arestas são separados

Tipos de relacionamento definem quais vínculos são válidos e são gerenciados no dashboard.
Arestas de relacionamento são os vínculos reais entre registros e são criadas, atualizadas e excluídas por meio destes endpoints de API.
Antes de gravar relacionamentos, liste os valores válidos de rel_kind com:
- GET /data_objects/types/{type_name}/user_relationship_types
- GET /data_objects/types/{type_name}/object_relationship_types

Por que relacionamentos de objetos exigem `related_type_name`

rel_kind não é globalmente único entre todos os pares de tipos de objeto. Por exemplo, rel_kind pode ser subaccount para um par de tipos de objeto e partner_account para outro.
Gravações de relacionamento de objetos, portanto, exigem tanto rel_kind quanto related_type_name para identificar o tipo de relacionamento pretendido, junto com o outro tipo de objeto na associação.
Se o related_type_name não corresponder ao tipo de relacionamento para aquele rel_kind, a solicitação retorna 400.

`anchor` controla a direção do relacionamento

Os relacionamentos de objetos são direcionais. O objeto da URL é interpretado com base em anchor.

`anchor`	Papel do objeto da URL	Chave do objeto relacionado nas respostas
`source` (padrão)	Lado de origem (aresta de saída)	`to_data_object`
`target`	Lado de destino (aresta de entrada)	`from_data_object`

Criar a mesma aresta a partir da perspectiva oposta do anchor ainda tem como alvo um único relacionamento subjacente. Uma segunda chamada de criação para a mesma aresta retorna 409 (duplicate-object-relationship).

Assimetria de caminhos para relacionamentos de usuários

As leituras e gravações de relacionamentos de usuários usam caminhos de endpoint diferentes intencionalmente:

Leitura: GET /data_objects/objects/{type_name}/{object_id}/user_relationships
Gravação: POST|PUT|PATCH|DELETE /data_objects/objects/{type_name}/{object_id}/users

Atributos de relacionamento são separados dos atributos de objeto

Os endpoints de relacionamento retornam atributos no nível da aresta no campo attributes de nível superior.
Os atributos do objeto permanecem aninhados em to_data_object ou from_data_object.
PUT substitui os attributes do relacionamento, e PATCH mescla os attributes do relacionamento.

Exemplo prático

Este exemplo mostra um fluxo de trabalho comum de contas:

Crie account/acct-123.
Crie account/acct-456 como uma conta filha.
Vincule um usuário a acct-123 com rel_kind: account_user.
Vincule acct-123 a acct-456 com rel_kind: subaccount.

Para ler os vínculos de volta:

GET /data_objects/objects/account/acct-123/user_relationships para usuários vinculados
GET /data_objects/objects/account/acct-123/object_relationships para vínculos de objeto de saída
GET /data_objects/objects/account/acct-456/object_relationships?anchor=target para vínculos de objeto de entrada