Autenticar e acessar APIs da Experience Platform

Este documento fornece um tutorial passo a passo para obter acesso a uma conta de desenvolvedor da Adobe Experience Platform para fazer chamadas para APIs da Experience Platform. No final deste tutorial, você gerou as seguintes credenciais necessárias para todas as chamadas de API da plataforma:

  • {ACCESS_TOKEN}
  • {API_KEY}
  • {IMS_ORG}

Para manter a segurança de seus aplicativos e usuários, todas as solicitações para APIs do Adobe I/O devem ser autenticadas e autorizadas usando padrões como OAuth e JSON Web Tokens (JWT). Um JWT é usado junto com informações específicas do cliente para gerar seu token de acesso pessoal.

Este tutorial aborda como coletar as credenciais necessárias para autenticar chamadas da API do Platform, conforme descrito no fluxograma a seguir:

Pré-requisitos

Para fazer chamadas com êxito para APIs do Experience Platform, você deve ter o seguinte:

  • Uma Organização IMS com acesso à Adobe Experience Platform.
  • Um administrador do Admin Console que pode adicioná-lo como desenvolvedor e como usuário para um perfil de produto.

Você também deve ter uma Adobe ID para concluir este tutorial. Se você não tiver uma Adobe ID, poderá criar uma usando as seguintes etapas:

  1. Ir para Console do desenvolvedor do Adobe.
  2. Selecionar Criar uma nova conta.
  3. Conclua o processo de inscrição.

Obter acesso de desenvolvedor e usuário para o Experience Platform

Antes de criar integrações no Console do desenvolvedor do Adobe, sua conta deve ter permissões de desenvolvedor e de usuário para um perfil de produto do Experience Platform no Adobe Admin Console.

Obter acesso do desenvolvedor

Entre em contato com um Admin Console administrador em sua organização para adicioná-lo como desenvolvedor a um perfil de produto do Experience Platform usando o Admin Console. Consulte a Admin Console documentação para obter instruções específicas sobre como gerenciar o acesso do desenvolvedor para perfis de produtos.

Depois de ser atribuído como um desenvolvedor, você pode começar a criar integrações no Console do desenvolvedor do Adobe. Essas integrações são um pipeline de aplicativos e serviços externos para APIs do Adobe.

Obter acesso do usuário

Seu Admin Console O administrador também deve adicioná-lo como usuário ao mesmo perfil de produto. Consulte o guia sobre gerenciamento de grupos de usuários no Admin Console para obter mais informações.

Gerar uma chave de API, ID de organização IMS e segredo do cliente

OBSERVAÇÃO

Se você estiver seguindo este documento da Guia da API do Privacy Service, agora você pode retornar a esse guia para gerar as credenciais de acesso exclusivas do Privacy Service.

Depois de ter recebido acesso de desenvolvedor e usuário à Platform por meio de Admin Console, a próxima etapa é gerar {IMS_ORG} e {API_KEY} credenciais no Console do desenvolvedor do Adobe. Essas credenciais só precisam ser geradas uma vez e podem ser reutilizadas em chamadas futuras da API da plataforma.

Adicionar Experience Platform a um projeto

Acesse o Adobe Developer Console e faça logon com seu Adobe ID. Em seguida, siga as etapas descritas no tutorial em criação de um projeto vazio na documentação do Console do desenvolvedor do Adobe.

Depois de criar um novo projeto, selecione Adicionar API no Visão geral do projeto tela.

A tela Adicionar uma API é exibida. Selecione o ícone do produto para Adobe Experience Platform e escolha API Experience Platform antes de selecionar Próximo.

A partir daqui, siga as etapas descritas no tutorial em adicionar uma API a um projeto usando uma conta de serviço (JWT) (começando pela etapa "Configurar API") para concluir o processo.

IMPORTANTE

Em uma determinada etapa durante o processo vinculado acima, o navegador baixa automaticamente uma chave privada e um certificado público associado. Observe onde essa chave privada é armazenada em sua máquina, já que é necessária em uma etapa posterior deste tutorial.

Obter credenciais

Depois que a API for adicionada ao projeto, a variável API Experience Platform para o projeto exibe as credenciais a seguir, que são necessárias em todas as chamadas para APIs do Experience Platform:

  • {API_KEY} (ID do cliente)
  • {IMS_ORG} (ID da organização)

Além das credenciais acima, você também precisa do Segredo do cliente para uma etapa futura. Selecionar Recuperar segredo do cliente para revelar o valor e, em seguida, copiá-lo para uso posterior.

Gerar um JSON Web Token (JWT)

A próxima etapa é gerar um JSON Web Token (JWT) com base em suas credenciais de conta. Esse valor é usado para gerar {ACCESS_TOKEN} credencial para uso em chamadas da API da plataforma, que devem ser geradas novamente a cada 24 horas.

Selecionar Conta de serviço (JWT) na navegação à esquerda, selecione Gerar JWT.

Na caixa de texto fornecida em Gerar JWT personalizado, cole o conteúdo da chave privada gerada anteriormente ao adicionar a API da plataforma à conta de serviço. Em seguida, selecione Gerar token.

A página é atualizada para mostrar o JWT gerado, juntamente com um comando cURL de amostra que permite gerar um token de acesso. Para fins deste tutorial, selecione Copiar ao lado de JWT gerado para copiar o token para a área de transferência.

Gerar um token de acesso

Depois de gerar uma JWT, você pode usá-la em uma chamada de API para gerar {ACCESS_TOKEN}. Diferente dos valores de {API_KEY} e {IMS_ORG}, um novo token deve ser gerado a cada 24 horas para continuar usando as APIs da plataforma.

Solicitação

A solicitação a seguir gera um novo {ACCESS_TOKEN} com base nas credenciais fornecidas no payload. Esse ponto de extremidade aceita apenas dados de formulário como sua carga, e portanto deve receber uma Content-Type cabeçalho de multipart/form-data.

curl -X POST https://ims-na1.adobelogin.com/ims/exchange/jwt \
  -H 'Content-Type: multipart/form-data' \
  -F 'client_id={API_KEY}' \
  -F 'client_secret={SECRET}' \
  -F 'jwt_token={JWT}'
Propriedade Descrição
{API_KEY} O {API_KEY} (ID do cliente) que você recuperou em um etapa anterior.
{SECRET} O segredo do cliente que você recuperou em um etapa anterior.
{JWT} O JWT gerado em um etapa anterior.
OBSERVAÇÃO

Você pode usar a mesma chave de API, segredo do cliente e JWT para gerar um novo token de acesso para cada sessão. Isso permite automatizar a geração de token de acesso em seus aplicativos.

Resposta

{
  "token_type": "bearer",
  "access_token": "{ACCESS_TOKEN}",
  "expires_in": 86399992
}
Propriedade Descrição
token_type O tipo de token que está sendo retornado. Para tokens de acesso, esse valor é sempre bearer.
access_token O {ACCESS_TOKEN}. Esse valor, com o prefixo da palavra Bearer, é obrigatório como Authentication para todas as chamadas de API do Platform.
expires_in O número de milissegundos restantes até o token de acesso expirar. Quando esse valor atingir 0, um novo token de acesso deverá ser gerado para continuar usando as APIs da plataforma.

Testar credenciais de acesso

Depois de reunir todas as três credenciais necessárias, tente fazer a seguinte chamada de API. Esta chamada lista todos os padrões Experience Data Model (XDM) classes disponíveis para sua organização.

Solicitação

curl -X GET https://platform.adobe.io/data/foundation/schemaregistry/global/classes \
  -H 'Accept: application/vnd.adobe.xed-id+json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}'

Resposta

Se sua resposta for semelhante à mostrada abaixo, suas credenciais serão válidas e funcionarão. (Essa resposta foi truncada para espaço.)

{
  "results": [
    {
        "title": "XDM ExperienceEvent",
        "$id": "https://ns.adobe.com/xdm/context/experienceevent",
        "meta:altId": "_xdm.context.experienceevent",
        "version": "1"
    },
    {
        "title": "XDM Individual Profile",
        "$id": "https://ns.adobe.com/xdm/context/profile",
        "meta:altId": "_xdm.context.profile",
        "version": "1"
    }
  ]
}

Use o Postman para autenticar e testar chamadas da API

Postman O é uma ferramenta popular que permite aos desenvolvedores explorar e testar RESTful APIs. Essa Postagem média descreve como você pode configurar o Postman para executar automaticamente a autenticação JWT e usá-la para consumir APIs da plataforma.

Próximas etapas

Ao ler este documento, você reuniu e testou com êxito suas credenciais de acesso para APIs da plataforma. Agora você pode seguir com o exemplo de chamadas de API fornecidas durante a documentação.

Além dos valores de autenticação coletados neste tutorial, muitas APIs da plataforma também exigem um {SANDBOX_NAME} a ser fornecido como um cabeçalho. Consulte a visão geral das sandboxes para obter mais informações.

Nesta página