Show Menu
TEMAS×

Introducción a las API de REST

Información sobre requisitos generales, autenticación, parámetros de consulta opcionales, direcciones URL de solicitud y otras referencias.

Requisitos de API y recomendaciones

Cosas que debe y debe hacer al trabajar con Audience Manager APIs.
Tenga en cuenta lo siguiente al trabajar con el código de API de Audience Manager:
  • **** Parámetros de solicitud: Todos los parámetros de solicitud son obligatorios a menos que se especifique lo contrario.
  • JSON tipo de contenido: Especifique content-type: application/json y ** accept: application/json en el código.
  • **** Solicitudes y respuestas: Enviar solicitudes como un JSON objeto con el formato correcto. Audience Manager responde con datos con JSON formato. Las respuestas del servidor pueden contener datos solicitados, un código de estado o ambos.
  • **** Acceso: Su Audience Manager asesor le proporcionará un ID de cliente y una clave que le permitirá realizar API solicitudes.
  • **** Ejemplos de documentación y código: El texto en cursiva representa una variable que se proporciona o pasa al crear o recibir API datos. Reemplace el texto en cursiva con su propio código, parámetros u otra información requerida.

Recomendaciones: Creación de un usuario de API genérico

Le recomendamos que cree una cuenta de usuario técnica independiente para trabajar con Audience Manager APIs. Es una cuenta genérica que no está vinculada a un usuario específico de su organización ni asociada a él. Este tipo de cuenta de API usuario le ayuda a realizar dos tareas:
  • Identifique qué servicio llama a la API (p. ej., llamadas desde sus aplicaciones que usan nuestros APIo desde otras herramientas que realizan API solicitudes).
  • Proporcionar acceso ininterrumpido a los APIinformes. Una cuenta vinculada a una persona específica puede ser eliminada cuando abandone su empresa. Esto impedirá que trabaje con el API código disponible. Una cuenta genérica que no está vinculada a un empleado en particular le ayuda a evitar este problema.
Como ejemplo o caso de uso para este tipo de cuenta, supongamos que desea cambiar muchos segmentos a la vez con las Herramientas de administración masiva. Bueno, para hacerlo, su cuenta de usuario necesita API acceso. En lugar de agregar permisos a un usuario específico, cree una cuenta de usuario no específica que tenga las credenciales, la clave y el secreto adecuados para realizar API API llamadas. Esto también resulta útil si desarrolla sus propias aplicaciones que utilizan Audience Manager APIs.
Póngase en contacto con su asesor de Audience Manager para configurar una cuenta de usuario genérica APIde solo.

OAuth Authentication

Audience Manager REST API sigue OAuth 2.0 los estándares de autenticación y renovación de testigos. Las secciones siguientes describen cómo autenticarse y comenzar a trabajar con APIs.

Flujo de trabajo de autenticación de contraseña

Autenticación de contraseña acceso seguro a nuestro REST API. Los pasos a continuación describen el flujo de trabajo para la autenticación de contraseña de un JSON cliente en su explorador.
Cifre los tokens de acceso y actualícelos si los almacena en una base de datos.

Paso 1: Solicitar acceso a API

Póngase en contacto con el administrador de soluciones de socio. Le proporcionarán un ID de API cliente y un secreto. El ID y el secreto le autentican en el API.
Nota: Si desea recibir un autentificador de actualización, especifíquelo cuando solicite API acceso.

Paso 2: Solicitar el token

Pasa una solicitud de token con tu JSON cliente preferido. Al generar la solicitud:
  • Utilice un POST método para llamar https://api.demdex.com/oauth/token .
  • Convierta el ID de cliente y el secreto en una cadena con codificación base-64. Separe el ID y el secreto con dos puntos durante el proceso de conversión. Por ejemplo, las credenciales testId : testSecret se convierten en dGVzdElkOnRlc3RTZWNyZXQ= .
  • Pasa los HTTP encabezados Authorization:Basic <base-64 clientID:clientSecret> y Content-Type: application/x-www-form-urlencoded . Por ejemplo, el encabezado podría tener este aspecto:
    Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
    Content-Type: application/x-www-form-urlencoded
  • Configure el cuerpo de la solicitud de la siguiente manera:
    grant_type=password&username=<your-AudienceManager-user-name>&password=<your-AudienceManager-password>

Paso 3: Recibir el token

La JSON respuesta contiene el autentificador de acceso. La respuesta debería tener este aspecto:
{
    "access_token": "28fed402-eafd-456c-9341-ac753f25bbbc",
    "token_type": "bearer",
    "refresh_token": "b27122c0-b0c7-4b39-a71b-1547a3b3b88e",
    "expires_in": 21922,
    "scope": "read write"
}

La expires_in tecla representa el número de segundos hasta que caduca el autentificador de acceso. Se recomienda utilizar tiempos de caducidad cortos para limitar la exposición si el token se expone alguna vez.

Actualizar token

Actualice los tokens para renovar API el acceso después de que caduque el token original. Si se solicita, la respuesta JSON en el flujo de trabajo de contraseña incluye un token de actualización. Si no recibe un token de actualización, cree uno nuevo mediante el proceso de autenticación de contraseña.
También puede utilizar un token de actualización para generar un nuevo token antes de que caduque el autentificador de acceso existente.
Si el autentificador de acceso ha caducado, recibirá un 401 Status Code y el siguiente encabezado en la respuesta:
WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"
Los pasos siguientes describen el flujo de trabajo para utilizar un token de actualización para crear un nuevo autentificador de acceso desde un JSON cliente en el explorador.

Paso 1: Solicitar el nuevo token

Pasa una solicitud de token de actualización con el JSON cliente preferido. Al generar la solicitud:
  • Utilice un POST método para llamar https://api.demdex.com/oauth/token .
  • Convierta el ID de cliente y el secreto en una cadena con codificación base-64. Separe el ID y el secreto con dos puntos durante el proceso de conversión. Por ejemplo, las credenciales testId : testSecret se convierten en dGVzdElkOnRlc3RTZWNyZXQ= .
  • Pasa los encabezados HTTP Authorization:Basic <base-64 clientID:clientSecret> y Content-Type: application/x-www-form-urlencoded . Por ejemplo, el encabezado podría tener este aspecto:
    Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
    Content-Type: application/x-www-form-urlencoded
  • En el cuerpo de la solicitud, especifique grant_type:refresh_token y pase el token de actualización que recibió en la solicitud de acceso anterior. La solicitud debería tener este aspecto:
    grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e

Paso 2: Recibir el nuevo token

La JSON respuesta contiene el nuevo token de acceso. La respuesta debería tener este aspecto:
{
    "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 autorización y autenticación implícita

Audience Manager REST API admite código de autorización y autenticación implícita. Para utilizar estos métodos de acceso, los usuarios deben iniciar sesión para https://api.demdex.com/oauth/authorize obtener acceso y actualizar los tokens.

Realizar solicitudes de API autenticadas

Requisitos para llamar a API métodos después de recibir un autentificador.
Para realizar llamadas con los API métodos disponibles:
  • En el HTTP encabezado, establezca Authorization: Bearer <token> .
  • Llame al API método requerido.

Parámetros de consulta API opcionales

Establezca los parámetros opcionales disponibles para los métodos que devuelven todas las propiedades de un objeto.
Puede utilizar estos parámetros opcionales con API métodos que devuelven todas las propiedades de un objeto. Configure estas opciones en la cadena de solicitud al pasar esa consulta al API.
Parámetro
Descripción
página
Devuelve los resultados por número de página. La numeración empieza en 0.
pageSize
Define el número de resultados de respuesta que devuelve la solicitud (10 es el valor predeterminado).
sortBy
Ordena y devuelve resultados según la JSON propiedad especificada.
descendente
Ordena y devuelve los resultados en orden descendente. Ascendente es el valor predeterminado.
OR
Devuelve los resultados en función de la cadena especificada que desee utilizar como parámetro de búsqueda. Por ejemplo, supongamos que desea buscar resultados para todos los modelos que tienen la palabra "Prueba" en cualquiera de los campos de valor para ese elemento. Su solicitud de muestra podría tener este aspecto: GET https://api.demdex.com/v1/models/?search=Test . Puede buscar cualquier valor devuelto por un método "get all".
folderId
Devuelve todos los ID de características dentro de la carpeta especificada. No está disponible para todos los métodos.
permisos
Devuelve una lista de segmentos basada en el permiso especificado. READ es el valor predeterminado. Los permisos incluyen:
  • READ :: Devolver y ver información sobre un segmento.
  • WRITE :: Se utiliza PUT para actualizar un segmento.
  • CREATE :: Se utiliza POST para crear un segmento.
  • DELETE : Eliminar un segmento. Requiere acceso a las características subyacentes, si las hay. Por ejemplo, necesitará derechos para eliminar las características que pertenecen a un segmento si desea eliminarlo.
Especifique varios permisos con pares de clave-valor independientes. Por ejemplo, para devolver una lista de segmentos solo con READ y WRITE permisos, pase "permissions":"READ" , "permissions":"WRITE" .
includePermissions
(Booleano) Establezca en true para devolver los permisos del segmento. El valor predeterminado es false.

Una nota sobre las opciones de página

Cuando no se especifica la información de la página , la solicitud devuelve JSON resultados sencillos en una matriz. Si se especifica la información de la página, la lista devuelta se envuelve en un JSON objeto que contiene información sobre el resultado total y la página actual. La solicitud de muestra con opciones de página podría tener un aspecto similar a este:
GET https://api.demdex.com/v1/models/?page=1&pageSize=2&search=Test

API URL

URLs para solicitudes, entornos de ensayo y producción y versiones.

URL de solicitud

La siguiente tabla enumera las direcciones URL de solicitud utilizadas para pasar API solicitudes, por método.
API Métodos
Solicitud URL
Modelado algorítmico
https://api.demdex.com/v1/models/
Fuente de datos
https://api.demdex.com/v1/datasources/
Señales derivadas
https://api.demdex.com/v1/signals/derived/
Destinos
https://api.demdex.com/v1/destinations/
Dominios
https://api.demdex.com/v1/partner-sites/
Carpetas
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
Taxonomía
https://api.demdex.com/v1/taxonomies/0/

Entornos

Los Audience Manager dos APIproporcionan acceso a diferentes entornos de trabajo. Estos entornos le ayudan a probar el código con bases de datos independientes sin afectar a los datos de producción activos. La siguiente tabla enumera los entornos disponibles API y los nombres de host de recursos correspondientes.
Entorno
Nombre del host
Producción
https://api.demdex.com/...
Beta
https://api-beta.demdex.com/...
El entorno beta de Audience Manager es una versión independiente de menor escala del entorno de producción. Todos los datos que desee probar deben introducirse y recopilarse en este entorno.

Versiones

Las nuevas versiones de estos APIinformes se publican con regularidad. Una nueva versión incrementa el número de la API versión. Se hace referencia al número de versión en la dirección URL de la solicitud, como v<version number> se muestra en el siguiente ejemplo:
https://<host>/v1/...

Códigos de respuesta definidos

HTTP códigos de estado y texto de respuesta devueltos por Audience Manager REST API.
ID del código de respuesta
Texto de respuesta
Definición
200
OK
La solicitud se procesó correctamente. Devolverá el contenido o los datos esperados si es necesario.
201
Creado
Se creó el recurso. Devuelve PUT y POST solicitudes.
204
Sin contenido
Se eliminó el recurso. El cuerpo de la respuesta estará en blanco.
400
Solicitud incorrecta
El servidor no entendía la solicitud. Generalmente debido a una sintaxis mal formada. Compruebe su solicitud e inténtelo nuevamente.
403
Prohibido
No tiene acceso al recurso.
404
No encontrado
No se encontró el recurso para la ruta especificada.
409
Conflicto
No se pudo completar la solicitud debido a un conflicto con el estado del recurso.
500
Error del servidor
El servidor encontró un error inesperado que le impedía cumplir la solicitud.