Renomear ID externo

Use esse endpoint para renomear os IDs externos dos seus usuários.

Você pode enviar até 50 objetos de renomeação por solicitação.

Esse endpoint define um novo external_id (primário) para o usuário e torna obsoleto o external_id existente. Isso significa que o usuário pode ser identificado por qualquer um dos external_id até que o obsoleto seja removido. Ter vários IDs externos permite um período de migração para que as versões legadas dos seus apps que usam o esquema de nomenclatura de ID externo anterior não sejam interrompidas.

Depois que o esquema de nomenclatura antigo não estiver mais em uso, é altamente recomendável remover IDs externos obsoletos usando o endpoint /users/external_ids/remove.

Aviso

Remova os IDs externos obsoletos com o endpoint /users/external_ids/remove em vez de /users/delete. O envio de uma solicitação para /users/delete com o ID externo obsoleto exclui totalmente o perfil do usuário e não pode ser desfeito.

Pré-requisitos

Para usar esse endpoint, você precisará de uma chave de API com a permissão users.external_ids.rename.

Limite de taxa

Aplicamos um limite de taxa de 1.000 solicitações por minuto a esse endpoint, conforme documentado em Limites de taxa da API.

Corpo da solicitação

1
2
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY

1
2
3
{
  "external_id_renames" : (required, array of external ID rename objects)
}

Parâmetros de solicitação

Observe o seguinte:

• O current_external_id deve ser o ID principal do usuário e não pode ser um ID obsoleto.
• O new_external_id não deve estar em uso como ID primário ou ID obsoleto.
• O current_external_id e o new_external_id não podem ser iguais.

Exemplo de solicitação

1
2
3
4
5
6
7
8
9
10
11
curl --location --request POST 'https://rest.iad-01.braze.com/users/external_ids/rename' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "external_id_renames" :[
    {
      "current_external_id": "existing_external_id",
      "new_external_id" : "new_external_id"
    }
  ]
}'

Resposta

A resposta confirmará todas as renomeações bem-sucedidas, bem como as malsucedidas com quaisquer erros associados. As mensagens de erro no campo rename_errors farão referência ao índice do objeto no array da solicitação original.

1
2
3
4
5
{
  "message" : (string) status message,
  "external_ids" : (array of strings) successful rename operations,
  "rename_errors": (array of arrays) <minor error message>
}

O campo message retornará success para qualquer solicitação válida. Erros mais específicos são capturados no array rename_errors. O campo message retorna um erro nos seguintes casos:

• Chave de API inválida
• Array external_id_renames vazio
• Array external_id_renames com mais de 50 objetos
• Limite de taxa atingido (mais de 1.000 solicitações por minuto)

Perguntas frequentes

Isso afeta o MAU?

Não, porque o número de usuários permanece o mesmo — eles apenas passam a ter um novo external_id.

O comportamento do usuário muda historicamente?

Não, porque o usuário ainda é o mesmo, e todo o seu comportamento histórico continua conectado a ele.

Pode ser executado em espaços de trabalho de desenvolvimento ou de staging?

Sim. Na verdade, é altamente recomendável executar uma migração de teste em um espaço de trabalho de staging ou desenvolvimento e garantir que tudo ocorra bem antes de executar nos dados de produção.

Isso registra pontos de dados?

Esse recurso não registra pontos de dados.

Qual é o período de descontinuação recomendado?

Não temos um limite rígido de quanto tempo você pode manter IDs externos obsoletos, mas é altamente recomendável removê-los quando não houver mais necessidade de fazer referência aos usuários pelo ID obsoleto.