Ir para o conteúdo

Criar ou substituir objetos de dados em massa

put

/data_objects/objects

Use este endpoint para criar ou substituir até 50 objetos de dados, de qualquer combinação de tipos, em uma única solicitação.

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 objeto de dados e ver a alteração na hora, use Substituir objeto de dados. Para saber quando usar cada um, consulte Endpoints em massa.

Pré-requisitos

Para usar este endpoint, você precisará de uma chave de API com a permissão data_objects.bulk_upsert. As permissões de registro único, como data_objects.create, não concedem acesso a este endpoint.

Limite de frequência

Este endpoint fica no bucket de gravação em massa do Data Objects, 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/objects.

Parâmetro Obrigatório Tipo de dados Descrição
records Obrigatório Array Os objetos de dados 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 O nome de máquina do tipo de objeto de dados. O tipo já precisa existir. Este endpoint nunca cria tipos.
records[].object_id Obrigatório String Seu identificador para o objeto, o mesmo valor de object_id nos caminhos dos endpoints de registro único
records[].attributes Obrigatório Objeto Os atributos do objeto, indexados pelo nome do campo. Cada campo já precisa estar definido no tipo.

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. A Braze confere se cada tipo existe 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 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 qualquer solicitação que o inclua. Quando duas solicitações alteram o mesmo objeto, prevalece a que a Braze recebeu por último, e a Braze ignora uma gravação mais antiga que chegue depois.
  • Os upserts não esperam. Um upsert de objeto nunca espera por outro registro. Um upsert recebido depois da exclusão do mesmo objeto recria esse objeto.

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": "account", "object_id": "acct-001", "attributes": {"name": "Acme"}},
    {"type_name": "opportunity", "object_id": "opp-001", "attributes": {"amount": 10}}
  ]
}

Exemplo de solicitação cURL

Este exemplo cria ou substitui um registro account e um registro opportunity na mesma solicitação.

curl --location --request PUT 'https://rest.iad-01.braze.com/data_objects/objects' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "records": [
    {"type_name": "account", "object_id": "acct-001", "attributes": {"name": "Acme"}},
    {"type_name": "opportunity", "object_id": "opp-001", "attributes": {"amount": 10}}
  ]
}'

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": 2
}

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 estes códigos pelo endpoint. Ela os registra para registros individuais quando processa um lote na fila.

Código Significado
data-object-type-not-found type_name não corresponde a nenhum tipo ativo no espaço de trabalho.
data-object-schema-mismatch Os attributes não correspondem aos campos do tipo. A mensagem indica cada atributo com problema.
data-object-ingestion-rejected Qualquer outra rejeição, como um object_id recusado.

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 em records, começando em 0).

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 que a Braze define (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 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.bulk_upsert e se o seu IP de origem está na lista de permissões da chave, caso esteja configurada.
404 O Data Objects 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 depois de X-RateLimit-Reset e reduza a frequência das solicitações.
500 Não foi possível aceitar o lote (internal-error) A Braze não aceitou nada, então é seguro tentar a solicitação novamente.
New Stuff!