Ir para o conteúdo

Excluir relacionamentos de usuários em massa

delete

/data_objects/user_relationships

Use este endpoint para excluir até 50 relacionamentos entre usuários e objetos em uma única solicitação.

A Braze aceita a solicitação e a processa em segundo plano. Uma resposta 202 significa que o lote está na fila, e não que já foi aplicado. Para excluir um único relacionamento e ver a alteração imediatamente, use Excluir relacionamento de usuário. 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.user_relationships.bulk_delete. As permissões de registro único, como data_objects.user_relationships.delete, não dão acesso a este endpoint.

Limite de frequência

Este endpoint faz parte do 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. Esse limite é compartilhado entre os seis endpoints em massa e com as sincronizações de data objects do 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/user_relationships.

Parâmetro Obrigatório Tipo de dados Descrição
records Obrigatório Array Os relacionamentos de usuários a serem excluí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 ao qual o usuário está vinculado
records[].object_id Obrigatório String Identificador do objeto ao qual o usuário está vinculado
records[].rel_kind Obrigatório String Nome do tipo de relacionamento
records[].user Obrigatório Objeto O usuário vinculado. Deve conter exatamente um destes: external_id, braze_id, email, phone ou alias. Enviar nenhum ou mais de um gera um erro.
records[].user.external_id Opcional String O ID externo do usuário
records[].user.braze_id Opcional String O ID de usuário da Braze
records[].user.email Opcional String O endereço de e-mail do usuário
records[].user.phone Opcional String O número de telefone do usuário
records[].user.alias Opcional Objeto Objeto de alias de usuário com alias_name e alias_label (ambos obrigatórios quando usado)

Quando um endereço de e-mail ou número de telefone corresponde a mais de um usuário, as regras padrão de seleção de perfil da Braze decidem qual usuário é afetado.

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 completa.
  • As consultas acontecem durante o processamento. A Braze verifica se o tipo, o tipo de relacionamento, o objeto, o usuário e o relacionamento existem quando processa o lote. Portanto, 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 solicitações que incluam esse campo. Quando duas solicitações alteram o mesmo relacionamento, prevalece a que a Braze recebeu por último, e a Braze ignora uma gravação mais antiga que chegue depois.
  • As exclusões podem aguardar. A exclusão de um relacionamento que ainda não existe fica aguardando em vez de falhar imediatamente. A Braze tenta novamente por cerca de 40 horas (10 tentativas). Se o relacionamento 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": "account", "object_id": "acct-001", "rel_kind": "owns", "user": {"external_id": "user-1"}}
  ]
}

Exemplo de solicitação cURL

Este exemplo remove o relacionamento owns entre o usuário com ID externo user-1 e acct-001. O perfil de usuário e o registro da conta continuam existindo.

curl --location --request DELETE 'https://rest.iad-01.braze.com/data_objects/user_relationships' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "records": [
    {"type_name": "account", "object_id": "acct-001", "rel_kind": "owns", "user": {"external_id": "user-1"}}
  ]
}'

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 pelo endpoint. Ela os registra para registros individuais ao processar 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-relationship-type-not-found rel_kind não corresponde a nenhum tipo de relacionamento ativo para esse tipo.
data-object-invalid-user-identifier O identificador de usuário não pode ser usado para encontrar um usuário.
data-object-ingestion-rejected Qualquer outra rejeição.
data-object-dependency-not-found O relacionamento ainda não existia 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). O parameter usa os nomes da sua solicitação, como user.external_id.

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), tem um campo do tipo errado ou uma string vazia, ou tem um objeto user com mais de um identificador Corrija todos os registros listados e reenvie a solicitação completa.
400 Identificador de usuário ausente (missing-user-identifier): o user de um registro não tem identificador Envie exatamente um identificador no user de cada registro.
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.user_relationships.bulk_delete e se o 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 o seu espaço de trabalho está provisionado para Accounts.
429 Limite de frequência excedido Tente novamente após 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!