Autenticar e acessar APIs da Experience Platform

Este documento fornece um tutorial passo a passo para obter acesso a uma conta de desenvolvedor do Adobe Experience Platform para fazer chamadas para APIs Experience Platform. No final deste tutorial, você terá gerado ou coletado as seguintes credenciais que são necessárias como cabeçalhos em todas as chamadas de API da plataforma:

Para manter a segurança de seus aplicativos e usuários, todas as solicitações para APIs Experience Platform devem ser autenticadas e autorizadas usando padrões como o OAuth.

Este tutorial aborda como coletar as credenciais necessárias para autenticar chamadas de API da plataforma, conforme descrito no fluxograma abaixo. Você pode coletar a maioria das credenciais necessárias na configuração inicial única. No entanto, o token de acesso deve ser atualizado a cada 24 horas.

Pré-requisitos prerequisites

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

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:

Obter acesso de desenvolvedor e usuário para o Experience Platform gain-developer-user-access

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

Obter acesso de desenvolvedor gain-developer-access

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

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

Obter acesso do usuário gain-user-access

O administrador do Admin Console também deve adicioná-lo como usuário ao mesmo perfil de produto. Com o acesso do usuário, é possível ver na interface do usuário o resultado das operações de API executadas.

Consulte o manual sobre gerenciamento de grupos de usuários em Admin Console para obter mais informações.

Gerar uma chave de API (ID do cliente) e uma ID da organização generate-credentials

Depois de receber acesso de desenvolvedor e usuário à Platform por meio do Admin Console, a próxima etapa é gerar suas credenciais do {ORG_ID} e do {API_KEY} no Adobe Developer Console. 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 add-platform-to-project

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

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

A tela Adicionar uma API é exibida. Selecione o ícone do produto para o Adobe Experience Platform e escolha Experience Platform API antes de selecionar Avançar.

Selecione o tipo de autenticação de Servidor para Servidor do OAuth select-oauth-server-to-server

Em seguida, selecione o tipo de autenticação OAuth Server-to-Server para gerar tokens de acesso e acessar a API de Experience Platform.

Selecione os perfis de produto para sua integração select-product-profiles

Na tela Configurar API, selecione AEP-Padrão-Todos-Usuários.

Selecione Salvar API configurada quando estiver pronto.

Uma apresentação das etapas descritas acima para configurar uma integração com a API de Experience Platform também está disponível no tutorial em vídeo abaixo:

Coletar credenciais gather-credentials

Depois que a API for adicionada ao projeto, a página APIs de Experience Platform do projeto exibirá as seguintes credenciais, necessárias em todas as chamadas para APIs de Experience Platform:

Gerar um token de acesso generate-access-token

A próxima etapa é gerar uma credencial {ACCESS_TOKEN} para uso em chamadas de API da plataforma. Diferentemente dos valores de {API_KEY} e {ORG_ID}, um novo token deve ser gerado a cada 24 horas para continuar usando as APIs da plataforma. Selecione Gerar token de acesso, como mostrado abaixo.

Criar e recuperar credenciais de autenticação diretamente na documentação de referência da API get-credentials-functionality

A partir da versão de novembro de 2024 do Experience Platform, você poderá obter credenciais para usar as APIs de Experience Platform diretamente das páginas de referência da API, sem precisar acessar o Developer Console. Veja o exemplo abaixo na página API de Serviço de Fluxo - Destinos.

Para obter credenciais para chamar APIs da plataforma, navegue até qualquer página de referência da API de Experience Platform e selecione Entrar na parte superior da página. Entre com sua Conta Pessoal ou Conta da Empresa ou Escola.

Depois de entrar, selecione Criar nova credencial para criar um novo conjunto de credenciais para acessar as APIs da plataforma.

Em seguida, use o seletor suspenso para abrir a janela de credenciais, gerar um token de acesso e obter a chave de API e a ID da organização. Copie as credenciais nos blocos Experimente-a nas páginas de referência da API para começar a trabalhar com APIs da Platform.

[Obsoleto]{class="badge informative"} Gerar um JSON Web Token (JWT) jwt

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}'

{
  "token_type": "bearer",
  "access_token": "{ACCESS_TOKEN}",
  "expires_in": 86399992
}

Testar credenciais de acesso test-credentials

Depois de coletar todas as três credenciais necessárias - token de acesso, chave de API e ID da organização - , você pode tentar fazer a seguinte chamada de API. Esta chamada lista todas as classes padrão Experience Data Model (XDM) disponíveis para sua organização. Importe e execute a chamada no Postman.

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: {{ORG_ID}}'

Resposta

Se sua resposta for semelhante à mostrada abaixo, suas credenciais serão válidas e estarão funcionando. (Esta resposta foi truncada por questões de 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"
    }
  ]
}

Obter as permissões necessárias de controle de acesso baseado em atributos get-abac-permissions

Para acessar ou modificar vários recursos no Experience Platform, você deve ter as permissões de controle de acesso apropriadas. Os administradores do sistema podem conceder a você as permissões necessárias. Obtenha mais informações na seção sobre gerenciamento de credenciais de API para uma função.

Informações detalhadas sobre como um administrador do sistema pode conceder as permissões necessárias para acessar os recursos da plataforma por meio da API também estão disponíveis no tutorial em vídeo abaixo:

Usar o Postman para autenticar e testar chamadas de API use-postman

O Postman é uma ferramenta popular que permite aos desenvolvedores explorar e testar as APIs RESTful. Você pode usar coleções e ambientes do Experience Platform Postman para acelerar seu trabalho com APIs de Experience Platform. Leia mais sobre como usar o Postman no Experience Platform e começar a usar coleções e ambientes.

Informações detalhadas sobre o uso do Postman com coleções e ambientes de Experience Platform também estão disponíveis nos tutoriais em vídeo abaixo:

Baixe e importe um ambiente do Postman para usar com APIs Experience Platform

Usar uma coleção do Postman para gerar tokens de acesso

Baixe a coleção do Identity Management Service Postman e assista ao vídeo abaixo para saber como gerar tokens de acesso.

Baixe coleções do Postman da API de Experience Platform e interaja com as APIs

Administradores do sistema: conceder controle de acesso a desenvolvedores e API com permissões de Experience Platform grant-developer-and-api-access-control

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

Adicionar desenvolvedores ao perfil do produto add-developers-to-product-profile

Vá para Admin Console e entre com sua Adobe ID.

Selecione Produtos e Adobe Experience Platform na lista de produtos.

Na guia Perfis de produto, selecione AEP-Padrão-Todos-Usuários. Como alternativa, use a barra de pesquisa para pesquisar o perfil de produto inserindo o nome.

Selecione a guia Desenvolvedores e selecione Adicionar desenvolvedor.

Insira o email ou nome de usuário do desenvolvedor. Um email ou nome de usuário válido exibirá os detalhes do desenvolvedor. Selecione Salvar.

O desenvolvedor foi adicionado com sucesso e aparece na guia Desenvolvedores.

Atribuir API a uma função

Um administrador do sistema pode atribuir APIs a funções na interface do usuário do Experience Platform.

Selecione Permissões e a função à qual você deseja adicionar a API. Selecione a guia Credenciais da API e selecione Adicionar credenciais de API.

Selecione a API que você deseja adicionar à função e selecione Salvar.

Você retornará à guia Credenciais da API, onde a API recém-adicionada está listada.

Recursos adicionais additional-resources

Consulte os recursos adicionais vinculados abaixo para obter mais ajuda para começar a usar as APIs de Experience Platform

Próximas etapas next-steps

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

Além dos valores de autenticação coletados neste tutorial, muitas APIs da Platform também exigem que uma {SANDBOX_NAME} válida seja fornecida como um cabeçalho. Consulte a visão geral das sandboxes para obter mais informações.