Introdução às APIs do Adobe Experience Platform

O Adobe Experience Platform é desenvolvido sob uma filosofia de "API first". Usando APIs do Experience Platform, você pode executar programaticamente operações básicas de CRUD (Criar, Ler, Atualizar, Excluir) em relação aos dados, como configurar atributos calculados, acessar dados/entidades, exportar dados, excluir dados ou lotes desnecessários e muito mais.

As APIs para cada serviço do Experience Platform compartilham o mesmo conjunto de cabeçalhos de autenticação e usam sintaxes semelhantes para suas operações CRUD. O guia a seguir descreve as etapas necessárias para começar a usar as APIs do Experience Platform.

Autenticação e cabeçalhos

Para fazer chamadas com êxito para pontos de extremidade do Experience Platform, você deve concluir o tutorial de autenticação. Concluir o tutorial de autenticação fornece os valores de cada um dos cabeçalhos necessários nas chamadas de API do Experience Platform, conforme mostrado abaixo:

Cabeçalho da sandbox

Todos os recursos no Experience Platform são isolados em sandboxes virtuais específicas. As solicitações para APIs do Experience Platform exigem um cabeçalho que especifique o nome da sandbox em que a operação ocorrerá:

Para obter mais informações sobre sandboxes na Experience Platform, consulte a documentação de visão geral da sandbox.

Cabeçalho de tipo de conteúdo

Todas as solicitações com uma carga no corpo da solicitação (como chamadas POST, PUT e PATCH) devem incluir um cabeçalho Content-Type. Os valores aceitos são específicos para cada endpoint de API. Se um valor Content-Type específico for necessário para um ponto de extremidade, seu valor será mostrado nas solicitações de API de exemplo fornecidas pelos guias de API para serviços Experience Platform individuais.

Fundamentos da API do Experience Platform

As APIs do Adobe Experience Platform empregam várias tecnologias e sintaxes subjacentes que são importantes de entender para gerenciar efetivamente os recursos do Experience Platform.

Para saber mais sobre as tecnologias de API subjacentes que a Experience Platform utiliza, incluindo objetos de esquema JSON de exemplo, visite o guia fundamentos de API do Experience Platform.

Coleções Postman para APIs do Experience Platform

O Postman é uma plataforma de colaboração para o desenvolvimento de API que permite configurar ambientes com variáveis predefinidas, compartilhar coleções de API, simplificar solicitações CRUD e muito mais. A maioria dos serviços de API do Experience Platform tem coleções do Postman que podem ser usadas para ajudar a fazer chamadas de API.

Para saber mais sobre o Postman, incluindo como configurar um ambiente, uma lista de coleções disponíveis e como importar coleções, visite a documentação do Experience Platform Postman.

Leitura de chamadas de API de amostra sample-api

Os formatos de solicitação variam dependendo da API do Experience Platform que está sendo usada. A melhor maneira de saber como estruturar suas chamadas de API é seguindo os exemplos fornecidos na documentação para o serviço Experience Platform específico que você está usando.

A documentação do Experience Platform mostra exemplos de chamadas de API de duas maneiras diferentes. Primeiro, a chamada é apresentada em seu formato de API, uma representação de modelo que mostra apenas a operação (GET, POST, PUT, PATCH, DELETE) e o ponto de extremidade que está sendo usado (por exemplo, /global/classes). Alguns modelos também mostram a localização das variáveis para ajudar a ilustrar como uma chamada deve ser formulada, como GET /{VARIABLE}/classes/{ANOTHER_VARIABLE}.

As chamadas são exibidas como comandos cURL em uma Solicitação, que inclui os cabeçalhos necessários e o "caminho base" completo necessário para interagir com êxito com a API. O caminho base deve ser anexado previamente a todos os endpoints. Por exemplo, o ponto de extremidade /global/classes mencionado acima torna-se https://platform.adobe.io/data/foundation/schemaregistry/global/classes. Você verá o formato da API/padrão de solicitação em toda a documentação e espera-se que use o caminho completo mostrado no exemplo de solicitação ao fazer suas próprias chamadas para as APIs do Experience Platform.

Exemplo de solicitação de API

Veja a seguir um exemplo de solicitação da API que demonstra o formato que você encontrará na documentação.

Formato da API

O formato da API mostra a operação (GET) e o endpoint que está sendo usado. As variáveis são indicadas por chaves (neste caso, {CONTAINER_ID}).

GET /{CONTAINER_ID}/classes

Solicitação

Nesta solicitação de exemplo, as variáveis do formato da API recebem valores reais no caminho da solicitação. Além disso, todos os cabeçalhos necessários são mostrados como valores de cabeçalho de amostra ou variáveis, onde informações confidenciais (como tokens de segurança e IDs de acesso) devem ser incluídas.

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}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Resposta

A resposta ilustra o que você esperaria receber após uma chamada bem-sucedida para a API, com base na solicitação enviada. Ocasionalmente, a resposta é truncada por espaço, o que significa que você pode ver mais informações ou informações adicionais para aquelas exibidas na amostra.

{
    "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"
        }
    ],
    "_links": {}
}

Mensagens de erro

O guia de solução de problemas do Experience Platform fornece uma lista de erros que você pode encontrar ao usar qualquer serviço do Experience Platform.

Para obter guias de solução de problemas sobre serviços individuais da Experience Platform, consulte o diretório de solução de problemas de serviço.

Para obter mais informações sobre endpoints específicos nas APIs do Experience Platform, incluindo cabeçalhos e corpos de solicitação necessários, consulte os guias da API do Experience Platform.

Guias da API do Experience Platform api-guides

Para obter mais informações sobre endpoints e operações específicos disponíveis para cada serviço, consulte a documentação de referência da API no Adobe I/O.

Próximas etapas

Este documento apresentou os cabeçalhos necessários, os guias disponíveis e forneceu um exemplo de chamada de API. Agora que você tem os valores de cabeçalho necessários para fazer chamadas de API no Adobe Experience Platform, selecione um ponto de extremidade de API que deseja explorar na tabela de guias da API do Experience Platform.

Para obter respostas para perguntas frequentes, consulte o guia de solução de problemas do Experience Platform.

Para configurar um ambiente do Postman e explorar as coleções disponíveis do Postman, consulte o guia do Experience Platform Postman.