Endpoints de objetos personalizados

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

Importante

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

Endpoints de tipos

Endpoints de objetos

Endpoints de relacionamentos de objeto

Endpoints de relacionamentos 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 personalizados estão hospedados e como as solicitações são autenticadas.

Para hosts de endpoints, consulte a visão geral da API da Braze.
Todas as cargas úteis de solicitação e resposta são JSON.
As solicitações estã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 não autorizados retornam 403.

Permissões de chave de API

Esta seção mapeia 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
`custom_objects.read`	Leituras de tipos e objetos, e leituras de relacionamentos de objeto
`custom_objects.create`	Criação de objetos
`custom_objects.update`	Substituição e atualização de objetos
`custom_objects.delete`	Exclusão de objetos
`custom_objects.user_relationships.read`	Leituras de relacionamentos de usuário
`custom_objects.user_relationships.create`	Criação de relacionamentos de usuário
`custom_objects.user_relationships.update`	Substituição e atualização de relacionamentos de usuário
`custom_objects.user_relationships.delete`	Exclusão de relacionamentos de usuário
`custom_objects.object_relationships.create`	Criação de relacionamentos de objeto
`custom_objects.object_relationships.update`	Substituição e atualização de relacionamentos de objeto
`custom_objects.object_relationships.delete`	Exclusão de relacionamentos de objeto

Nota

As leituras de relacionamentos de objeto usam custom_objects.read. Não existe uma permissão custom_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 escrita.

Bucket	Limite padrão
Leituras de objetos personalizados	50 solicitações por minuto
Escritas de objetos personalizados	50 solicitações por minuto

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

Para solicitações limitadas por taxa, 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."
    }
  ]
}

Conceitos principais

Esta seção define os identificadores principais usados em todos os endpoints de objetos personalizados.

type_name: o nome de máquina do tipo de objeto personalizado, único dentro de um espaço de trabalho.
external_id: seu identificador de objeto, único dentro de um tipo.
braze_id: o ID de usuário da Braze usado nos endpoints de relacionamento de usuário.
attributes: dados de objeto ou relacionamento organizados por nome de campo, validados conforme o esquema configurado.

Como os relacionamentos funcionam

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

Modelo de relacionamento em resumo

Use este diagrama para ver como tipos, registros e relacionamentos se encaixam, e o que a vinculação entre eles permite fazer na Braze. Você define os tipos no dashboard e então 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["Custom 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 /custom_objects/types/{type_name}/user_relationship_types
- GET /custom_objects/types/{type_name}/object_relationship_types

Por que relacionamentos de objeto exigem `related_type_name`

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.
Portanto, as escritas de relacionamento de objeto 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 objeto 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_custom_object`
`target`	Lado de destino (aresta de entrada)	`from_custom_object`

Criar a mesma aresta pela 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ário

As leituras e escritas de relacionamentos de usuário usam caminhos de endpoint diferentes intencionalmente:

Leitura: GET /custom_objects/objects/{type_name}/{external_id}/user_relationships
Escrita: POST|PUT|PATCH|DELETE /custom_objects/objects/{type_name}/{external_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 permanecem aninhados em to_custom_object ou from_custom_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:

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

Para ler os vínculos de volta:

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