Restricciones de uso de la API de Impression Bus
En este artículo se proporciona información sobre las restricciones a las que se enfrentan al usar las API.
Para garantizar un buen rendimiento, los servicios de la plataforma implementan la limitación de velocidad tanto en los niveles de usuario como de servicio. Estos límites, establecidos por el servicio, pueden cambiar con el tiempo.
Cuando los usuarios encuentran solicitudes limitadas por velocidad, la API responderá con uno de los dos códigos de respuesta, junto con los encabezados pertinentes, para indicar el motivo y cómo proceder:
Http 429 (demasiadas solicitudes) indica que el usuario ha superado el número máximo de llamadas de usuario a este servicio.
Esto siempre indica una respuesta de velocidad limitada, pero para obtener detalles específicos, consulte los encabezados y la respuesta. Algunas aplicaciones pueden imponer limitaciones adicionales que desencadenan un error 429, pero proporcionarán información adicional sobre la ubicación y el motivo del límite.
Las solicitudes limitadas de velocidad de plataforma general incluirán el
x-ratelimit-code
encabezado .
EL HTTP 503 (Servicio no disponible) se produce cuando el servicio está sobrecargado por las solicitudes y limita las nuevas.
- Si el 503 procede de la limitación de velocidad, habrá un
x-ratelimit-code
encabezado.
- Si el 503 procede de la limitación de velocidad, habrá un
Si está experimentando más llamadas con tarifas limitadas de las previstas, póngase en contacto con el representante de su cuenta de Xandr.
Si supera el límite de limitación, la API responderá con el código de respuesta HTTP 429 o HTTP 503.
Si usa un script, debe buscar el código de respuesta 429 o un código 503 que también incluya el x-ratelimit-code
encabezado. Si recibe este código, suspenda el script para el número devuelto en el Retry-After
campo del encabezado de respuesta. Este campo le indica cuánto tiempo antes de restablecer el límite de limitación y puede seguir enviando solicitudes de API.
Las solicitudes limitadas en el nivel de usuario devolverán un 429 con los siguientes encabezados de límite de velocidad:
-
x-ratelimit-code
: corresponde al código HTTP devuelto cuando la llamada era de velocidad limitada. -
retry-after
: muestra el tiempo en segundos que se debe esperar antes de volver a intentar la solicitud. -
x-ratelimit-count
: muestra el recuento total en las llamadas que el usuario ha realizado dentro del período límite. Los usuarios pueden hacer referencia a este número para ajustar sus patrones de llamadas al ver solicitudes de velocidad limitada. -
x-an-user-id
: identificador de usuario limitado.
Ejemplo 429 de encabezados de solicitud limitados:
< HTTP/1.1 429 Too Many Requests
< Server: nginx/1.11.10
< Date: Fri, 02 Feb 2024 15:58:18 GMT
< Content-Type: application/json; charset=utf-8
< Content-Length: 358
< Connection: keep-alive
< Retry-After: 9
< x-b3-traceid: 9f53184f6e2c3cb9
< x-ratelimit-code: 429
< x-an-user-id: 1234
< x-ratelimit-count: 1000
< retry-after: 24
Las solicitudes limitadas en el nivel de servicio devolverán un 503 con los siguientes encabezados de límite de velocidad:
-
x-ratelimit-code
: corresponde al código HTTP devuelto cuando la llamada era de velocidad limitada. -
retry-after
: muestra el tiempo en segundos que se debe esperar antes de volver a intentar la solicitud.
Ejemplo 503 de encabezados de solicitud limitados:
< HTTP/1.1 429 Too Many Requests
< Server: nginx/1.11.10
< Date: Fri, 02 Feb 2024 15:58:18 GMT
< Content-Type: application/json; charset=utf-8
< Content-Length: 358
< Connection: keep-alive
< Retry-After: 9
< x-b3-traceid: 9f53184f6e2c3cb9
< x-ratelimit-code: 503
< retry-after: 24
Los encabezados siguientes de las respuestas están en desuso y se quitarán en el futuro. Ya no proporcionan ninguna información relevante. Ajuste los scripts que los usen para usar los nuevos encabezados, como se describió anteriormente.
- x-count-read
- x-count-write
- Límites de velocidad x
- x-ratelimit-read
- x-ratelimit-write
- x-ratelimit-system
Además del código de respuesta y el encabezado de respuesta, cada respuesta de la API contendrá un dbg_info
parámetro. Este parámetro contiene información sobre la llamada y la respuesta de la API. A continuación se muestra un ejemplo de esta salida de depuración, que incluye las advertencias recibidas de la API, la versión de API usada para la llamada que generó esta respuesta y el servicio usado.
{
"response": {
"status": "OK",
...
"dbg_info": {
"warnings": [],
"version": "1.18.349",
"output_term": "user"
}
}
}
El número máximo de objetos que se pueden devolver en una respuesta GET determinada es 100. Para recuperar más de 100 objetos, puede paginar los resultados especificando start_element
y num_elements
en la cadena de consulta de la solicitud GET. Por ejemplo, la siguiente solicitud devolvería los primeros 50 objetos de la respuesta:
$ curl -b cookies -c cookies 'https://api.adnxs.com/creative?start_element=0&num_elements=50'
Para recuperar los 50 siguientes, simplemente establecería start_element=50
.
- 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.
$ curl -b cookies -c cookies 'https://api.adnxs.com/segment?start_element=0&num_elements=100'
$ curl -b cookies -c cookies 'https://api.adnxs.com/user?start_element=0&num_elements=100'
Después de autenticarse, el token permanece válido durante 2 horas. No es necesario volver a autenticarse en este momento. Si vuelve a autenticarse, tenga en cuenta la siguiente limitación: La API le permite autenticarse correctamente 10 veces por período de 5 minutos. Los intentos de autenticación posteriores en esos 5 minutos producirán un error.
Sugerencia
Se recomienda escuchar la error_id "NOAUTH" en las respuestas de llamada y volver a autenticarse solo después de recibirla.
Xandr limita el número de elementos de línea, campañas, creativos, editores, sitios y ubicaciones que puede tener en la plataforma. Además, Xandr limita el número de dominios que se pueden usar en una sola lista de dominios y el número de destinos determinados que se pueden usar en un único perfil. Puede usar el servicio de límite de objetos para ver los límites y supervisar de forma proactiva el uso.
Sugerencia
Para todos los tipos de objeto excepto las creatividades, los objetos activos e inactivos se cuentan con respecto al límite. En el caso de las creatividades, solo los objetos no expirados se cuentan con respecto al límite. Una creatividad expira cuando no se ha servido ni se ha modificado en 45 días.
Para la mayoría de los clientes, los límites de objetos predeterminados son los siguientes:
Objeto | Límite |
---|---|
Creatividades por miembro Nota: Solo las creatividades no expiradas se cuentan con este límite. |
10,000 |
Campañas por miembro | 10,000 |
Elementos de línea por miembro | 3,000 |
Ubicaciones por miembro | 20,000 |
Sitios por miembro | 10,000 |
Publicadores por miembro | 3,000 |
Dominios por lista de dominios | 30,000 |
Segmentos dirigidos por perfil | 400 |
Grupos de segmentos dirigidos por perfil | 400 |
Categorías de contenido destinadas por perfil | 300 |
Categorías de contenido de plataforma destinadas por perfil | 300 |
Códigos postales dirigidos por perfil | 4000 |
Orígenes de inventario destinados por perfil | En desuso |
Publicadores destinados por perfil | 300 |
Ubicación Grupos dirigida por perfil | 100 |
Ubicaciones destinadas por perfil | 250 |
Ofertas dirigidas por miembro (nota: solo las ofertas con perfiles se cuentan con este límite) | 1000 |
Perfiles dirigidos por miembro | 100 |
Le enviaremos una notificación por correo electrónico cuando alcance el 85 % y el 95 % de su límite para un objeto y otro correo electrónico cuando alcance el 100 % de su límite.
Los correos electrónicos de notificación de límite de objetos se envían a las direcciones de correo electrónico especificadas en el sherlock_notify_email
campo del servicio miembro. Puede cambiar los destinatarios en cualquier momento. Tenga en cuenta, sin embargo, que este campo controla también los destinatarios de los correos electrónicos de auditoría creativos.
Cuando se aproxima o alcanza el límite de campañas, elementos de línea, ubicaciones, sitios o publicadores, debe eliminar cualquier instancia inactiva, no utilizada o innecesaria para que pueda permanecer por debajo del límite. Los elementos de línea eliminados, las campañas, los creativos, los editores, los sitios y las ubicaciones seguirán apareciendo en los informes, pero no se pueden recuperar.
Cuando se acerca o alcanza el límite para las creatividades, debe quitar las creatividades no expiradas. Las creatividades no expiradas tienen el is_expired
campo establecido en false
. Tenga en cuenta que la eliminación de las creatividades expiradas no afectará al recuento de creatividades.
Si necesita crear objetos adicionales, pero ya ha cumplido o superado el límite como se ha indicado anteriormente, elimine objetos no utilizados o póngase en contacto con el soporte técnico para obtener ayuda. Nuestro equipo de soporte técnico puede ayudarle a identificar los objetos inactivos que se van a eliminar.
En casos excepcionales, un límite puede ser elevado temporalmente por una pequeña cantidad a discreción de nuestro equipo de ingeniería. Póngase en contacto con su representante de Xandr para analizar esta opción.