Introdução a REST APIs

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

Requisitos da API e recomendações

As coisas que você deve e deve fazer ao trabalhar com Audience Manager APIs.

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

• Parâmetros de solicitação: todos os parâmetros de solicitação são obrigatórios, a menos que especificado de outra forma.
• Cabeçalhos de solicitação: ao usar 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 permite que você faça 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 fazer 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. Inclui as ferramentas do desenvolvedor do Adobe I/O e as APIs e APIs para todos os produtos do Adobe. Esta é a maneira recomendada de configurar e usar Adobe APIs.
• Autenticação OAuth (obsoleta). Embora esse método esteja 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. Inclui as ferramentas do desenvolvedor do Adobe I/O e as APIs e APIs para todos os produtos do Adobe.

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

Pré-requisitos

Antes de configurar a autenticação JWT, certifique-se de ter acesso ao Console do Desenvolvedor do Adobe em Adobe I/O. Entre em contato com o administrador da organização para obter informações sobre 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 Adobe Developer Console.
2. Siga as etapas em Service Account Connection.
   • 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.

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 start trabalhando 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. Este tipo de conta de usuário API ajuda você a realizar duas coisas:

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

Como exemplo ou caso de uso para esse tipo de conta, digamos que você queira alterar muitos segmentos de uma só vez com as Ferramentas de Gerenciamento em Massa. 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 Audience Manager APIs.

Entre em contato com seu consultor Audience Manager para configurar uma conta de usuário genérica, API apenas.

Fluxo de trabalho de autenticação de senha

Autenticação de senha, acesso seguro a REST API. As etapas abaixo descrevem o fluxo de trabalho para autenticação de senha de um cliente JSON no seu navegador.

Etapa 1: Solicitar API acesso

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

Observação: Se você quiser receber um token de atualização, especifique-o ao solicitar o acesso API.

Etapa 2: Solicite o token

Passe uma solicitação de token com seu cliente preferencial JSON. Quando você cria 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=.
• Passe HTTP headers Authorization:Basic <base-64 clientID:clientSecret> e Content-Type: application/x-www-form-urlencoded. Por exemplo, seu cabeçalho pode ser semelhante a:
  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 seu token de acesso. A resposta deve ser parecida com 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 tecla 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 depois que 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 pelo processo de autenticação de 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 no seu navegador.

Etapa 1: Solicitar o novo token

Passe uma solicitação de token de atualização com seu cliente preferencial JSON. Quando você cria 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=.
• Passe os cabeçalhos HTTP Authorization:Basic <base-64 clientID:clientSecret> e Content-Type: application/x-www-form-urlencoded. Por exemplo, seu cabeçalho pode ser semelhante a:
  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 na solicitação de acesso anterior. A solicitação deve ser parecida com esta:
  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 parecida com 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 o código de autorização e a autenticação implícita. Para usar esses métodos de acesso, seus usuários precisam fazer logon em https://api.demdex.com/oauth/authorize para obter acesso e atualizar tokens.

Fazer solicitações API autenticadas

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

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

• No cabeçalho HTTP, defina Authorization: Bearer <token>.
• Ao usar 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 client_id da página integração do Adobe I/O.
• Chame o método API necessário.

Parâmetros de Query 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 string de solicitação ao passar esse query para API.

Parâmetro	Descrição
page	Retorna os resultados por número de página. Numerando start em 0.
pageSize	Define o número de resultados de resposta retornados pela solicitação (10 é padrão).
sortBy	Classifica e retorna os resultados de acordo com a propriedade JSON especificada.
descending	Classifica e retorna os resultados em ordem decrescente. ascending é padrão.
search	Retorna os resultados com base na string especificada que você deseja usar como parâmetro de pesquisa. Por exemplo, digamos que você queira encontrar resultados para todos os modelos que têm a palavra "Teste" em qualquer um dos campos de valor desse item. Sua solicitação de amostra pode ser semelhante a: GET https://aam.adobe.io/v1/models/?search=Test. Você pode pesquisar qualquer valor retornado por um método "get all".
folderId	Retorna todas as IDs de traits dentro da pasta especificada. Não disponível para todos os métodos.
permissions	Retorna uma lista de segmentos com base na permissão especificada. READ é padrão. As permissões incluem: READ : Informações de retorno e visualização sobre um segmento. WRITE : Use PUT para atualizar um segmento. CREATE : Use POST para criar um segmento. DELETE : Excluir um segmento. Requer acesso às características subjacentes, se houver. Por exemplo, você precisará de direitos para excluir as características que pertencem a um segmento se desejar removê-lo. Especifique várias permissões com pares separados de valores chave. Por exemplo, para retornar uma lista de segmentos apenas com permissões READ e WRITE, passe "permissions":"READ", "permissions":"WRITE".
includePermissions	(Boolean) Defina como true para retornar suas permissões para o segmento. O padrão é false.

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

Quando as informações da página não são especificadas, a solicitação retorna simples JSON resulta em um storage. Se as informações da 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 amostra 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 passar 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.

Solicite URLs a autenticação JWT

API Métodos	Solicitação URL
Algorithmic Modeling	https://aam.adobe.io/v1/models/
Data Source	https://aam.adobe.io/v1/datasources/
Derived Signals	https://aam.adobe.io/v1/signals/derived/
Destinations	https://aam.adobe.io/v1/destinations/
Domains	https://aam.adobe.io/v1/partner-sites/
Folders	Características: https://aam.adobe.io/v1/folders/traits / Segmentos: https://aam.adobe.io/v1/folders/segments /
Schema	https://aam.adobe.io/v1/schemas/
Segments	https://aam.adobe.io/v1/segments/
Traits	https://aam.adobe.io/v1/traits/
Trait Types	https://aam.adobe.io/v1/customer-trait-types
Taxonomy	https://aam.adobe.io/v1/taxonomies/0/

Solicite URLs a autenticação OAuth (obsoleta)

API Métodos	Solicitação URL
Algorithmic Modeling	https://api.demdex.com/v1/models/
Data Source	https://api.demdex.com/v1/datasources/
Derived Signals	https://api.demdex.com/v1/signals/derived/
Destinations	https://api.demdex.com/v1/destinations/
Domains	https://api.demdex.com/v1/partner-sites/
Folders	Características: https://api.demdex.com/v1/folders/traits / Segmentos: https://api.demdex.com/v1/folders/segments /
Schema	https://api.demdex.com/v1/schemas/
Segments	https://api.demdex.com/v1/segments/
Traits	https://api.demdex.com/v1/traits/
Trait Types	https://api.demdex.com/v1/customer-trait-types
Taxonomy	https://api.demdex.com/v1/taxonomies/0/

Ambientes

Os Audience Manager APIs fornecem acesso a diferentes ambientes de trabalho. Esses ambientes ajudam você a testar o código em bancos de dados separados sem afetar os dados de produção 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.

Ambiente	Nome do host para autenticação JWT	Nome do host para autenticação OAuth
Produção	https://aam.adobe.io/...	https://api.demdex.com/...
Beta	https://aam-beta.adobe.io/...	https://api-beta.demdex.com/...

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>, conforme 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.

ID do código de resposta	Texto de resposta	Definição
200	OK	A solicitação foi processada com êxito. Retornará o conteúdo ou os dados esperados, se necessário.
201	Created	O recurso foi criado. Retorna para solicitações PUT e POST.
204	No Content	O recurso foi excluído. O corpo da resposta ficará em branco.
400	Bad Request	O servidor não entendeu a solicitação. Geralmente devido a sintaxe malformada. Verifique sua solicitação e tente novamente.
403	Forbidden	Você não tem acesso ao recurso.
404	Not Found	Não foi possível localizar o recurso para o caminho especificado.
409	Conflict	Não foi possível concluir a solicitação devido a um conflito com o estado do recurso.
500	Server Error	O servidor encontrou um erro inesperado que o impedia de atender à solicitação.