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

O recurso Objetos de dados está disponível para todos, mas seu espaço de trabalho precisa estar provisionado para Contas antes que você possa usar esses endpoints. Para solicitar o provisionamento, acesse Configurações de dados > Contas e preencha o questionário. Depois que o provisionamento for concluído, as permissões de chave de API de Objetos de dados aparecem em Configurações > Chaves de API. Para mais detalhes, consulte Ativar Contas.

Endpoints de tipo

Endpoints de objeto

Endpoints de relacionamento entre objetos

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 a visão geral da API da Braze.
Todas as cargas úteis de solicitação e resposta estão em JSON.
As solicitações são limitadas ao espaço de trabalho dono da chave de API.
Se a chave tiver uma lista de IPs permitidos, endereços IP fora dessa lista retornam 403.

Permissões da chave de API

Esta seção associa cada endpoint à 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 e objetos, e leitura 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`	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 a 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 o tráfego de leitura e de gravação.

Bucket	Limite padrão
Leituras de Objetos de dados	1000 solicitações por minuto
Gravações de Objetos de dados	1000 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 1000 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ê atinge um deles. Para saber como esses limites se aplicam aos registros de contas, consulte Limites de objetos de conta.

Limites de contagem

Esses limites se aplicam à sua empresa como um todo, salvo indicação em contrário. Eles são capacidades iniciais. Se você precisar de mais registros ou de um limite maior, entre em contato com a equipe de conta da Braze para solicitar um aumento.

Limite	Valor padrão
Registros de objetos de dados por empresa (em todos os espaços de trabalho)	50.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 entre objetos para um objeto de dados	1.000

Limites de campos e valores

Esses limites são fixos para todas as empresas.

Limite	Valor
Campos por tipo de relacionamento (relacionamentos de usuários e relacionamentos entre objetos)	25. Os campos de relacionamento não contam para o limite de campos por tipo de objeto de dados.
Comprimento do valor do atributo	255 caracteres
Comprimento e formato do `object_id`	250 caracteres. Apenas letras, números, hifens e sublinhados.
Comprimento e formato do nome do campo	250 caracteres. Apenas letras, números e sublinhados, e não pode começar com sublinhado.
Nomes de campos 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`
Campos por tipo de relacionamento	`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 entre objetos para um objeto de dados	`data-object-relationship-limit-exceeded`

Seus registros e relacionamentos existentes continuam no lugar. Apenas a solicitação que excederia o limite é rejeitada. Para liberar espaço dentro de um limite, exclua registros de que você não precisa mais ou remova relacionamentos que você não usa mais. Para aumentar um limite de contagem, entre em contato com a 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 principais

Esta seção define os principais identificadores 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.
user: O usuário em uma solicitação de gravação de relacionamento de usuário, identificado por exatamente um destes campos: external_id, braze_id, alias, email ou phone.
attributes: Dados do objeto ou do relacionamento, organizados por nome de campo e validados de acordo com 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 você consegue fazer na Braze ao vinculá-los. Você define os tipos no dashboard e depois 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

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. Elas são criadas, atualizadas e excluídas por meio destes endpoints da 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 entre objetos exigem `related_type_name`

O rel_kind não é único globalmente 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.
Por isso, as gravações de relacionamentos entre objetos exigem tanto rel_kind quanto related_type_name. Assim, é possível identificar o tipo de relacionamento pretendido junto com o outro tipo de objeto da associação.
Se o related_type_name não corresponder ao tipo de relacionamento daquele rel_kind, a solicitação retorna 400.

`anchor` controla a direção do relacionamento

Relacionamentos entre 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 caminhos para relacionamentos de usuários

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

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