Show Menu
TÓPICOS×

Introdução às APIs REST

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

Requisitos e recomendações da API

As coisas que você deve e deve fazer ao trabalhar com o Audience Manager APIs.
Observe o seguinte ao trabalhar com o código da API do Audience Manager:
  • **** Parâmetros de solicitação: Todos os parâmetros de solicitação são necessários, a menos que especificado de outra forma.
  • JSON tipo de conteúdo: Especifique content-type: application/json e especifique accept: application/json no seu código.
  • **** Solicitações e respostas: Envie 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 fazer API solicitações.
  • **** Documentação e amostras de código: O texto em itálico representa uma variável fornecida ou transmitida 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.

Recomendações: Criar um usuário de API genérico

Recomendamos que você crie uma conta de usuário técnica e separada para trabalhar com o 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 API usuário ajuda você a realizar duas coisas:
  • Identifique o serviço que está chamando o API (por exemplo, chamadas de seus aplicativos que usam nossos APIs ou de outras ferramentas que fazem API solicitações).
  • Fornecer 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 API código 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 não específica, API 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 os Audience Manager APIs.
Entre em contato com seu consultor do Audience Manager para configurar uma conta de usuário genérica e APIexclusiva.

OAuth Authentication

O 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 os APIs.

Fluxo de trabalho da autenticação de senha

Autenticação de senha, acesso seguro a nossa REST APIsenha. As etapas abaixo descrevem o fluxo de trabalho para autenticação por senha de um JSON cliente em seu navegador.
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 seu gerente de soluções de parceiros. Eles fornecerão uma ID de API 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 API acesso.

Etapa 2: Solicite o token

Transmita uma solicitação de token com seu JSON cliente preferencial. Ao criar a solicitação:
  • Use um POST método 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 são testId : testSecret convertidas em dGVzdElkOnRlc3RTZWNyZXQ= .
  • Passe nos HTTP cabeçalhos 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 JSON resposta contém seu token de acesso. A resposta deve ser a seguinte:
{
    "access_token": "28fed402-eafd-456c-9341-ac753f25bbbc",
    "token_type": "bearer",
    "refresh_token": "b27122c0-b0c7-4b39-a71b-1547a3b3b88e",
    "expires_in": 21922,
    "scope": "read write"
}

A expires_in chave 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

Atualizar tokens renovam o API acesso após 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 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 cabeçalho 401 Status Code e o seguinte 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 JSON cliente em seu navegador.

Etapa 1: Solicitar o novo token

Passe uma solicitação de token de atualização com o seu JSON cliente preferencial. Ao criar a solicitação:
  • Use um POST método 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 são testId : testSecret convertidas em dGVzdElkOnRlc3RTZWNyZXQ= .
  • Transmita 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 token de atualização grant_type:refresh_token e passe-o na solicitação de acesso anterior. A solicitação deve ser semelhante a:
    grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e

Etapa 2: Receber o novo token

A JSON resposta contém seu novo token de acesso. A resposta deve ser a seguinte:
{
    "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 para obter acesso e atualizar tokens https://api.demdex.com/oauth/authorize para que possam acessá-los.

Fazer solicitações de API autenticadas

Requisitos para chamar API métodos depois de receber um token de autenticação.
Para efetuar chamadas em relação aos API métodos disponíveis:
  • No HTTP cabeçalho, defina Authorization: Bearer <token> .
  • Chame o API método necessário.

Parâmetros de consulta de 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 API métodos que retornam todas as propriedades de um objeto. Defina essas opções na string de solicitação ao passar essa consulta para o API.
Parâmetro
Descrição
página
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 é padrão).
sortBy
Classifica e retorna os resultados de acordo com a JSON propriedade especificada.
descendente
Classifica e retorna os resultados em ordem decrescente. Crescente é padrão.
pesquisa
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://api.demdex.com/v1/models/?search=Test . Você pode pesquisar qualquer valor retornado por um método "obter tudo".
folderId
Retorna todas as IDs para características dentro da pasta especificada. Não disponível para todos os métodos.
permissões
Retorna uma lista de segmentos com base na permissão especificada. LER é 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 à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 somente com READ e WRITE permissões, passe "permissions":"READ" , "permissions":"WRITE" .
includePermissions
(Booliano) Defina como true para retornar suas permissões para o segmento. O padrão é falso.

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 JSON resultados simples em uma matriz. Se as informações da página forem especificadas, a lista retornada será encapsulada em um JSON objeto 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://api.demdex.com/v1/models/?page=1&pageSize=2&search=Test

URLs de API

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

Solicitar URLs

A tabela a seguir lista os URLs de solicitação usados para passar em API solicitações, por método.
API Métodos
Solicitação URL
Modelagem algorítmica
https://api.demdex.com/v1/models/
Fonte de dados
https://api.demdex.com/v1/datasources/
Sinais derivados
https://api.demdex.com/v1/signals/derived/
Destinos
https://api.demdex.com/v1/destinations/
Domínios
https://api.demdex.com/v1/partner-sites/
Pastas
Características: https://api.demdex.com/v1/folders/traits /
Segmentos: https://api.demdex.com/v1/folders/segments /
Esquema
https://api.demdex.com/v1/schemas/
Segmentos
https://api.demdex.com/v1/segments/
Características
https://api.demdex.com/v1/traits/
Tipos de características
https://api.demdex.com/v1/customer-trait-types
Taxonomia
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 códigos em bancos de dados separados sem afetar os dados de produção ao vivo. A tabela a seguir lista os API ambientes disponíveis e os nomes dos hosts de recursos correspondentes.
Ambiente
Nome de host
Produção
https://api.demdex.com/...
Beta
https://api-beta.demdex.com/...
O ambiente beta do 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.

Versões

Novas versões desses APIs são lançadas regularmente. Uma nova versão aumenta o número da API versão. O número da versão é referenciado no URL da solicitação, conforme v<version number> 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
Criado
O recurso foi criado. Retorna para PUT e POST solicitações.
204
Sem conteúdo
O recurso foi excluído. O corpo da resposta ficará em branco.
400
Solicitação inválida
O servidor não entendeu a solicitação. Normalmente devido a sintaxe malformada. Verifique sua solicitação e tente novamente.
403
Proibido
Você não tem acesso ao recurso.
404
Não encontrada
Não foi possível localizar o recurso para o caminho especificado.
409
Conflito
Não foi possível concluir a solicitação devido a um conflito com o estado do recurso.
500
Erro do servidor
O servidor encontrou um erro inesperado que o impedia de atender à solicitação.