Informações sobre requisitos gerais, autenticação, parâmetros opcionais de query, solicitação URLs e outras referências.
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:
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.content-type: application/json
** accept: application/json
e no seu código.O Audience Manager REST APIs suporta dois métodos de autenticação.
Dependendo do método de autenticação, é necessário ajustar a solicitação URLs de acordo. Consulte a seção Ambientes para obter detalhes sobre os nomes dos hosts que você deve usar.
Adobe I/O é o ecossistema e a comunidade do Adobe. Inclui as ferramentas do desenvolvedor Adobe I/O e as APIs e APIs para todos os produtos do Adobe.
Esta é a maneira recomendada de configurar e usar Adobe APIs.
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 informações sobre solicitações de acesso.
Siga as etapas abaixo para configurar a autenticação JWT (Service Account) usando Adobe I/O:
Para configurar e trabalhar com o Audience Manager REST APIs de maneira automatizada, você pode gerar o JWT de forma programada. Consulte Autenticação JWT (Conta de Serviço) para obter instruções detalhadas.
Audience Manager REST API autenticação e renovação de token via agora OAuth 2.0 está obsoleta.
Em vez disso, use Autenticação JWT (Conta de Serviço).
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.
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:
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.
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.
Criptografe o acesso e atualize os tokens se você armazená-los em um banco de dados.
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.
Passe uma solicitação de token com seu cliente preferencial JSON. Quando você cria a solicitação:
POST
para chamar https://api.demdex.com/oauth/token
.testId : testSecret
são convertidas em dGVzdElkOnRlc3RTZWNyZXQ=
.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
grant_type=password&username=<your-AudienceManager-user-name>&password=<your-AudienceManager-password>
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.
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.
Passe uma solicitação de token de atualização com seu cliente preferencial JSON. Quando você cria a solicitação:
POST
para chamar https://api.demdex.com/oauth/token
.testId : testSecret
são convertidas em dGVzdElkOnRlc3RTZWNyZXQ=
.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
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
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"
}
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.
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:
HTTP
, defina Authorization: Bearer <token>
.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.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:
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 . |
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
URLs para solicitações, ambientes de preparo e produção e versões.
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.
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/ |
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/ |
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/... |
O ambiente beta Audience Manager é 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.
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/...
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. |