Show Menu
TÓPICOS×

Guia do desenvolvedor da API do Serviço de Identidade

O Adobe Experience Platform Identity Service gerencia a identificação entre dispositivos, canais cruzados e quase em tempo real de seus clientes no que é conhecido como um gráfico de identidade na Adobe Experience Platform.

Introdução

Este guia exige uma compreensão prática dos seguintes componentes da Adobe Experience Platform:
  • Serviço de identidade: Resolve o desafio fundamental colocado pela fragmentação dos dados do perfil do cliente. Ele faz isso ao fazer a ponte de identidades entre dispositivos e sistemas nos quais os clientes interagem com sua marca.
  • Perfil do cliente em tempo real: Fornece um perfil unificado e de consumidor em tempo real, com base em dados agregados de várias fontes.
  • Modelo de dados de experiência (XDM) : A estrutura padronizada pela qual a Plataforma organiza os dados de experiência do cliente.
As seções a seguir fornecem informações adicionais que você precisará conhecer ou ter em mãos para fazer chamadas à API do serviço de identidade com êxito.

Lendo chamadas de exemplo da API

Este guia fornece exemplos de chamadas de API para demonstrar como formatar suas solicitações. Isso inclui caminhos, cabeçalhos necessários e cargas de solicitação formatadas corretamente. O JSON de amostra retornado em respostas de API também é fornecido. Para obter informações sobre as convenções usadas na documentação para chamadas de API de amostra, consulte a seção sobre como ler chamadas de API de exemplo no guia de solução de problemas da plataforma Experience.

Reunir valores para cabeçalhos necessários

Para fazer chamadas para APIs de plataforma, você deve primeiro concluir o tutorial de autenticação. A conclusão do tutorial de autenticação fornece os valores para cada um dos cabeçalhos necessários em todas as chamadas da API da plataforma da experiência, como mostrado abaixo:
  • Autorização: Portador {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}
Todos os recursos da plataforma Experience são isolados para caixas de proteção virtuais específicas. Todas as solicitações para APIs de plataforma exigem um cabeçalho que especifique o nome da caixa de proteção em que a operação ocorrerá:
  • x-sandbox-name: {SANDBOX_NAME}
Para obter mais informações sobre caixas de proteção na Plataforma, consulte a documentação de visão geral da caixa de proteção.
Todas as solicitações que contêm uma carga (POST, PUT, PATCH) exigem um cabeçalho adicional:
  • Tipo de conteúdo: application/json

roteamento baseado na região

A API do Serviço de Identidade emprega endpoints específicos da região que exigem a inclusão de um {REGION} como parte do caminho da solicitação. Durante o provisionamento da organização IMS, uma região é determinada e armazenada no perfil de organização IMS. Usar a região correta com cada endpoint garante que todas as solicitações feitas usando a API do Serviço de Identidade sejam encaminhadas para a região apropriada.
Existem duas regiões atualmente suportadas pelas APIs do Serviço de Identidade: VA7 e NLD2.
A tabela abaixo mostra os caminhos de exemplo usando regiões:
Serviço de
Região: VA7
Região: NLD2
API do Serviço de Identidade
https://platform-va7.adobe.io/data/core/identity/
https://platform-nld2.adobe.io/data/core/identity/
API de Namespace de identidade
https://platform-va7.adobe.io/data/core/idnamespace/
https://platform-nld2.adobe.io/data/core/idnamespace
As solicitações feitas sem especificar uma região podem resultar no roteamento de chamadas para a região incorreta ou causar falhas inesperadas de chamadas.
Se você não conseguir localizar a região dentro do perfil IMS Org, entre em contato com o administrador do sistema para obter suporte.

Uso da API do Serviço de identidade

Os parâmetros de identidade utilizados nestes serviços podem ser expressos de duas formas; composto ou XID.
Identidades compostas são construções que incluem o valor da ID e a namespace. Ao usar identidades compostas, a namespace pode ser fornecida pelo nome ( namespace.code ) ou ID ( namespace.id ).
Quando uma identidade é persistente, o Serviço de identidade gera e atribui uma ID a essa identidade, chamada de ID nativa ou XID. Todas as variações das APIs de cluster e mapeamento suportam identidades compostas e XID em suas solicitações e respostas. Um dos parâmetros é necessário - xid ou combinação de # e id para usar essas APIs.
Para limitar a carga em respostas, as APIs adaptam suas respostas ao tipo de construção de identidade usada. Ou seja, se você passar o XID suas respostas terão XIDs, se você passar identidades compostas, a resposta seguirá a estrutura usada na solicitação.
Os exemplos neste documento não abrangem a funcionalidade completa da API do serviço de identidade. Para obter a API completa, consulte a Referência da API do Swagger.
Todas as identidades retornadas estarão no formulário XID nativo quando o XID nativo for usado na solicitação. É recomendável usar o formulário de ID/namespace. Para obter mais informações, consulte a seção sobre como obter o XID de uma identidade .

Próximas etapas

Agora que você reuniu as credenciais necessárias, pode continuar a ler o restante do guia do desenvolvedor. Cada seção fornece informações importantes sobre seus pontos de extremidade e demonstra exemplos de chamadas de API para executar operações CRUD. Cada chamada inclui o formato geral da API, uma solicitação de amostra mostrando os cabeçalhos necessários e cargas formatadas corretamente e uma resposta de amostra para uma chamada bem-sucedida.