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.

IMPORTANTE

Dependendo do seu método de autenticação, você precisa ajustar sua solicitação URLs de acordo. Consulte a seção Ambientes para obter detalhes sobre os nomes de host que você deve usar.

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.
  3. Experimente a conexão fazendo sua primeira chamada API com base nas instruções de Etapa 3.
OBSERVAÇÃO

Para configurar e trabalhar com o Audience Manager REST APIs de maneira automatizada, você pode gerar o JWT programaticamente. Consulte Autenticação JWT (Conta de Serviço) para obter instruções detalhadas.

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.

    conta técnica

  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)

AVISO

Audience Manager REST API a autenticação e a renovação de token por meio do agora OAuth 2.0 está obsoleta.

Em vez disso, use a JWT (Conta de Serviço) Authentication.

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.

DICA

Criptografe o acesso e atualize os tokens se você armazená-los em um banco de dados.

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:

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.

Parâmetro Descrição
page Retorna os resultados por número de página. A numeração começa em 0.
pageSize Define o número de resultados de resposta retornados pela solicitação (10 é o padrão).
sortBy Classifica e retorna resultados de acordo com a propriedade JSON especificada.
descending Classifica e retorna resultados em ordem decrescente. ascending é padrão.
search Retorna 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 para esse item. Sua solicitação de amostra pode ter esta aparência: 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 para 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 : Retornar e exibir informações 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 de valores chave separados. Por exemplo, para retornar uma lista de segmentos com permissões READ e WRITE somente, 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 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

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/

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

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

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/...
OBSERVAÇÃO

O Audience Manager ambiente beta é uma versão independente e de menor escala do ambiente de produção. Todos os dados que você deseja testar devem ser inseridos e coletados neste ambiente.

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.

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 estará 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.

Nesta página