Introdução ao REST APIs

Última atualização em 2024-02-08
  • Tópicos
  • API
    Exibir mais informações sobre este tópico

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

Requisitos da API e Recommendations

Observe o seguinte ao trabalhar com o API AUDIENCE MANAGER código:

  • 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 Developer tokens, você deve fornecer a x-api-key cabeçalho. Você pode obter o seu API seguindo as instruções na caixa Integração da Conta de Serviço página.
  • JSONtipo de conteúdo: Especificar content-type: application/json e accept: application/json em seu código.
  • Solicitações e respostas: Enviar solicitações como um formulário corretamente formatado 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 consultor fornecerá uma ID do cliente e uma chave que permitirá que você faça API solicitações.
  • Documentação e amostras de código: Texto em itálico representa uma variável que você fornece ou transmite 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

A variável Audience Manager REST APIs oferecem suporte a três métodos de autenticação.

IMPORTANTE

Dependendo do método de autenticação, é necessário ajustar a solicitação URLs em conformidade. Consulte a Ambientes para obter detalhes sobre os nomes de host que você deve usar.

Autenticação de servidor para servidor OAuth usando 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 Audience Manager.

Visão geral do Adobe Developer

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

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

Pré-requisitos

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

Autenticação

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

  1. Faça logon no Console do Adobe Developer.
  2. Siga as etapas na guia Guia de implementação de credenciais do OAuth de servidor para servidor.
  3. Experimente a conexão fazendo seu primeiro API chame com base nas instruções de Etapa 3.
OBSERVAÇÃO

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

Ir para Console do Adobe Developer e faça logon com sua Adobe ID. Em seguida, siga as etapas descritas no tutorial em criação de um projeto vazio na documentação do Console do Adobe Developer.

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

DICA

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 variável Add an API é exibida. Selecione o ícone de produto do Adobe Experience Cloud e escolha Audience Manager API antes de selecionar Next.

Selecione Audience Manager API.

DICA

Selecione o View docs opção para navegar em uma janela de navegador separada até a conclusão Documentação de referência da API do Audience Manager.

Selecione o tipo de autenticação de servidor para servidor OAuth

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

IMPORTANTE

Selecione o OAuth Server-to-Server como esse será o único método compatível a partir de agora. A variável 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

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

Selecionar Save configured API quando estiver pronto.

Coletar credenciais

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

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

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

Gerar um token de acesso

A próxima etapa é gerar um {ACCESS_TOKEN} credencial para uso em chamadas de API Audience Manager. Ao contrário 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. Selecionar Generate access token, conforme mostrado abaixo.

Mostrar como gerar um token de acesso

Testar uma chamada de API

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. Selecionar Authorize e cole o token de acesso obtido na gerar token de acesso etapa.

    Autorizar chamadas de API

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

    Executar chamadas de API

curl -X 'GET' \
  'https://api.demdex.com/v1/datasources/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer your-access-token'

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.

[
  {
    "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"
    ],

    [...]

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

 Exibir informações sobre o obsoleto JWT (Service Account) para obter tokens de autenticação.

Visão geral do Adobe Developer

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

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

Pré-requisitos

Antes de configurar JWT autenticação, verifique se você tem acesso à Console do Adobe Developer in Adobe Developer. 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 Adobe Developer.
  2. Siga as etapas em Conexão da Conta de Serviço.
  3. Experimente a conexão fazendo seu primeiro API chame 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 a variável JWT programaticamente. Consulte Autenticação JWT (conta de serviço) para obter instruções detalhadas.

Permissões RBAC da conta técnica

Se sua conta Audience Manager usa Controle de acesso baseado em função, você deve 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. Criar um GET chamada para https://aam.adobe.io/v1/users/self. A chamada criará uma conta de usuário técnico que pode ser vista na variável Admin Console, no Users página.

    conta técnica

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

ObsoletoOAuth Autenticação (obsoleta)

 Visualizar informações sobre o legado obsoleto OAuth Método de autenticação para obtenção de tokens de autenticação.
AVISO

Audience Manager REST API autenticação e renovação de token via OAuth 2.0 O agora está obsoleto.

Use Autenticação JWT (conta de serviço) em vez disso.

A variável Audience Manager REST API segue 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 separada para trabalhar com a 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. Esse tipo de API A conta de usuário do ajuda você a realizar duas coisas:

  • Identificar o serviço que está chamando o API (por exemplo, chamadas de seus aplicativos que usam nossa APIs ou de outras ferramentas que API pedidos).
  • Fornecer 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 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, considere que você deseja alterar muitos segmentos de uma só vez com o Ferramentas de gerenciamento em massa. Bem, 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 que tenha as credenciais, a chave e o 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 o seu Audience Manager consultor para configurar um genérico, APIconta de usuário somente do.

Fluxo de trabalho de autenticação de senha

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

DICA

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

Etapa 1: solicitação API Access

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

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

Etapa 2: solicitar o token

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

  • Use um POST método a ser chamado 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 testId : testSecret converter em dGVzdElkOnRlc3RTZWNyZXQ=.
  • Transmite 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 variável JSON A resposta contém o token de acesso. A resposta deve ser semelhante a:

{
    "access_token": "28fed402-eafd-456c-9341-ac753f25bbbc",
    "token_type": "bearer",
    "refresh_token": "b27122c0-b0c7-4b39-a71b-1547a3b3b88e",
    "expires_in": 21922,
    "scope": "read write"
}

A variável expires_in A chave 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

Atualizar tokens renovar API depois que o token original expirar. Se solicitado, a resposta será 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 JSON cliente no navegador.

Etapa 1: solicitar o novo token

Transmita uma solicitação de token de atualização com sua preferência JSON cliente. Ao criar a solicitação:

  • Use um POST método a ser chamado 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 testId : testSecret converter 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 variável JSON A resposta contém o novo token de acesso. A resposta deve ser semelhante a:

{
    "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

A variável 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 no https://api.demdex.com/oauth/authorize para obter acesso e atualizar tokens.

Tornar autenticado API Solicitações

Requisitos de chamada API após receber um token de autenticação.

Para fazer chamadas para o API Métodos:

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 string de solicitação ao transmitir 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 os valores especificados JSON propriedade.
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 "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 é o padrão. As permissões incluem:
  • READ : Retorna e exibe informações sobre um segmento.
  • WRITE : Uso PUT para atualizar um segmento.
  • CREATE : Uso 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 valor-chave separados. Por exemplo, para retornar uma lista de segmentos com READ e WRITE somente permissões, transmitir "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 da página não é especificada, a solicitação retorna simples JSON resulta em uma matriz. Se as informações da página é especificada, a lista retornada é encapsulada em uma variável JSON objeto 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

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 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 o RecomendadoObsoletoJWT Autenticação por meio do Adobe Developer

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 o ObsoletoOAuth Autenticação

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

A variável Audience Manager APIAs 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 em tempo real. A tabela a seguir lista os API ambientes e nomes de host de recursos correspondentes.

Dependendo do método de autenticação usado, é necessário ajustar o ambiente URLs de acordo com o quadro abaixo.

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

A variável Audience Manager o ambiente beta é uma versão independente e em 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 APIOs s são lançados 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 variável 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 Devoluções para PUT e POST solicitações.
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.

Nesta página