Renomear ID externo

Use esse ponto de extremidade para renomear as IDs externas dos seus usuários.

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

Esse ponto de extremidade define um novo external_id (primário) para o usuário e substitui o external_id existente. Isso significa que o usuário pode ser identificado por 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 mais antigas de 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 externas obsoletas usando o ponto de extremidade/users/external_ids/remove .

Pré-requisitos

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

Limite de taxa

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

• O current_external_id deve ser o ID principal do usuário e não pode ser um ID obsoleto
• O endereço new_external_id não deve estar em uso como ID principal ou ID obsoleto
• Os sites current_external_id e new_external_id não podem ser os mesmos

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 renomeações malsucedidas com quaisquer erros associados. As mensagens de erro no campo rename_errors farão referência ao índice do objeto no vetor 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 no caso de:

• Chave de API inválida
• Matriz external_id_renames vazia
• external_id_renames vetor de objetos com mais de 50 objetos
• Limite de frequência atingido (mais de 1.000 solicitações/minuto)

Perguntas frequentes

Isso afeta o MAU?
Não, como o número de usuários permanecerá o mesmo, eles terão apenas um novo external_id.

O comportamento do usuário muda historicamente?
Não, pois o usuário ainda é o mesmo, e todo o seu comportamento histórico ainda está conectado a ele.

Ele pode ser executado em espaços de trabalho de desenvolvimento/estágio?
Sim. Na verdade, é altamente recomendável executar uma migração de teste em um espaço de trabalho de preparação ou desenvolvimento e garantir que tudo corra bem antes de executar nos dados de produção.

Isso consome pontos de dados?
Esse recurso não custa pontos de dados.

Qual é o período de depreciação recomendado?
Não temos um limite rígido de quanto tempo você pode manter IDs externas obsoletas, mas é altamente recomendável removê-las quando não houver mais necessidade de fazer referência aos usuários pela ID obsoleta.