Licitadores: semántica de API
En esta página se explica cómo trabajar con nuestra API REST del bus de impresiones. Incluye información sobre:
- Autenticación
- Cómo preguntar a un servicio sobre sí mismo: qué campos admite, qué campos se pueden usar para filtrar
- Códigos de respuesta y errores
Nota:
Para obtener más información sobre cómo trabajar con servicios de API específicos, consulte los vínculos de Servicios de API.
Protocolo HTTP
La API del bus de impresiones de Xandr admite el protocolo HTTP versión 1.1 o posterior. Aunque algunas llamadas pueden funcionar con la versión 1.0 en desuso, esto no está garantizado. Asegúrese de que el cliente se comunica con al menos la versión 1.1.
Puntos de conexión de API
| Entorno | URL | Notas |
|---|---|---|
| Producción | https://api.adnxs.com |
Necesitamos usar un punto de conexión seguro (https://) para nuestra API de producción para garantizar la privacidad de los datos. El acceso no seguro a la API del producto (HTTP) no está disponible. |
REST
Los servicios de API de Xandr son "RESTful". REST (transferencia de estado representacional) es un tipo de arquitectura de software en la que las solicitudes modela la comunicación desde un explorador web a un servidor web. A continuación se muestran los métodos REST centrales que se usan en los servicios de API de Xandr y sus usos:
| Rest (método) | Uso |
|---|---|
| POST | create/add |
| GET | lectura y recuperación |
| PUT | actualizar o modificar |
| DELETE | delete |
En nuestra documentación usamos cURL para realizar solicitudes REST. cURL es una herramienta de línea de comandos para transferir archivos con sintaxis url, compatible con FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, LDAP, LDAPS y FILE. Los scripts de ejemplo de cada página wiki de API delearán claramente la estructura de los cURL comandos que necesitará para ejecutar los servicios de API de Xandr.
Anexar en PUT
En PUT el caso de las solicitudes, solo se actualizarán los campos incluidos en el archivo JSON , excepto en el caso de las matrices.
Al actualizar una matriz mediante PUT, todos los campos de la matriz se sobrescriben con el contenido de la nueva matriz que cargue, a menos que agregue esto a la cadena de consulta de la solicitud: "append=true".
Meta llamadas
Todos los servicios del licitador admiten meta llamadas, que devolverán los campos del servicio y el tipo de valor. Las meta llamadas tienen este aspecto:
$ curl -b cookies -c cookies 'https://api.adnxs.com/SERVICE/meta'
Por ejemplo (salida parcial de una metallamada):
"bidder_id": {
"type": "int"
},
"agent_id": {
"type": "int"
},
"code": {
"type": "string"
},
"active": {
"type": "boolean"
}
Limitación de registros de solicitudes GET
Agregar esta cadena al final de cualquier solicitud GET a la API limitará el número de registros recuperados:
?start_element=N&num_elements=N
Ejemplos
segment/1?start_element=0&num_elements=1000
member?start_element=0&num_elements=100
creative/1?start_element=0&num_elements=200
Nota:
El número máximo de elementos que se pueden devolver independientemente de la solicitud es 100.
- El primer elemento es el elemento 0.
- Todas las respuestas GET tendrán una propiedad "count" que muestra el número total de elementos que coinciden con la solicitud GET.
- Esto también se aplicará a los servicios que no son de informes, como el servicio de búsqueda creativa, que se solicitan con métodos distintos de los GET.
Filtrado y ordenación
La mayoría de los servicios de API admiten el filtrado y la ordenación. El filtrado permite especificar un subconjunto de objetos que se van a devolver. La ordenación permite controlar el orden de los objetos devueltos.
Obtención de varios objetos por identificador
Puede obtener varios objetos específicos por identificador pasando una lista separada por comas de identificadores. El objeto de resultado contendrá una matriz que contiene solo esos objetos específicos. En el ejemplo siguiente, pedimos al Servicio creativo solo las creatividades con los identificadores 1, 2 y 3.
$ curl -bc -cc 'https://api.adnxs.com/creative?id=1,2,3
{
"response" : {
"count" : 3,
"status" : "OK",
"creatives" : [ ... ]
}
}
Filtrar por identificadores
Pase un parámetro de cadena de consulta para el campo con una lista separada por comas de identificadores.
Ejemplo: Solicitar todas las creatividades para determinados miembros
$ curl -b cookies -c cookies 'https://api.adnxs.com/creative?member_id=123,987'
Nota:
El número máximo de objetos que se pueden devolver por solicitud, independientemente de la paginación, es 100. Si solicita más de 100 objetos, solo devolveremos los primeros 100 y no proporcionaremos un mensaje de error.
Filtrar por Min y Max valores
Los campos que son del tipo int, double, dateo money se pueden filtrar por min y max. Por ejemplo:
$ curl -b cookies -c cookies 'https://api.adnxs.com/creative?min_id=47'
$ curl -b cookies -c cookies 'https://api.adnxs.com/creative?min_brand_id=20'
Los campos del tipo date se pueden filtrar mediante el min_last_modified filtro . Tenga en cuenta la sintaxis de fecha y hora necesaria: AAAA-MM-DD+HH:MM:SS
$ curl -b cookies 'https://api.adnxs.com/creative/114?min_last_activity=2017-10-27+21:00:00'
Filtrar por nombres de campo
Para limitar la respuesta a campos específicos de un objeto, pase el fields parámetro de cadena de consulta con una lista separada por comas de nombres de campo. Por ejemplo:
$ curl -b cookies "https://api.adnxs.com/user/current&fields=username,user_type,id"
{
"response":{
"status":"OK",
"count":1,
"start_element":0,
"num_elements":100,
"user":{
"id":14311,
"username":"rloveland",
"user_type":"admin"
}
}
}
Filtros erróneos en el campo
Se admiten los siguientes filtros adicionales basados en campos en las respuestas de API:
not_*like_*min_*max_*nmin_*nmax_*having_*having_min_*having_max_*
Ejemplo
$ curl -b cookies -c cookies 'https://api.adnxs.com/creative?like_[fieldName]=partialValue'
Valores de campo JSON
POST y PUT las solicitudes requieren datos con formato JSON. POST por lo general, la solicitud crea objetos en la base de datos y, por tanto, requiere toda la información sobre ese objeto (a menos que se modifique posteriormente mediante una solicitud PUT). En PUT el caso de las solicitudes, solo se actualizarán los campos JSON incluidos en una solicitud. Todos los demás campos no se modificarán.
Los campos diferentes requieren diferentes tipos de valores.
| Tipo | Description | Ejemplo |
|---|---|---|
| Matriz | Se permite más de un valor | [87,45] |
| Booleano | Verdadero/Falso | Verdadero |
| Doble | Número de punto flotante con dos veces el espacio de bits de un float. | 3.12 |
| Enum | Un elemento de una matriz de valores preasignados solo | hombre/mujer |
| Float | Número de punto flotante | 3.12 |
| Int | Entero | 87 |
| String(100) | Cadena de 100 caracteres o menos | male_26_likes_cheese |
| Timestamp | Cadena de fecha y hora con el formato AAAA-MM-DD HH:MM:SS | 2009-01-14 05:41:04 |
| Unsigned | Solo enteros positivos | 745 |
Autenticación
Para poder usar las API, debe autenticarse con su nombre de usuario y contraseña. Consulte Servicio de autenticación para obtener más información.
Códigos de respuesta
Todos los servicios de API devuelven datos con formato JSON. Cuando las llamadas de servicio se realizan correctamente, la respuesta JSON incluirá un "status" campo establecido en "OK". La respuesta a las llamadas POST y PUT también incluirá el identificador del objeto pertinente, como el licitador, miembro, etiqueta o creativo, así como los atributos pertinentes de ese objeto. (En el ejemplo siguiente, estamos usando cookies para almacenar nuestro token de autenticación y agregar el archivo "tag" al servicio de etiquetas tiny).
$ curl -b cookies -c cookies -X POST --data-binary @tag https://api.adnxs.com/tt/32/
{
"response": {
"status": "OK",
"id": "242"
}
}
Errores
Cuando se envía una entrada no válida a la API (por ejemplo, una contraseña incorrecta), se devolverá una respuesta JSON con "error" campos y "error_id" . Para algunas condiciones de error, también puede ver los campos opcionales "error_description" y "error_code" .
$ curl -b cookies -c cookies 'https://api.adnxs.com/api/auth?username=admin&password=Wr0ngP@ss'
{
"response": {
"error": "No match found for user\/pass",
"error_id": "NOAUTH"
}
}
El "error" campo es útil para fines de depuración, ya que contiene una descripción detallada del error. El "error_id" campo se puede usar mediante programación de la siguiente manera:
| Error_ID | Significado | Lógica |
|---|---|---|
| NOAUTH | Falta información de autenticación o no es válida | Uso de /auth para obtener un token válido |
| UNAUTH | El usuario no está autorizado para realizar la acción solicitada. | Compruebe el mensaje "error" y asegúrese de que la lógica es correcta en el código. |
| SINTAXIS | La sintaxis de la solicitud es incorrecta | Use el mensaje "error" para identificar el problema y corregir el código. |
| SYSTEM | Se ha producido un error del sistema | Ponerse en contacto con Xandr |
| INTEGRIDAD | Una solicitud de cliente es incoherente; por ejemplo, un intento de eliminar una creatividad predeterminada adjunta a un TinyTag activo | Comprobación de la solicitud de integridad |