Introdução a REST APIs

Informações sobre requisitos gerais, autenticação, parâmetros de consulta opcionais, solicitação URLs e outras referências.

Requisitos da API e recomendações

O que você deve e deve fazer ao trabalhar com o Audience Manager APIs.

Observe o seguinte ao trabalhar com o código API do Audience Manager:

• Parâmetros da solicitação: todos os parâmetros da solicitação são obrigatórios, a menos que especificado de outra forma.
• Cabeçalhos de solicitação: ao usar o Adobe I/ Otokens, você deve fornecer o x-api-key cabeçalho . Você pode obter sua chave API seguindo as instruções na página Integração da conta de serviço.
• JSONtipo de conteúdo: especifique content-type: application/json ** accept: application/json e no seu código.
• Solicitações e respostas: envia solicitações como um JSON objeto formatado corretamente. Audience Manager responde com dados JSON formatados. As respostas do servidor podem conter dados solicitados, um código de status ou ambos.
• Acesso: seu Audience Manager consultor fornecerá uma ID de cliente e uma chave que permitem fazer API solicitações.
• Documentação e exemplos de código: o texto em ** itálico representa uma variável que você fornece ou transmite ao criar ou receber API dados. Substitua o texto em itálico por seu próprio código, parâmetros ou outras informações necessárias.

Autenticação

O Audience Manager REST APIs suporta dois métodos de autenticação.

• Autenticação JWT (Conta de Serviço) usando Adobe I/O. Adobe I/O é o ecossistema e a comunidade do Adobe. Ele inclui as ferramentas do desenvolvedor Adobe I/O e as APIs e APIs para todos os produtos Adobe. Esta é a maneira recomendada de configurar e usar Adobe APIs.
• Autenticação OAuth (obsoleta). Embora esse método seja obsoleto, os clientes com integrações OAuth existentes podem continuar usando esse método.

JWT (Service Account) Autenticação usando Adobe I/O

Visão geral do Adobe I/O

Adobe I/O é o ecossistema e a comunidade do Adobe. Ele inclui as ferramentas do desenvolvedor Adobe I/O e as APIs e APIs para todos os produtos Adobe.

Esta é a maneira recomendada de configurar e usar Adobe APIs.

Pré-requisitos

Antes de configurar a autenticação JWT, verifique se você tem acesso ao Console do Desenvolvedor do Adobe em Adobe I/O. Entre em contato com o administrador da organização para obter solicitações de acesso.

Autenticação

Siga as etapas abaixo para configurar a autenticação JWT (Service Account) usando Adobe I/O:

1. Faça logon no Console do desenvolvedor do Adobe.
2. Siga as etapas em Conexão da Conta de Serviço.
   • Durante Etapa 2: Adicione uma API ao seu projeto usando a autenticação da conta de serviço, escolha a opção Audience Manager API.
3. Experimente a conexão fazendo sua primeira chamada API com base nas instruções de Etapa 3.

Permissões RBAC de conta técnica

Se sua conta do Audience Manager usar Controle de acesso com base em função, você deverá criar uma conta de usuário técnica do Audience Manager e adicioná-la ao grupo RBAC do Audience Manager que fará as chamadas de API.

Siga as etapas abaixo para criar uma conta de usuário técnica e adicioná-la a um grupo RBAC:

1. Faça uma chamada GET para https://aam.adobe.io/v1/users/self. A chamada criará uma conta técnica de usuário que você pode ver no Admin Console, na página Users.

   

2. Faça logon em sua conta do Audience Manager e adicione a conta técnica de usuário ao grupo de usuários que fará as chamadas de API.

OAuth Autenticação (obsoleto)

O Audience Manager REST API segue os padrões OAuth 2.0 para autenticação e renovação de token. As seções abaixo descrevem como autenticar e começar a trabalhar com os APIs.

Criar um Usuário Genérico API

Recomendamos que você crie uma conta de usuário técnica e separada para trabalhar com os Audience Manager APIs. Esta é uma conta genérica que não está vinculada ou associada a um usuário específico em sua organização. Esse tipo de API conta de usuário ajuda você a realizar duas coisas:

• Identifique qual serviço está chamando o API (por exemplo, chamadas de seus aplicativos que usam nossos APIs ou de outras ferramentas que fazem solicitações de API).
• Forneça acesso ininterrupto aos APIs. Uma conta vinculada a uma pessoa específica pode ser excluída ao sair da empresa. Isso impedirá que você trabalhe com o código API disponível. Uma conta genérica não vinculada a um funcionário específico ajuda a evitar esse problema.

Como exemplo ou caso de uso para esse tipo de conta, digamos que você queira alterar muitos segmentos ao mesmo tempo com as Ferramentas de gerenciamento em massa. Bem, para fazer isso, sua conta de usuário precisa de API acesso. Em vez de adicionar permissões a um usuário específico, crie uma conta de usuário API não específica que tenha as credenciais, a chave e o segredo apropriados para fazer chamadas API. Isso também é útil se você desenvolver seus próprios aplicativos que usam o Audience Manager APIs.

Trabalhe com seu consultor Audience Manager para configurar uma conta de usuário genérica, API somente.

Fluxo de trabalho de autenticação de senha

A autenticação de senha protege o acesso em REST API. As etapas abaixo descrevem o fluxo de trabalho para autenticação de senha de um cliente JSON em seu navegador.

Etapa 1: Solicitar acesso API

Entre em contato com o gerente de soluções de parceiros. Eles fornecerão uma API ID do cliente e um segredo. A ID e o segredo autenticam você no API.

Observação: Se quiser receber um token de atualização, especifique que ao solicitar acesso a API.

Etapa 2: Solicitar o token

Transmita uma solicitação de token com seu cliente preferido JSON. Ao criar a solicitação:

• Use um método POST para chamar https://api.demdex.com/oauth/token.
• Converta a ID do cliente e o segredo em uma string codificada em base 64. Separe a ID e o segredo com dois pontos durante o processo de conversão. Por exemplo, as credenciais testId : testSecret são convertidas em dGVzdElkOnRlc3RTZWNyZXQ=.
• Transmita HTTP headers Authorization:Basic <base-64 clientID:clientSecret> e Content-Type: application/x-www-form-urlencoded . Por exemplo, o cabeçalho pode ter a seguinte aparência:
  Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
• Configure o corpo da solicitação da seguinte maneira:
  
  grant_type=password&username=<your-AudienceManager-user-name>&password=<your-AudienceManager-password>

Etapa 3: Receber o token

A resposta JSON contém o token de acesso. A resposta deve ser semelhante a esta:

{
    "access_token": "28fed402-eafd-456c-9341-ac753f25bbbc",
    "token_type": "bearer",
    "refresh_token": "b27122c0-b0c7-4b39-a71b-1547a3b3b88e",
    "expires_in": 21922,
    "scope": "read write"
}

A chave expires_in representa o número de segundos até que o token de acesso expire. Como prática recomendada, use tempos de expiração curtos para limitar a exposição se o token for exposto.

Atualizar Token

Atualize os tokens para renovar o acesso API após o token original expirar. Se solicitado, a resposta JSON no workflow de senha inclui um token de atualização. Se você não receber um token de atualização, crie um novo por meio do processo de autenticação por senha.

Você também pode usar um token de atualização para gerar um novo token antes que o token de acesso existente expire.

Se o token de acesso tiver expirado, você receberá um 401 Status Code e o seguinte cabeçalho na resposta:

WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"

As etapas a seguir descrevem o fluxo de trabalho para usar um token de atualização para criar um novo token de acesso de um cliente JSON em seu navegador.

Etapa 1: Solicitar o novo token

Passe uma solicitação de token de atualização com o cliente preferido JSON. Ao criar a solicitação:

• Use um método POST para chamar https://api.demdex.com/oauth/token.
• Converta a ID do cliente e o segredo em uma string codificada em base 64. Separe a ID e o segredo com dois pontos durante o processo de conversão. Por exemplo, as credenciais testId : testSecret são convertidas em dGVzdElkOnRlc3RTZWNyZXQ=.
• Transmita os cabeçalhos HTTP Authorization:Basic <base-64 clientID:clientSecret> e Content-Type: application/x-www-form-urlencoded. Por exemplo, o cabeçalho pode ter a seguinte aparência:
  Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
• No corpo da solicitação, especifique o grant_type:refresh_token e passe o token de atualização recebido em sua solicitação de acesso anterior. A solicitação deve ter esta aparência:
  grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e

Etapa 2: Receber o novo token

A resposta JSON contém seu novo token de acesso. A resposta deve ser semelhante a esta:

{
    "access_token": "4fdfc261-2ffc-4fb7-8dbd-64221714c45f",
    "token_type": "bearer",
    "refresh_token": "295fa487-1825-4caa-a715-80b81ac17dae",
    "expires_in": 21922,
    "scope": "read write"
}

Código de autorização e autenticação implícita

O Audience Manager REST API suporta código de autorização e autenticação implícita. Para usar esses métodos de acesso, os usuários precisam fazer logon em https://api.demdex.com/oauth/authorize para obter acesso e atualizar tokens.

Fazer solicitações autenticadas API

Requisitos para chamar os métodos API após receber um token de autenticação.

Para fazer chamadas em relação aos métodos API disponíveis:

• No cabeçalho HTTP, defina Authorization: Bearer <token>.
• Ao usar a Autenticação JWT (Conta de Serviço), é necessário fornecer o cabeçalho x-api-key, que será o mesmo que seu client_id. Você pode obter seu client_id da página Adobe I/O integration.
• Chame o método API necessário.

Parâmetros de consulta API opcionais

Defina os parâmetros opcionais disponíveis para métodos que retornam todas as propriedades de um objeto.

Você pode usar esses parâmetros opcionais com métodos API que retornam todas propriedades para um objeto. Defina essas opções na cadeia de caracteres de solicitação ao passar essa consulta para API.

Uma observação sobre as opções da página

Quando as informações de página não são especificadas, a solicitação retorna simples JSON resulta em uma matriz. Se as informações de página forem especificadas, a lista retornada será encapsulada em um objeto JSON que contém informações sobre o resultado total e a página atual. Sua solicitação de exemplo usando opções de página pode ser semelhante a esta:

GET https://aam.adobe.io/v1/models/?page=1&pageSize=2&search=Test

API URLs

URLs para solicitações, ambientes de preparo e produção e versões.

Solicitação URLs

A tabela a seguir lista a solicitação URLs usada para transmitir solicitações API, por método.

Dependendo do método de autenticação usado, é necessário ajustar a solicitação URLs de acordo com as tabelas abaixo.

Solicite URLs a autenticação JWT

Solicitação URLs para autenticação OAuth (obsoleto)

Ambientes

Os Audience Manager APIs fornecem acesso a diferentes ambientes de trabalho. Esses ambientes ajudam a testar o código em bancos de dados separados sem afetar os dados de produção e ao vivo. A tabela a seguir lista os ambientes API disponíveis e os nomes de host de recursos correspondentes.

Dependendo do método de autenticação usado, é necessário ajustar o ambiente URLs de acordo com a tabela abaixo.

Versões

Novas versões desses APIs são lançadas regularmente. Uma nova versão incrementa o número da versão API. O número da versão é referenciado na solicitação URL como v<version number>, como mostrado no exemplo a seguir:

https://<host>/v1/...

Códigos de resposta definidos

HTTP códigos de status e texto de resposta retornados pelo Audience Manager REST API.