Leer en inglés

Compartir a través de


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

Servicios de API del licitador