Introdução ao REST APIs

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

Requisitos da API e recomendações

O que você deve e deve fazer ao trabalhar com a variável Audience Manager APIs.

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

• Parâmetros da solicitação: todos os parâmetros de solicitação são necessários, a menos que especificado de outra forma.
• Cabeçalhos de solicitação: ao usar Desenvolvedor de Adobe , você deve fornecer a variável x-api-key cabeçalho. Você pode obter seu API seguindo as instruções da Integração de contas de serviço página.
• JSONtipo de conteúdo: Especificar content-type: application/json e accept: application/json no seu código.
• Solicitações e respostas: Enviar solicitações como formatadas corretamente JSON objeto. Audience Manager responde com JSON dados formatados. As respostas do servidor podem conter dados solicitados, um código de status ou ambos.
• Acesso: Seu Audience Manager o consultor fornecerá a você uma ID do cliente e uma chave que permite API solicitações.
• Documentação e amostras de código: Texto em itálico representa uma variável fornecida ou transmitida ao criar ou receber API dados. Substituir itálico texto com seu próprio código, parâmetros ou outras informações necessárias.

Autenticação

O Audience Manager REST APIs oferecem suporte para dois métodos de autenticação.

• Autenticação JWT (Conta de Serviço) usar Desenvolvedor de Adobe. Adobe Developer é o ecossistema e a comunidade do Adobe. Inclui APIs para todos os produtos Adobe. Essa é a maneira recomendada de configurar e usar Adobe APIs.
• Autenticação OAuth (obsoleta). Embora esse método seja obsoleto, os clientes com OAuth as integrações podem continuar usando esse método.

JWT (Service Account) Autenticação usando Adobe Developer

Visão geral do desenvolvedor do Adobe

Adobe Developer é o ecossistema e a comunidade do Adobe. Inclui APIs para todos os produtos Adobe.

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

Pré-requisitos

Antes de configurar JWT autenticação, certifique-se de ter acesso ao Console do desenvolvedor do Adobe em Desenvolvedor de Adobe. Entre em contato com o administrador da organização para obter solicitações de acesso.

Autenticação

Siga as etapas abaixo para configurar JWT (Service Account) autenticação usando Adobe Developer:

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: Adicionar uma API ao seu projeto usando a autenticação da conta de serviço, escolha o Audience Manager API opção.
3. Experimente a conexão fazendo a primeira API com base nas instruções de Etapa 3.

Permissões RBAC de conta técnica

Se sua conta Audience Manager usar Controle de acesso com base em função, você deve 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 GET chamar para https://aam.adobe.io/v1/users/self. A chamada criará uma conta técnica de usuário que pode ser exibida na variável Admin Consoleno Users página.

   

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

OAuth Autenticação (obsoleto)

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

Criar um Genérico API Usuário

Recomendamos que você crie uma conta de usuário técnica e separada para trabalhar com a 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 a conta de usuário ajuda você a realizar duas coisas:

• Identifique o serviço que está chamando a variável API (por exemplo, chamadas de seus aplicativos que usam nosso APIou de outras ferramentas API solicitações).
• Forneça acesso ininterrupto à APIs. Uma conta vinculada a uma pessoa específica pode ser excluída ao sair da empresa. Isso impedirá que você trabalhe com os API código. 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 a variável Ferramentas de gerenciamento em massa. Para fazer isso, sua conta de usuário precisa API acesso. Em vez de adicionar permissões a um usuário específico, crie um API conta de usuário com credenciais, chave e segredo apropriados para fazer API chamadas . Isso também é útil se você desenvolver seus próprios aplicativos que usam o Audience Manager APIs.

Trabalhe com seu Audience Manager consultor para configurar um genérico, APIconta de usuário somente .

Fluxo de trabalho de autenticação de senha

Autenticação de senha: acesso seguro à nossa REST API. As etapas abaixo destacam o fluxo de trabalho para autenticação de senha a partir de um JSON no seu navegador.

Etapa 1: Solicitação API Acesso

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

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

Etapa 2: Solicitar o token

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

• Use um POST método 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 converter em dGVzdElkOnRlc3RTZWNyZXQ=.
• Transmita o 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

O JSON contém seu 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"
}

O 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

Renovar tokens API acesso após o token original expirar. Se solicitado, a resposta JSON no fluxo de trabalho da 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á uma 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 a partir de um JSON no seu navegador.

Etapa 1: Solicitar o novo token

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

• Use um POST método 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 converter 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 transmitir o token de atualização recebido na 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

O 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 O suporta código de autorização e autenticação implícita. Para usar esses métodos de acesso, os usuários precisam fazer logon no para https://api.demdex.com/oauth/authorize para obter acesso e atualizar tokens.

Tornar Autenticado API Solicitações

Requisitos para a chamada API métodos depois de receber um token de autenticação.

Para fazer chamadas em relação ao disponível API métodos:

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

Opcional API Parâmetros de consulta

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 API métodos que retornam all propriedades de um objeto. Defina essas opções na cadeia de caracteres de solicitação ao passar essa consulta para o API.

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

Quando informações da página não é especificado, a solicitação retorna simples JSON resulta em uma matriz. Se informações da página é especificado, a lista retornada é encapsulada em uma JSON objeto 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 usado para transmitir API solicitações, por método.

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

Solicitação URLs para JWT Autenticação

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

Ambientes

O Audience Manager APIFornecem 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 API 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 libertadas regularmente. Uma nova versão aprimora o API número da versão. O número da versão é referenciado na solicitação URL as 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 pela Audience Manager REST API.