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. Ao final deste tutorial, você terá gerado as seguintes credenciais, necessárias para todas as chamadas de API da plataforma:

  • {ACCESS_TOKEN}
  • {API_KEY}
  • {ORG_ID}

Para manter a segurança de seus aplicativos e usuários, todas as solicitações para APIs 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 de API da plataforma, conforme descrito no seguinte fluxograma:

Pré-requisitos

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

  • Uma organização com acesso ao Adobe Experience Platform.
  • Um administrador de Admin Console que pode adicioná-lo como desenvolvedor e 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 Adobe Developer.
  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 Adobe Developer, 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

Entre em contato com um Admin Console administrador na organização para adicioná-lo como desenvolvedor a um perfil de produto Experience Platform usando o Admin Console. Consulte a 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 Console do Adobe Developer. Essas integrações são um pipeline de aplicativos e serviços externos para APIs 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, uma ID da organização e um segredo do cliente

OBSERVAÇÃO

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

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

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 de produto do Adobe Experience Platform e escolha API EXPERIENCE PLATFORM antes de selecionar Próxima.

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 na etapa "Configurar API") para concluir o processo.

IMPORTANTE

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

Coletar credenciais

Depois que a API for adicionada ao projeto, o API EXPERIENCE PLATFORM A página do projeto exibe as seguintes credenciais que são necessárias em todas as chamadas para as APIs Experience Platform:

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

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

Gerar um JSON Web Token (JWT)

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

IMPORTANTE

Para os fins deste tutorial, as etapas abaixo descrevem como gerar um JWT no Console do desenvolvedor. No entanto, esse método de geração só deve ser usado para fins de teste e avaliação.

Para uso regular, o JWT deve ser gerado automaticamente. Para obter mais informações sobre como gerar JWTs programaticamente, consulte guia de autenticação da conta de serviço no Adobe Developer.

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 à sua 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 os 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 um JWT, você pode usá-lo em uma chamada de API para gerar {ACCESS_TOKEN}. Ao contrário 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.

Solicitação

A solicitação a seguir gera um novo {ACCESS_TOKEN} com base nas credenciais fornecidas na carga. Esse endpoint só aceita dados de formulário como sua carga, portanto, deve receber um 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} A variável {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 gerado {ACCESS_TOKEN}. Este valor, com prefixo da palavra Bearer, é obrigatório como a Authentication para todas as chamadas de API da plataforma.
expires_in O número de milissegundos restantes até que o token de acesso expire. 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 coletar todas as três credenciais necessárias, você pode tentar fazer a seguinte chamada de API. Essa chamada lista todas as chamadas padrão Experience Data Model Classes do (XDM) 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: {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"
    }
  ]
}

Usar o Postman para autenticar e testar chamadas de API

Postman O é uma ferramenta popular que permite aos desenvolvedores explorar e testar as APIs RESTful. Este 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.

Desenvolvedor e controle de acesso à API com permissões de Experience Platform

OBSERVAÇÃO

Somente administradores do sistema têm a capacidade de exibir e gerenciar credenciais de API nas Permissões.

Antes de criar integrações no Console do Adobe Developer, 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

Acesse Admin Console e faça logon com sua Adobe ID.

Selecionar Produtos e selecione Adobe Experience Platform da lista de produtos.

Lista de produtos no Admin Console

No 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.

Pesquisar o perfil de produto

Selecione o Desenvolvedores e selecione Adicionar desenvolvedor.

Adicionar desenvolvedor na guia Desenvolvedores

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

Adicionar desenvolvedor usando seu email ou nome de usuário

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

Desenvolvedores listados na guia Desenvolvedores

Configurar uma API

Um desenvolvedor pode adicionar e configurar uma API em um projeto no Console do Adobe Developer.

Selecione seu projeto e, em seguida, Adicionar API.

Adicionar API a um projeto

No Adicionar uma API caixa de diálogo selecionar Adobe Experience Platform e selecione API EXPERIENCE PLATFORM.

Adicionar uma API no Experience Platform

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

Atribuir API a uma função

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

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

Guia de credenciais de API na função selecionada

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

Lista de APIs disponíveis para seleção

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

Guia Credenciais da API com API recém-adicionada

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 junto com as chamadas de API de exemplo fornecidas em documentação.

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

Nesta página