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 hosts de 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 direcionadas ao espaço de trabalho que possui a chave de API.
Se a chave tiver uma lista de IPs permitidos, endereços IP não incluídos na lista retornarão 403.

Permissões de chave de API

Esta seção mapeia cada endpoint à sua 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`	Leituras de tipos e objetos, e leituras de 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`	Leituras 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

As leituras de relacionamentos entre objetos usam data_objects.read. Não existe uma permissão data_objects.object_relationships.read.

Limites de frequência

Esta seção explica as cotas padrão de solicitações 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 para 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. Sua equipe de conta da 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 objetos 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 de `object_id`	250 caracteres. Apenas letras, números, hifens e underscores.
Comprimento e formato do nome do campo	250 caracteres. Apenas 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 objetos para um objeto de dados	`data-object-relationship-limit-exceeded`

Seus registros e relacionamentos existentes permanecem intactos — apenas 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 utiliza mais. Para aumentar um limite de contagem, entre em contato com sua equipe de conta da Braze.

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

Conceitos fundamentais

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, único dentro de um espaço de trabalho.
object_id: O identificador do seu objeto, único 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 contra o esquema configurado.

Como os relacionamentos funcionam

Esta seção explica os tipos de relacionamento, as arestas de relacionamento e o comportamento do 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 vincular esses elementos permite fazer na Braze. Você define os tipos no dashboard e, em seguida, cria os registros e os vínculos entre eles por meio desses 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

Os tipos de relacionamento definem quais vínculos são válidos e são gerenciados no dashboard.
As arestas de relacionamento são os vínculos reais entre registros e são criadas, atualizadas e excluídas por meio desses endpoints de API.
Antes de criar 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.
Portanto, as operações de escrita de relacionamento de objetos exigem tanto rel_kind quanto related_type_name para identificar o tipo de relacionamento pretendido, juntamente com o outro tipo de objeto na associação.
Se 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 no 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 aponta para um único relacionamento subjacente. Uma segunda chamada de criação para a mesma aresta retorna 409 (duplicate-object-relationship).

Assimetria de jornadas para relacionamentos de usuários

As leituras e escritas de relacionamentos de usuários usam jornadas de endpoint diferentes intencionalmente:

Leitura: GET /data_objects/objects/{type_name}/{object_id}/user_relationships
Escrita: 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 conta:

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 consultar os vínculos criados:

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 saída de objetos
GET /data_objects/objects/account/acct-456/object_relationships?anchor=target para vínculos de entrada de objetos