Compartir a través de

API de plataforma digital: semántica de API

  • Artículo

En esta página se explica la semántica de nuestra API REST. Incluye información sobre:

  • Cómo preguntar a un servicio sobre sí mismo: qué campos admite, qué campos se pueden filtrar.
  • Cómo obtener solo la información que desea mediante el filtrado y la ordenación.
  • La "forma" de nuestras respuestas JSON en diferentes escenarios.

En este documento se supone que ha completado el proceso de incorporación de API.

Protocolo HTTP

Digital Platform API 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

La dirección URL del punto de conexión de la API de producción es: https://api.appnexus.com. Tenga en cuenta que el acceso no seguro a la API del producto (HTTP) no está disponible.

Los cambios realizados con esta API afectan al entorno de producción. Solo los usuarios autorizados deben modificar la información o la configuración de este entorno.

Semántica de REST

Nuestros servicios de API 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 nuestros servicios de API y sus usos:

POST Crear
GET Lectura
PUT Actualizar
DELETE Eliminar

Al realizar una POST solicitud o PUT , debe incluir un archivo JSON con los datos para crear o actualizar.

Advertencia

PUT sobrescribe matrices a menos que 'append=true' se agregue a la cadena de consulta.

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 anexe lo siguiente a la cadena de consulta de solicitud: "append=true".

Ejemplo de solicitud "heredada" PUT para actualizar una matriz

Este ejemplo le guía por el proceso de actualizar correctamente la pixels matriz de identificador creativo 503577 mediante el método "heredado"; es decir, con el comportamiento "sobrescribir matrices en PUT" que se produce a menos que anexe la cadena "append=true" a la cadena de consulta de la solicitud.

En primer lugar, echemos un vistazo a la creatividad. Tenga en cuenta que la pixels matriz ya incluye un píxel.

$ curl -b cookies 'https://api.appnexus.com/creative?id=503577'
{
    "response": {
        "status": "OK",
        "count": 1,
        "id": "503577",
        "start_element": 0,
        "num_elements": 100,
        "creative": {
            "name": null,
            "brand_id": 1,
            "media_url": "https://creative.com/300x250",
            "id": 503577,
            ...
            "pixels": [
                {
                    "id": 196,
                    "pixel_template_id": null,
                    "param_1": null,
                    "param_2": null,
                    "param_3": null,
                    "param_4": null,
                    "param_5": null,
                    "format": "url-js",
                    "url": "https://50.16.221.228/render_js?cb=${CACHEBUSTER}&uid=${USER_ID}"
                }
            ],
            ...
        }
    }
}

A continuación, creamos el archivo JSON para agregar un nuevo píxel a la creatividad. En el archivo, se incluyen tanto el nuevo píxel que queremos agregar como el píxel que ya estaba asociado a la creatividad.

Si no se incluye el píxel existente en el archivo JSON , nuestra actualización eliminará ese píxel de la creatividad.

$ cat creative_update
{
    "creative": {
        "pixels": [
            {
                "format": "url-js",
                "url":"https://12.19.232.312/render_js?cb=${CACHEBUSTER}&uid=${USER_ID}&ref=${REFERER_URL}"
            },
            {
                "id": 196,
                "format": "url-js",
                "url": "https://50.18.232.228/render_js?cb=${CACHEBUSTER}&uid=${USER_ID}"
            }
        ]
    }
}

A continuación, se realiza una PUT llamada para actualizar la creatividad con la información del archivo JSON . Tenga en cuenta que la pixels matriz de la respuesta incluye los píxeles nuevos y antiguos.

$ curl -b cookies -X PUT -d @creative_update 'https://api.appnexus.com/creative?id=503577'
{
    "response": {
        "status": "OK",
        "count": 1,
        "id": "503577",
        "start_element": 0,
        "num_elements": 100,
        "creative": {
            "name": null,
            "brand_id": 1,
            "media_url": "https://creative.com/300x250",
            "id": 503577,
            ...
            "pixels": [
                {
                    "id": 196,
                    "pixel_template_id": null,
                    "param_1": null,
                    "param_2": null,
                    "param_3": null,
                    "param_4": null,
                    "param_5": null,
                    "format": "url-js",
                    "url": "https://50.16.221.228/render_js?cb=${CACHEBUSTER}&uid=${USER_ID}
                     &ref=${REFERER_URL}&campaign_id=147"
                },
                {
                    "id": 197,
                    "pixel_template_id": null,
                    "param_1": null,
                    "param_2": null,
                    "param_3": null,
                    "param_4": null,
                    "param_5": null,
                    "format": "url-js",
                    "url":"https://12.13.234.312/render_js?cb=${CACHEBUSTER}&uid=${USER_ID}&ref=${REFERER_URL}"
                }
            ],
            ...
        }
    }
}

Uso de cURL

En nuestra documentación usamos curl para realizar solicitudes HTTP. 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, etc. Se han proporcionado scripts de ejemplo en cada página wiki de API para ilustrar la estructura de los curl comandos que necesitará para ejecutar los servicios de LA API de Xandr. Además, a continuación se muestra un ejemplo de cómo realizar una solicitud genérica POST . En este ejemplo se usa el servicio de autenticación:

$ curl -b cookies -c cookies -X POST -d @auth.json 'https://api.appnexus.com/auth'
Fragmento de solicitud Lo que significa
-c cookies Crea un archivo de texto llamado "cookies" y almacena el token de sesión (asignado por el servicio de autenticación). Este no es un argumento necesario para curl después de la autenticación inicial, pero no afecta a las llamadas posteriores si se incluye.
-b cookies Recupera el token de autenticación que almacenó anteriormente en el archivo de "cookies" texto.
-X Indica que va a realizar un determinado tipo de solicitud, en este caso "POST".
-d Indica que va a cargar un archivo, en este caso "auth.json".
'https://api.appnexus.com/auth' Dirección URL del servicio al que realiza la solicitud. Use comillas en caso de que tenga caracteres especiales en la dirección URL.

Sugerencia

Use comillas simples alrededor de la dirección URL de la solicitud.

Algunas solicitudes requieren comillas simples alrededor de la dirección URL de la solicitud, como en la solicitud anterior curl . Si recibe un mensaje de error del shell de UNIX, asegúrese de que la dirección URL de la solicitud tenga comillas simples antes de seguir solucionando problemas. Para obtener más información sobre cómo funcionan las comillas de shell de UNIX y el escape, consulte esta documentación sobre las comillas y el escape en los shells.

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.

Sugerencia

Consulte también el servicio de búsqueda y el servicio de búsqueda para ver formas de buscar objetos en el miembro.

Nota:

Al filtrar por campos, el filtro "puede" solo respetarse si los campos usados para el filtrado se pasan en el parámetro de cadena de consulta fields.

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 de campañas solo las campañas con los identificadores 1, 2 y 3.

$ curl -bc -cc 'https://api.appnexus.com/campaign?id=1,2,3
{ 
  "response" : {
     "count" : 3,
     "status" : "OK",
     "campaigns" : [ ... ]
  }
}

Filtrar por identificadores

Pase un parámetro de cadena de consulta para el campo con una lista separada por comas de identificadores.

Ejemplos

Solicitar todas las campañas para determinados artículos de línea

$ curl -b cookies 'https://api.appnexus.com/campaign?advertiser_id=40&line_item_id=1,2,3'

Solicitar determinados anunciantes

$ curl -b cookies 'https://api.appnexus.com/advertiser?id=3'

Sugerencia

Solo se devolverán 100 objetos por solicitud.

El número máximo de objetos que se pueden devolver, 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. Para obtener más información sobre cómo paginar los resultados de la API, consulte Paginación.

Filtrar por valores mínimos y máximos

Los campos que son del tipo int, double, dateo money se pueden filtrar por min y max. Por ejemplo:

$ curl -b cookies 'https://api.appnexus.com/campaign?min_id=47'
$ curl -b cookies 'https://api.appnexus.com/campaign?min_advertiser_id=20'

Los campos del tipo date también se pueden filtrar por nmin y nmax . El nmin filtro le permite encontrar fechas que son null o posteriores a la fecha especificada, y el nmax filtro le permite encontrar fechas que son null o antes de la fecha especificada. Por ejemplo:

$ curl -b cookies 'https://api.appnexus.com/campaign?nmax_start_date=2012-12-20+00:00:00'
$ curl -b cookies 'https://api.appnexus.com/campaign?nmin_end_date=2013-01-01+00:00:00'

Tenga en cuenta la sintaxis de fecha y hora necesaria en el ejemplo anterior: AAAA-MM-DD+HH:MM:SS

Otra opción para filtrar por fecha es usar el min_last_modified filtro:

$ curl -b cookies 'https://api.appnexus.com/campaign?min_last_modified=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.appnexus.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 varios 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 'https://api.appnexus.com/placement?like_[fieldName]=partialValue'

Algunos servicios admiten search como parámetro de cadena de consulta para buscar el identificador o el nombre. Por ejemplo:

$ curl -b cookies 'https://api.appnexus.com/placement?search=17'

Ordenación

Para ordenar, use el sort parámetro de cadena de consulta y pase una lista de campos por los que desea ordenar y si desea que sean ascendentes (asc) o descendentes (desc). Por ejemplo:

$ curl -b cookies 'https://api.appnexus.com/campaign?advertiser_id=1&sort=id.desc'

Paginación

Para paginar, use los start_element parámetros y num_elements . Si num_elements no se proporciona, el valor predeterminado es 100 (que también es el valor máximo).

$ curl -b cookies 'https://api.appnexus.com/campaign?start_element=20&num_elements=10'

Anexar en PUT

Al incluir append=true en la cadena de consulta de una PUT llamada, un usuario solo puede actualizar un objeto secundario determinado en lugar de reemplazar todos los objetos secundarios. En otras palabras, en lugar de sobrescribir una matriz completa con una nueva en una PUT llamada, puede usar append=true en la cadena de consulta para agregar un único elemento a una matriz larga.

En este ejemplo, usaremos append=true en una PUT llamada para alternar la is_available marca de un objeto en la member_availabilities matriz del servicio de complementos. Sin la append=true marca de la cadena de consulta, el nuevo elemento reemplazaría toda la matriz. En este ejemplo, solo se agrega.

En primer lugar, echemos un vistazo al objeto que vamos a modificar (en estos ejemplos se usa jq para segmentar y cortar el JSON). Ambas disponibilidades se establecen en true:

Enviaremos el siguiente JSON para desactivar la is_available marca en uno de los member_availability objetos:

$ cat plugin-update.json
{
    "plugin" : {
        "developer" : {
            "id" : 1
        },
         "member_availabilities" : [
            {
                "is_available" : false,
                 "id" : 4
            }
        ],
         "name" : "ccc"
    }
}

Normalmente, el envío del JSON anterior en una PUT llamada sobrescribiría toda member_availabilities la matriz. Sin embargo, esta vez agregaremos "append=true" a la cadena de consulta de la llamada. Esto indica a la API que cambie solo el objeto cuyo id es 4. Podemos comprobar que lo ha hecho inspeccionando la salida.

$ curl -bc -X PUT -d @plugin-update.json 'https://api.appnexus.com/plugin?id=13&append=true' | jq '.response.plugin.member_availabilities'
[
  {
    "is_available": false,
    "id": 4
  },
  {
    "is_available": true,
    "id": 7
  }
]

Estructura básica json

A continuación se muestra la sintaxis de los componentes de un objeto JSON y lo que significan.

Un objeto:

{. . . }

Matriz:

[. . . ]

Cadena:

". . ."

Asocie una clave a un valor de cadena alfanumérico:

"key":"string"

Asocie una clave con un valor numérico:

"key":int

Un ejemplo que los reúne:

{
    "campaign": {
        "name": "my campaign",
        "id": 1434,
        "creatives": [
                {
                    "id": 4162,
                    "state": "active"
                }
            ],
}
}

Tipos de campo JSON

POST y PUT las solicitudes requieren datos JSON . 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. La tabla de tipos siguiente amplía los definidos en el estándar JSON.

Tipo Description Ejemplo
booleano True o false. true
string(100) Cadena de 100 caracteres o menos. "Homepage Pixel"
Entero El parámetro SyncSchedule especifica ???. Los valores válidos para este parámetro son: 87
decimal Número decimal genérico. 3.0
float Número de punto flotante con precisión de 32 bits. 3.14...
double Número de punto flotante con precisión de 64 bits. 3.14...
enumeración Uno de varios valores predeterminados. "male" o "female"
Dinero Valor numérico de punto flotante que se usa para representar dinero. 19.23
Timestamp Cadena de fecha y hora con el formato AAAA-MM-DD HH:MM:SS. Todas las zonas horarias están en UTC a menos que se indique lo contrario. "2009-01-14 05:41:04"
date Consulte la marca de tiempo anterior.
object Contenedor de cualquier subcampo en el campo actual. En el ejemplo siguiente, el campo "brand" es un objeto múltiple. Vea el ejemplo del tipo de objeto siguiente.
matriz Lista que contiene uno o varios valores. En nuestra API, las matrices suelen contener listas de objetos, enteros o cadenas. Vea el ejemplo para el tipo de matriz siguiente.

Ejemplo de tipo de objeto

"brand": {
"id": 466,
"name": "PKR"
}

Ejemplo de tipo de matriz

"members" : [
{
"id": 1234,
"member_use_deal_floor": true,
"member_ask_price": 2.15,
"name": "Buyer 1"
},
{
"id": 5561,
"member_use_deal_floor": true,
"member_ask_price": 2.25,
"name": "Buyer 2"
}
]

¿Cómo y por qué las API de informes son diferentes?

Las API de informes disponibles a través del servicio de informes funcionan de forma diferente a nuestras otras API. Tienen su propio flujo de solicitud y respuesta de varios pasos. Esto es necesario porque procesan grandes cantidades de datos; Este procesamiento debe realizarse de forma asincrónica.

Para obtener instrucciones sobre cómo recuperar informes, consulte el servicio de informes.

Para obtener un tutorial en el que se explica cómo usar las API de informes de forma eficaz, consulte Paginación de informes.

Nota sobre guiones bajos y guiones

Los campos y valores JSON usan caracteres de subrayado, por ejemplo, audit_type_direct.

Los nombres de servicio de API en las direcciones URL se dividen en guiones, por ejemplo, https://api.``appnexus``.com/insertion-order.

Códigos de respuesta

Todos los servicios de API devuelven datos JSON . Cuando las llamadas de servicio se realizan correctamente, la respuesta JSON incluirá un "status" campo establecido en "OK". La respuesta a POST y PUT las llamadas también incluirá el identificador del objeto pertinente, así como los atributos pertinentes de ese objeto. Cada respuesta incluye un "dbg_info" objeto que transmite información sobre la llamada api y la respuesta que es solo para uso interno de Xandr y que se puede solicitar durante una consulta de soporte técnico.

Mensajes de error

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

$ cat auth
{
  "auth": {
     "username":"user1",
     "password":"Wr0ngP@ss"
  }
}
$ curl -b cookies -c cookies -X POST -d @auth 'https://api.appnexus.com/auth'
{
    "response": {
        "error_id": "NOAUTH"
        "error": "No match found for user\/pass",
        "dbg_info": {
            ...
        }
    }
}

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 como se describe en la tabla siguiente.

Error_ID Significado Cómo responder
INTEGRITY Una solicitud de cliente es incoherente; por ejemplo, una solicitud intenta eliminar una creatividad predeterminada adjunta a una ubicación activa. Compruebe la coherencia de la lógica de solicitud.
LIMIT El usuario ha alcanzado el número máximo de objetos permitidos de un tipo determinado. Elimine objetos innecesarios para obtener por debajo del límite. Si no puede eliminar ningún objeto, póngase en contacto con su representante de Xandr.
NOAUTH El usuario no ha iniciado sesión o las credenciales de inicio de sesión no son válidas. Use el servicio de autenticación para obtener un token o compruebe el nombre de usuario y la contraseña en la solicitud.
NOAUTH_DISABLED Se ha desactivado la cuenta del usuario. Inicie sesión con otro usuario o cree una cuenta de usuario específicamente para el acceso a la API.
NOAUTH_EXPIRED La contraseña del usuario ha expirado y debe restablecerse. Use el servicio de autenticación para obtener un nuevo token.
SYNTAX La sintaxis de la solicitud es incorrecta. Use el "error" mensaje para identificar el problema y corregir el código.
SYSTEM Se ha producido un error del sistema. Póngase en contacto con su representante de Xandr.
UNAUTH El usuario no está autorizado para realizar la acción solicitada. Compruebe el "error" mensaje y asegúrese de que la lógica del código es correcta.