Criar ou substituir relacionamentos de objetos em massa
/data_objects/object_relationships
Use este endpoint para criar ou substituir até 50 relacionamentos entre objetos em uma única solicitação.

Objetos de dados está em disponibilidade geral, mas seu espaço de trabalho precisa estar provisionado para Contas antes que você possa usar este endpoint. Para solicitar o provisionamento, acesse Configurações de dados > Contas e preencha o questionário. Para saber mais, consulte Ativar contas.
A Braze aceita a solicitação e a processa em segundo plano. Uma resposta 202 significa que o lote foi colocado na fila, não que foi aplicado. Para alterar um único relacionamento e ver a alteração imediatamente, use Substituir relacionamento de objeto. Para saber quando usar cada um, consulte Endpoints em massa.
Pré-requisitos
Para usar este endpoint, você precisa de uma chave de API com a permissão data_objects.object_relationships.bulk_upsert. As permissões de registro único, como data_objects.object_relationships.create, não concedem acesso a este endpoint.
Limite de frequência
Este endpoint faz parte do bucket de gravação em massa de Objetos de dados, com um limite padrão de 1.000 solicitações por minuto por espaço de trabalho. O limite é compartilhado entre os seis endpoints em massa e com as sincronizações de objetos de dados da ingestão de dados na nuvem (Cloud Data Ingestion). Ele é separado do limite de gravação de registro único.
Parâmetros de solicitação
A tabela a seguir lista e descreve os parâmetros do corpo da solicitação JSON para o endpoint /data_objects/object_relationships.
| Parâmetro | Obrigatório | Tipo de dados | Descrição |
|---|---|---|---|
records |
Obrigatório | Array | Os relacionamentos de objetos a serem criados ou substituídos. Deve conter de 1 a 50 registros. A Braze rejeita qualquer outro campo de nível superior. |
records[].type_name |
Obrigatório | String | Tipo do objeto de origem |
records[].object_id |
Obrigatório | String | Identificador do objeto de origem |
records[].rel_kind |
Obrigatório | String | Nome do tipo de relacionamento. Para listar os valores válidos, use Listar tipos de relacionamento de objetos. |
records[].related_type_name |
Obrigatório | String | Tipo do objeto de destino |
records[].related_object_id |
Obrigatório | String | Identificador do objeto de destino |
records[].attributes |
Obrigatório | Objeto | Atributos do relacionamento, indexados pelo nome do campo. Envie {} se o tipo de relacionamento não tiver nenhum. |
Como a Braze processa o lote
- A validação é tudo ou nada. Se algum registro falhar na validação, a Braze rejeita a solicitação inteira com
400, não armazena nada e lista todos os erros. Corrija os erros e reenvie a solicitação inteira. - As verificações acontecem durante o processamento. Ao processar o lote, a Braze verifica se os tipos, o tipo de relacionamento e os objetos existem, e se os atributos correspondem aos campos do tipo de relacionamento. Uma solicitação que retorna
202ainda pode gerar falhas em registros individuais depois. Consulte Falhas de processamento. - 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. A Braze rejeita solicitações que o incluam. Quando duas solicitações alteram o mesmo relacionamento, prevalece a que a Braze recebeu por último. Se uma gravação mais antiga chegar depois, a Braze a ignora. - Os relacionamentos podem aguardar seus objetos. Um relacionamento cujo objeto de origem ou de destino ainda não existe fica aguardando em vez de falhar imediatamente. A Braze tenta novamente por cerca de 40 horas (10 tentativas). Se o objeto ainda não existir depois disso, o registro falha com
data-object-dependency-not-found.
Exemplo de solicitação
Esta seção inclui um exemplo de carga útil JSON e um exemplo de solicitação cURL.
Exemplo de carga útil da solicitação
{
"records": [
{
"type_name": "contact",
"object_id": "contact-001",
"rel_kind": "works_at",
"related_type_name": "account",
"related_object_id": "acct-001",
"attributes": {"since": "2024-01-15T00:00:00Z"}
}
]
}
Exemplo de solicitação cURL
Este exemplo vincula contact-001 a acct-001 com o tipo de relacionamento works_at e registra quando o relacionamento começou.
curl --location --request PUT 'https://rest.iad-01.braze.com/data_objects/object_relationships' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"records": [
{
"type_name": "contact",
"object_id": "contact-001",
"rel_kind": "works_at",
"related_type_name": "account",
"related_object_id": "acct-001",
"attributes": {"since": "2024-01-15T00:00:00Z"}
}
]
}'
Resposta
Esta seção inclui um exemplo de resposta bem-sucedida e os campos da resposta.
Exemplo de resposta bem-sucedida
O código de status 202 pode retornar o seguinte corpo de resposta.
{
"source_import_id": "api-20261022T153012123456-9f3a1c2b",
"status": "queued",
"record_count": 1
}
Parâmetros de resposta
A tabela a seguir lista e descreve os campos de uma resposta bem-sucedida.
| Parâmetro | Obrigatório | Tipo de dados | Descrição |
|---|---|---|---|
source_import_id |
Obrigatório | String | O identificador que a Braze gerou para esta solicitação. Cada solicitação é uma importação própria. |
status |
Obrigatório | String | Sempre queued. O lote foi aceito e está aguardando processamento. |
record_count |
Obrigatório | Inteiro | O número de registros na solicitação |
Falhas de processamento
A Braze não retorna esses códigos a partir do endpoint. Ela os registra para registros individuais ao processar um lote na fila.
| Código | Significado |
|---|---|
data-object-type-not-found |
type_name ou related_type_name não corresponde a nenhum tipo ativo no espaço de trabalho. |
data-object-relationship-type-not-found |
rel_kind não corresponde a nenhum tipo de relacionamento ativo para esses tipos. |
data-object-schema-mismatch |
attributes não correspondem aos campos do tipo de relacionamento. A mensagem indica cada atributo com problema. |
data-object-ingestion-rejected |
Qualquer outra rejeição. |
data-object-dependency-not-found |
O objeto de origem ou de destino ainda estava ausente após cerca de 40 horas de novas tentativas. |
Erros
Uma resposta 400 significa que a Braze não armazenou nada. Cada erro tem um id, uma message, o parameter com problema (quando houver) e, para erros no nível do registro, o index do registro (sua posição, começando em 0, em records).
{
"errors": [
{"index": 0, "id": "schema-mismatch", "parameter": "rel_kind", "message": "rel_kind is required"}
]
}
A tabela a seguir lista os erros comuns deste endpoint e como resolvê-los.
| Status | Causa | Orientação |
|---|---|---|
400 |
Solicitação inválida (invalid-request): o corpo não é um objeto JSON ou é um JSON malformado, records está ausente ou tem menos de 1 ou mais de 50 entradas, ou o corpo contém um campo definido pela Braze (source_type, source_import_id, source_chunk_id ou record_type) |
Envie um objeto JSON cujo único campo seja records, com 1 a 50 registros. |
400 |
Incompatibilidade de esquema (schema-mismatch): um registro não tem um campo obrigatório, tem um campo não reconhecido (incluindo updated_at) ou tem um campo do tipo errado ou com uma string vazia |
Corrija todos os registros listados e reenvie a solicitação inteira. |
401 |
Chave da API REST ausente ou inválida | Verifique se o cabeçalho Authorization usa Bearer YOUR_REST_API_KEY e se a chave está ativa. |
403 |
A chave de API não tem permissão ou a solicitação foi bloqueada pela lista de permissões | Confirme se a chave tem data_objects.object_relationships.bulk_upsert e se o IP de origem está na lista de permissões da chave, caso esteja configurada. |
404 |
Objetos de dados não está ativado para sua empresa | Confirme se seu espaço de trabalho está provisionado para Contas. |
429 |
Limite de frequência excedido | Tente novamente após X-RateLimit-Reset e reduza a frequência das solicitações. |
500 |
O lote não pôde ser aceito (internal-error) |
A Braze não aceitou nada, então é seguro tentar a solicitação novamente. |