Introdução ao REST APIs getting-started-with-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 Recommendations api-requirements-recommendations

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

  • Parâmetros de solicitação: todos os parâmetros de solicitação são necessários, a menos que especificado de outra forma.
  • Solicitar cabeçalhos: ao usar tokens do Adobe Developer, você deve fornecer o cabeçalho x-api-key. Para obter a chave API, siga as instruções na página Integração de Conta de Serviço.
  • JSONtipo de conteúdo: Especifique content-type: application/json e accept: application/json no seu código.
  • Solicitações e respostas: envia solicitações como um objeto JSON formatado corretamente. Audience Manager responde com JSON dados formatados. As respostas do servidor podem conter dados solicitados, um código de status ou ambos.
  • Acesso: O consultor do Audience Manager fornecerá a você uma ID de cliente e uma chave que permitem fazer solicitações do API.
  • 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 dados API. Substitua o texto em itálico pelo seu próprio código, parâmetros ou outras informações necessárias.

Autenticação authentication

O Audience Manager REST APIs dá suporte a três métodos de autenticação.

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

Autenticação de servidor para servidor OAuth usando Adobe Developer oauth-adobe-developer

Esta seção aborda como coletar as credenciais necessárias para autenticar chamadas de API de Audience Manager, conforme descrito no fluxograma abaixo. Você pode coletar a maioria das credenciais necessárias na configuração inicial única. No entanto, o token de acesso deve ser atualizado a cada 24 horas.

diagrama de fluxo de autenticação de Audience Manager.

Visão geral do Adobe Developer developer-overview

Adobe Developer é um ecossistema e uma comunidade de desenvolvedores do Adobe. Ele inclui APIs para todos os produtos Adobe.

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

Pré-requisitos prerequisites-server-to-server

Antes de configurar a autenticação do OAuth Server-to-Server, verifique se você tem acesso ao Adobe Developer Console no Adobe Developer. Entre em contato com o administrador da organização para obter solicitações de acesso.

Autenticação oauth

Siga as etapas abaixo para configurar a autenticação do OAuth Server-to-Server usando o Adobe Developer:

  1. Faça logon no Adobe Developer Console.
  2. Siga as etapas no guia de implementação de credenciais de servidor para servidor do OAuth.
  3. Experimente a conexão fazendo sua primeira chamada do API com base nas instruções da Etapa 3.
NOTE
Para configurar e trabalhar com o Audience Manager REST APIs de forma automatizada, você pode girar os segredos do cliente de forma programática. Consulte a documentação do desenvolvedor para obter instruções detalhadas.

Adicionar a API do Audience Manager a um projeto add-aam-api-to-project

Vá para Adobe Developer Console e entre com sua Adobe ID. Em seguida, siga as etapas descritas no tutorial sobre criação de um projeto vazio na documentação do Adobe Developer Console.

Depois de criar um novo projeto, selecione Add API na tela Project Overview.

TIP
Se você tiver sido provisionado para várias organizações, use o seletor de organizações no canto superior direito da interface para garantir que está na organização necessária.

Tela do Developer Console com a opção Adicionar API realçada.

A tela Add an API é exibida. Selecione o ícone de produto do Adobe Experience Cloud e escolha Audience Manager API antes de selecionar Next.

Selecione a API de Audience Manager.

TIP
Selecione a opção View docs para navegar em uma janela de navegador separada para a documentação de referência da API de Audience Manager completa.

Selecione o tipo de autenticação de servidor para servidor OAuth select-oauth-server-to-server

Em seguida, selecione o tipo de autenticação para gerar tokens de acesso e acessar a API Audience Manager.

IMPORTANT
Selecione o método OAuth Server-to-Server, pois esse será o único método com suporte dali em diante. O método Service Account (JWT) está obsoleto. Embora as integrações que usam o método de autenticação JWT continuem a funcionar até 1º de janeiro de 2025, a Adobe recomenda que você migre as integrações existentes para o novo método servidor para servidor OAuth antes dessa data.

Selecione o método de autenticação OAuth.

Selecione os perfis de produto para sua integração select-product-profiles

Na tela Configure API, selecione os perfis de produto desejados. A conta de serviço da sua integração terá acesso aos recursos detalhados por meio dos perfis de produto selecionados aqui.

Selecione perfis de produto para sua integração.

Selecione Save configured API quando estiver pronto.

Coletar credenciais gather-credentials

Depois que a API for adicionada ao projeto, a página Audience Manager API do projeto exibirá as seguintes credenciais, necessárias em todas as chamadas para as APIs Audience Manager:

Informações de integração após adicionar uma API no Developer Console.

  • {API_KEY} (Client ID)
  • {ORG_ID} (Organization ID)

Gerar um token de acesso generate-access-token

A próxima etapa é gerar uma credencial {ACCESS_TOKEN} para uso em chamadas de API Audience Manager. Diferentemente dos valores de {API_KEY} e {ORG_ID}, um novo token deve ser gerado a cada 24 horas para continuar usando as APIs Audience Manager. Selecione Generate access token, conforme mostrado abaixo.

Mostrar como gerar um token de acesso

Testar uma chamada de API test-api-call

Depois de obter o token do portador de autenticação, execute uma chamada de API para testar se agora é possível acessar APIs de Audience Manager.

  1. Navegue até a documentação de referência da API.

  2. Selecione Authorize e cole o token de acesso obtido na etapa gerar token de acesso.

    Autorizar chamadas de API

  3. Execute uma chamada GET para o ponto de extremidade da API /datasources para recuperar uma lista de todas as fontes de dados disponíveis globalmente, conforme indicado na documentação de referência da API. Selecione Try it out, seguido por Execute, como mostrado abaixo.

    Executar chamadas de API

recommendation-more-help
Solicitação de API
code language-shell
curl -X 'GET' \
  'https://api.demdex.com/v1/datasources/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer your-access-token'
Resposta da API em caso de uso do token de portador correto

Ao usar um token de acesso funcional, o endpoint da API retorna uma resposta 200, juntamente com um corpo de resposta que inclui todas as fontes de dados globais às quais sua organização tem acesso.

code language-json
[
  {
    "pid": 1794,
    "name": "testdatasource1",
    "description": "Test data source",
    "status": "ACTIVE",
    "integrationCode": "test_ds1",
    "dataExportRestrictions": [],
    "updateTime": 1595340792000,
    "crUID": 0,
    "upUID": 15910,
    "linkNamespace": false,
    "type": "GENERAL",
    "subIdType": "CROSS_DEVICE_PERSON",
    "inboundS2S": true,
    "outboundS2S": true,
    "useAudienceManagerVisitorID": false,
    "allowDataSharing": true,
    "masterDataSourceIdProvider": true,
    "uniqueTraitIntegrationCodes": false,
    "uniqueSegmentIntegrationCodes": false,
    "marketingCloudVisitorIdVersion": 0,
    "idType": "CROSS_DEVICE",
    "samplingEndTime": 1596550392825,
    "allowDeviceGraphSharing": false,
    "supportsAuthenticatedProfile": true,
    "deviceGraph": false,
    "authenticatedProfileName": "testdatasource1",
    "deviceGraphName": "",
    "customNamespaceId": 29769,
    "customNamespaceCode": "silviu_ds1",
    "customerProfileDataRetention": 62208000,
    "samplingStartTime": 1595340792825,
    "dataSourceId": 29769,
    "containerIds": [],
    "samplingEnabled": false
  },
  {
    "pid": 1794,
    "name": "AAM Test Company Audiences",
    "description": "Automatically generated trait data source",
    "status": "ACTIVE",
    "integrationCode": "adobe-provided",
    "dataExportRestrictions": [
      "PII"
    ],

    [...]

[Obsoleto]{class="badge negative"}Autenticação JWT (Service Account) usando Adobe Developer jwt

Exibir informações sobre o método JWT (Service Account) obsoleto de obtenção de tokens de autenticação.

Visão geral do Adobe Developer adobeio

Adobe Developer é um ecossistema e uma comunidade de desenvolvedores do Adobe. Ele inclui APIs para todos os produtos Adobe.

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

Pré-requisitos prerequisites

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

Autenticação auth

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

  1. Faça logon no Adobe Developer Console.
  2. Siga as etapas em Conexão com a Conta de Serviço.
  3. Experimente a conexão fazendo sua primeira chamada do API com base nas instruções da Etapa 3.
note note
NOTE
Para configurar e trabalhar com o Audience Manager REST APIs de forma automatizada, você pode gerar o JWT de forma programática. Consulte Autenticação de JWT (Conta de Serviço) para obter instruções detalhadas.

Permissões RBAC da conta técnica

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

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

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

    conta técnica

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

[Obsoleto]{class="badge negative"}Autenticação OAuth (obsoleta) oauth-deprecated

Visualize informações sobre o método de autenticação OAuth herdado obsoleto de obtenção de tokens de autenticação.
note warning
WARNING
A autenticação e renovação do token Audience Manager REST API via OAuth 2.0 foi descontinuada.
Em vez disso, use a Autenticação JWT (Conta de Serviço).

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

Criar um usuário API genérico requirements

Recomendamos que você crie uma conta de usuário técnico separada para trabalhar com o Audience Manager APIs. É uma conta genérica que não está vinculada a um usuário específico na organização nem associada a ele. Este tipo de conta de usuário do API ajuda você a realizar duas coisas:

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

Como exemplo ou caso de uso para esse tipo de conta, suponhamos que você queira alterar muitos segmentos ao mesmo tempo com as Ferramentas de gerenciamento em massa. Para fazer isso, sua conta de usuário precisa de acesso API. 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 o consultor do Audience Manager para configurar uma conta de usuário genérica, somente para API.

Fluxo de trabalho de autenticação de senha password-authentication-workflow

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

note tip
TIP
Criptografe tokens de acesso e atualização se você armazená-los em um banco de dados.

Etapa 1: solicitar acesso de API

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

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

Etapa 2: solicitar o token

Transmita uma solicitação de token com o cliente JSON de sua preferência. 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 sequência de caracteres codificada na 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=.
  • Passar no HTTP headers Authorization:Basic <base-64 clientID:clientSecret> e Content-Type: application/x-www-form-urlencoded . Por exemplo, seu cabeçalho pode ter esta 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 seu token de acesso. A resposta deve ser semelhante a:

code language-json
{
    "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é o token de acesso expirar. Como prática recomendada, use tempos de expiração curtos para limitar a exposição se o token for exposto.

Atualizar token refresh-token

Atualizar tokens renova o acesso API depois que o token original expirar. Se solicitado, a resposta JSON no fluxo de trabalho 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 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 a partir de um cliente JSON em seu navegador.

Etapa 1: solicitar o novo token

Transmita uma solicitação de token de atualização com seu cliente JSON preferido. 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 sequência de caracteres codificada na 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=.
  • Passar nos cabeçalhos HTTP Authorization:Basic <base-64 clientID:clientSecret> e Content-Type: application/x-www-form-urlencoded. Por exemplo, seu cabeçalho pode ter esta aparência:
    Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
    Content-Type: application/x-www-form-urlencoded
  • No corpo da solicitação, especifique o grant_type:refresh_token e transmita 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

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

code language-json
{
    "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 authentication-code-implicit

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

Fazer Solicitações API Autenticadas authenticated-api-requests

Requisitos para chamar métodos API depois que você receber um token de autenticação.

Para fazer chamadas com os métodos API disponíveis:

Parâmetros de Consulta API Opcionais optional-api-query-parameters

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

Parâmetro
Descrição
page
Retorna 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 é o padrão.
search
Retorna resultados com base na cadeia de caracteres 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. Seu exemplo de solicitação 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 é o 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 a 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 em "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 De Página

Quando as informações de página não são especificadas, a solicitação retorna resultados JSON simples em uma matriz. 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. O exemplo de solicitação usando opções de página pode ser semelhante a:

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

API URLs api-urls

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

Solicitação URLs request-urls

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

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

Solicitação URLs para [Recomendado]{class="badge positive"}[Obsoleto]{class="badge negative"}Autenticação de JWT por meio do Adobe Developer request-urls-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 [Obsoleto]{class="badge negative"}Autenticação de OAuth request-urls-oauth

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 environments

O Audience Manager APIs fornece 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 em tempo real. 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/...
NOTE
O ambiente beta do Audience Manager é uma versão independente de menor escala do ambiente de produção. Todos os dados que você deseja testar devem ser inseridos e coletados neste ambiente.

Versões versions

Novas versões desses APIs são lançadas regularmente. Uma nova versão incrementa o número de 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 response-codes-defined

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

ID do código de resposta
Texto da resposta
Definição
200
OK
A solicitação foi processada com sucesso. Retornará o conteúdo ou os dados esperados, se necessário.
201
Created
O recurso foi criado Retorna para solicitações de 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
O recurso não foi encontrado para o caminho especificado.
409
Conflict
A solicitação não pôde ser concluída devido a um conflito com o estado do recurso.
500
Server Error
O servidor encontrou um erro inesperado que o impediu de atender à solicitação.
de293fbf-b489-49b0-8daa-51ed303af695