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.

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 Data Objects 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 ficam restritas 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 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 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 com usuários
data_objects.user_relationships.create Criação de relacionamentos com usuários
data_objects.user_relationships.update Substituição e atualização de relacionamentos com usuários
data_objects.user_relationships.delete Exclusão de relacionamentos com 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
data_objects.bulk_upsert Criação ou substituição de objetos em massa
data_objects.bulk_delete Exclusão de objetos em massa
data_objects.object_relationships.bulk_upsert Criação ou substituição de relacionamentos entre objetos em massa
data_objects.object_relationships.bulk_delete Exclusão de relacionamentos entre objetos em massa
data_objects.user_relationships.bulk_upsert Criação ou substituição de relacionamentos com usuários em massa
data_objects.user_relationships.bulk_delete Exclusão de relacionamentos com usuários em massa

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 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
Gravações em massa de Objetos de dados 1000 solicitações por minuto, compartilhadas entre os seis endpoints em massa e com as sincronizações de objetos de dados da Cloud Data Ingestion

O limite de gravação em massa se aplica por espaço de trabalho e é separado do limite de gravação de registro único.

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 Data Objects e o que esperar quando você atinge um deles. Para saber como esses limites se aplicam aos registros de conta, consulte Limites de objetos de conta.

Limites de quantidade

Esses limites se aplicam à sua empresa como um todo, a menos que indicado de outra forma. Eles são capacidades iniciais. Se você precisar de mais registros ou de um limite maior, entre em contato com a equipe da sua conta 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ário e relacionamentos entre objetos) 25. Os campos de relacionamento não contam para o limite de campos por tipo de objeto de dados.
Tamanho do valor do atributo 255 caracteres
Campos de data Strings de data e hora no formato RFC 3339 que incluem hora e fuso horário, como 2026-11-03T00:00:00Z. A Braze rejeita valores só com data, como 2026-11-03. Para mais detalhes, consulte Formato do campo de data.
Tamanho e formato do object_id 250 caracteres. Apenas letras, números, hifens e sublinhados.
Tamanho e formato do nome do campo 250 caracteres. Apenas letras, números e sublinhados, e não pode começar com sublinhado.
Nomes de campo reservados id, external_id, object_id e display_name não podem ser usados como nomes de campos personalizados.

Formato do campo de data

Os campos de data aceitam apenas strings de data e hora no formato RFC 3339 que incluam hora e fuso horário. A Braze exige o valor completo para nunca precisar adivinhar uma hora ou um fuso horário. Se a sua fonte armazena valores só com data, como datas de renovação ou de contrato no seu data warehouse, converta esses valores antes de enviá-los. Por exemplo, faça isso na transformação do seu data warehouse.

Valor Resultado
2026-11-03T00:00:00Z Aceito
2026-11-03T00:00:00-05:00 Aceito
2026-11-03 Rejeitado porque não tem hora nem fuso horário
2026-11-03T00:00:00 Rejeitado porque não tem fuso horário

Esse formato se aplica aos campos de data em objetos de dados, relacionamentos de usuário e relacionamentos entre objetos. A forma como a Braze informa um valor rejeitado depende de como você o envia:

  • Os endpoints de registro único para criar, substituir e atualizar retornam 400. Se mais de um atributo for inválido, o erro cita apenas o primeiro.
  • Os endpoints de upsert em massa aceitam a solicitação com 202 e depois registram uma falha de processamento data-object-schema-mismatch para o registro, como attributes: renewal_date is not valid for its field.
  • As sincronizações da ingestão de dados na nuvem usam o mesmo processamento dos endpoints em massa. Então, a Braze não aplica uma linha com valor só de data, e a falha aparece nos logs de sincronização.

Por exemplo, uma solicitação de registro único que envia 2026-11-03 para um campo de data renewal_date retorna esta resposta 400:

{
  "error": "Validation failed: Attrs do not conform to field definitions: The property '#/renewal_date' must be a valid RFC3339 date/time string"
}

O que acontece quando você atinge um limite

Uma solicitação que excederia um limite de quantidade 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. Somente a solicitação que excederia o limite é rejeitada. Para liberar espaço dentro de um limite, exclua os registros de que você não precisa mais ou remova os relacionamentos que não usa mais. Para aumentar um limite de quantidade, entre em contato com a equipe da sua conta Braze.

Solicitações que falham na validação, como um object_id ou um 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 Data Objects.

  • 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, indexados pelo nome do 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 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 entender como tipos, registros e relacionamentos se encaixam e o que você pode fazer na Braze ao vinculá-los. Você define os tipos no dashboard e 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
  • O 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.
  • Por isso, 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 na 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

Os 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 do anchor oposto 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ário

As leituras e gravações de relacionamentos de usuário usam caminhos de endpoint diferentes de propósito:

  • 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 os atributos da aresta no campo attributes de nível superior.
  • Os atributos do 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:

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

Para consultar os vínculos:

  • 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

Endpoints em massa

Use os endpoints em massa para sincronizar objetos de dados, relacionamentos entre objetos e relacionamentos de usuários a partir dos seus próprios sistemas, em lotes. Cada solicitação cria, substitui ou exclui até 50 registros, e a Braze processa o lote em segundo plano.

Método Endpoint Finalidade
PUT /data_objects/objects Criar ou substituir até 50 objetos de dados, de qualquer combinação de tipos
DELETE /data_objects/objects Excluir até 50 objetos de dados, de qualquer combinação de tipos
PUT /data_objects/object_relationships Criar ou substituir até 50 relacionamentos entre objetos
DELETE /data_objects/object_relationships Excluir até 50 relacionamentos entre objetos
PUT /data_objects/user_relationships Criar ou substituir até 50 relacionamentos entre usuários e objetos
DELETE /data_objects/user_relationships Excluir até 50 relacionamentos entre usuários e objetos

Quando usar os endpoints em massa

Use os endpoints em massa quando você sincroniza muitos registros a partir dos seus próprios sistemas e não precisa que cada alteração seja aplicada antes de a resposta retornar. Use os endpoints de registro único quando precisar que a alteração fique visível na hora, quando precisar ler registros ou quando quiser atualizar apenas alguns atributos de um registro com PATCH.

Os endpoints em massa se diferenciam dos endpoints de registro único nos seguintes pontos:

  • O processamento é assíncrono. Uma resposta 202 significa que a Braze aceitou o lote e o colocou na fila, não que aplicou os registros. A Braze verifica se os tipos, os tipos de relacionamento, os objetos e os usuários existem, e se os atributos correspondem aos campos do tipo, quando processa o lote. Então, uma solicitação que retorna 202 ainda pode gerar falhas em registros individuais mais tarde.
  • A validação é do tipo tudo ou nada. Se qualquer registro de uma solicitação falhar na validação, a Braze rejeita a solicitação inteira com 400, não armazena nada e lista todos os erros.
  • Os registros são ordenados pelo horário de recebimento. A Braze marca cada registro com o horário em que recebeu a solicitação, então não envie updated_at. Quando duas solicitações alteram o mesmo registro, prevalece a que a Braze recebeu por último.
  • Os registros podem aguardar dependências. A exclusão de um objeto ou relacionamento que ainda não existe, e um relacionamento cujo objeto ou usuário ainda não existe, ficam em espera em vez de falhar na hora. A Braze tenta novamente por cerca de 40 horas (10 tentativas). Um upsert de objeto nunca fica em espera.
  • Os endpoints em massa usam suas próprias permissões de chave de API e compartilham um limite de frequência de 1.000 solicitações por minuto por espaço de trabalho.
  • Os endpoints em massa nunca criam tipos de objetos de dados. Todo type_name já precisa existir.

Os limites do produto se aplicam aos endpoints em massa da mesma forma que aos endpoints de registro único.

Paginação e atualização dos dados

Esta seção explica como funciona a paginação de listas e quando os dados ficam visíveis depois de uma gravação.

  • Os endpoints de listagem aceitam limit e offset.
  • O padrão de limit é 100, e o valor fica restrito ao intervalo de 1 a 250.
  • O padrão de offset é 0, e valores negativos são arredondados para 0.
  • Gravações de registro único ficam visíveis imediatamente para leituras e para a personalização com Liquid. As gravações em massa são aplicadas quando a Braze processa o lote na fila.
  • A associação a um Segment com base em objetos de dados pode atrasar até uma hora, porque os filtros calculados são atualizados a cada hora.

Comportamento de erros

Esta seção resume os padrões de status e de resposta de erro usados nos endpoints de objetos de dados.

  • 404, 409, 422 e 429 retornam um array errors com id e message.
  • 400, 401 e 403 retornam uma única string error.
  • Os endpoints em massa retornam os erros 400 e 500 como um array errors com id e message. Um erro 400 também inclui o parameter com problema, quando houver. Para erros no nível do registro, ele inclui ainda o index do registro.
  • 422 significa que a solicitação excederia um limite do produto. Os valores padrão dos limites variam de acordo com o contrato da empresa.

New Stuff!