Licitadores: API de servicio de segmento de Batch

Artículo
05/18/2024

Batch Segment Service permite cargar audiencias en la plataforma Xandr a través de un marco de carga masiva o por lotes. Estos datos se pueden usar junto con los datos de compradores o vendedores con el fin de dirigirse a campañas o administrar el rendimiento. Todos los datos enviados a través del servicio de segmento de Batch se anexan a los datos de segmento existentes que ya están en nuestro sistema.

Entre las características se incluyen:

Capacidad de cargar archivos comprimidos
Comprobación de errores de datos de segmento
Formato de archivo de entrada configurable
Confirmación de la carga correcta
Comentarios sobre el estado general del procesamiento
Asociación de segmentos a usuarios independientemente de la ubicación de los usuarios
Un volumen de datos máximo alto

Para obtener resultados óptimos, se recomienda encarecidamente implementar los procedimientos recomendados que se encuentran en Procedimientos recomendados del servicio de segmento de Batch.

Nota:

El servicio batch segment requiere la configuración antes de su uso. Consulte Configuración inicial de la cuenta de BSS para obtener información sobre cómo configurarla para su asiento.

Importante

Gzip es el único método de compresión de archivos compatible con este servicio.

Adición de un archivo de segmento para su procesamiento

Agregar el archivo de segmento al sistema es un proceso de tres pasos. En primer lugar, solicite un número de identificación de trabajo y una dirección URL de carga. En segundo lugar, cargue el archivo en la dirección URL de carga asignada. En tercer lugar, compruebe el estado de procesamiento del trabajo. Tenga en cuenta que, por ahora, los archivos están limitados a como máximo 1800 segmentos en cualquier línea individual. Si tiene más de 1800 segmentos para un usuario, debe dividir esa línea en varias líneas.

Paso 1. Solicitud de una dirección URL de carga y un identificador de trabajo
Paso 2. Publicar el archivo en la dirección URL de carga
Paso 3. Comprobación del estado del trabajo

Paso 1. Solicitud de una dirección URL de carga y un identificador de trabajo

Cada archivo de datos de segmento que se cargue debe estar asociado a un identificador de trabajo determinado. Este identificador se usa para crear la dirección URL de carga y realizar un seguimiento del estado de procesamiento del archivo. El primer paso es enviar una solicitud vacía POST al servicio.

Nota:

Este servicio funciona tanto para como api.appnexus.com para api.adnxs.com : está disponible tanto para los inicios de sesión del licitador como para los inicios de sesión de la consola.

$ curl -b cookies -X POST "https://api.appnexus.com/batch-segment?member_id=456"
{
 "response": {
  "id": 123,
  "status": "OK",
  "batch_segment_upload_job": {
   "job_id": "JFY8l6iMOFAFJIWCMPcy39MCt3Yleo1337618549",
   "id": 123,
   "member_id": 456,
   "last_modified": "2012-05-21 16:42:29",
   "upload_url": "https://01.data-api.prod.adnxs.net/segment-upload/JFY8l6iMOFAFJIWCMPcy39MCt3Yleo1337618549"
  },
  "start_element": 0,
  "count": 1,
  "num_elements": 100,
  "dbg_info": {
  ...
  }
 }
}

Paso 2. Publicar el archivo en la dirección URL de carga

La dirección URL de carga de archivos se indica en la respuesta JSON al paso 1 por el campo upload_url. Debe enviar POST el archivo de segmento a esta dirección URL para su procesamiento. Recibirá un objeto JSON que le indicará si la carga se realizó correctamente. No codifique de forma rígida la dirección URL de carga en la aplicación; asegúrese de tomarla dinámicamente del upload_url campo.

Nota:

Debe comenzar la carga en la dirección URL de carga determinada en un plazo de cinco (5) minutos y solo una dirección URL es válida en un momento dado. Si espera más de 5 minutos para iniciar la carga, debe solicitar una nueva dirección URL.
Se recomienda no superar una carga por minuto. Si tiene más de 200 trabajos a la espera de procesarse en un momento dado, se le prohibirá cargar trabajos adicionales.
El archivo de segmento no debe ser mayor que 0,5 GB.

Advertencia

Para que el archivo se cargue correctamente, debe especificar el tipo MIME en el encabezado HTTP como "Content-Type: application/octet-stream". No use "Content-Type: application/x-www-form-urlencode" (-d o --data flags in curl). El uso de un tipo MIME incorrecto impedirá que el servicio de segmento de lote de API procese el archivo.

El archivo debe ajustarse al conjunto de caracteres Latin1.

$ curl -v -H 'Content-Type:application/octet-stream' -b cookies -X POST --data-binary @segment_file "https://01.data-api.prod.adnxs.net/segment-upload/JFY8l6iMOFAFJIWCMPcy39MCt3Yleo1337618549"
* About to connect() to 01.data-api.prod.adnxs.net port 80
*   Trying 64.210.62.71... connected
* Connected to 01.data-api.prod.adnxs.net (64.210.62.71) port 80
> POST /segment-upload/FkmOY7oL2Qy2aCE7NrhE1BHVoJA0wi1337697712 HTTP/1.1
> User-Agent: curl/7.15.5 (x86_64-redhat-linux-gnu) libcurl/7.15.5 OpenSSL/0.9.8b zlib/1.2.3 libidn/0.6.5
> Host: 01.data-api.prod.adnxs.net
> Accept: */*
> Content-type:application/octet-stream
> Content-Length: 116
>
> 7652266028043224430;5848:0,5849:1440,5850:14404013681496264948522;5013:0,5014:15508802117132500293405;5851:0,5847:-1HTTP/1.1 200 OK
< Date: Tue, 22 May 2012 14:48:02 GMT
< Content-Type: application/json
< Transfer-Encoding: chunked
< Server: Jetty(7.6.2.v20120308)
* Connection #0 to host 01.data-api.prod.adnxs.net left intact
* Closing connection #0
{"response":{"segment_upload":{"job_id":"FkmOY7oL2Qy2aCE7NrhE1BHVoJA0wi1337697712"},"status":"OK"}}

Ejemplo de dirección URL de carga SSL

curl -b cookie -c cookie -X POST -s -d '' "https://api.appnexus.com/batch-segment?member_id=958"
"batch_segment_upload_job": {
      "id": 14841671,
      "job_id": "qGQhSZ1qvd2hSsJ9svTz32qgxq7z5b1439315424",
      "member_id": 958,
      "last_modified": "2015-08-11 17:50:24",
      "upload_url": "https://data-api-gslb.adnxs.net/segment-upload/qGQhSZ1qvd2hSsJ9svTz32qgxq7z5b1439315424"
    }

Paso 3. Comprobación del estado del trabajo

Por último, compruebe el estado de procesamiento mediante el envío de una GET solicitud. La respuesta JSON contiene información como cuánto tiempo tardó el archivo en procesarse y el número de errores, si los hubiera. Tenga en cuenta que debe esperar hasta "phase": "completed" antes de examinar los campos de resultados, como num_valid. Para obtener información más detallada, consulte Campos JSON a continuación.

Nota:

Por acuerdo de nivel de servicio de Xandr, espere hasta 24 horas para que el archivo se procese.

Advertencia

Si es un proveedor de datos que usa impbus API, tenga en cuenta que el batch_segment_upload_job campo será una matriz con un único objeto dentro de ella, por ejemplo:

{"batch_segment_upload_job":[{"phase": "completed"}]}

$ curl -b cookies "https://api.appnexus.com/batch-segment?member_id=456&job_id=JFY8l6iMOFAFJIWCMPcy39MCt3Yleo1337618549"
{
 "response": {
  "start_element": 0,
  "count": 1,
  "batch_segment_upload_job": {
   "phase": "completed",
   "start_time": "2012-05-21 20:04:35",
   "uploaded_time": "2012-05-21 20:04:41",
   "validated_time": "2012-05-21 20:07:24",
   "completed_time": "2012-05-21 20:08:24",
   "error_code": null,
   "time_to_process": "2.69",
   "percent_complete": 100,
   "num_valid": 200000,
   "num_valid_user":100000
   "num_invalid_format": 0,
   "num_invalid_user": 0,
   "num_invalid_segment": 0,
   "num_unauth_segment": 1,
   "num_past_expiration": 0,
   "num_inactive_segment": 0,
   "num_other_error": 0,
   "error_log_lines": " \n\nnum_unauth_segment-4013681496264948522;5013:0,5014:1550",
   "segment_log_lines": "\n5010:100000\n5011:50000\n5012:50000",
   "id": 88,
   "job_id": "4tGhzv2PojNGQpq0MYaoaOa70cuF061337630675",
   "member_id": 456,
   "created_on": "2012-05-21 20:04:35",
   "last_modified": "2012-05-21 20:08:24"
  },
  "dbg_info": {
  ...
  },
  "status": "OK",
  "num_elements": 100
 }
}

Posibles errores de carga

Intento de cargar un archivo de más de 0,5 GB

{"response":{"status":"ERROR","error_code":"FILESIZE_LIMIT_EXCEEDED","errors":["Member
exceeds maximum byte size allowed for a file"]}}

Código de error en el trabajo de carga de segmentos por lotes

""batch_segment_upload_job": {
      "phase": "error",
      "start_time": "2015-08-13 18:40:32",
      "uploaded_time": null,
      "validated_time": null,
      "completed_time": null,
      "error_code": "uploading-error",
      "time_to_process": "0.00",
      "percent_complete": 0,
      "num_valid": 0,
      "num_invalid_format": 0,
      "num_valid_user": 0,
      "num_invalid_user": 0,
      "num_invalid_segment": 0,
      "num_invalid_timestamp": 0,
      "num_unauth_segment": 0,
      "num_past_expiration": 0,
      "num_inactive_segment": 0,
      "num_other_error": 0,
      "error_log_lines": null,
      "segment_log_lines": null,
      "id": 11661553,
      "job_id": "Pm3oCUf5CSVKIOt4mAqOzdt6K3qInj1431542432",
      "member_id": 958,
      "created_on": "2015-05-13 18:40:32",
      "last_modified": "2015-05-13 18:40:33"
    }

A continuación se muestran los errores que pueden producirse cuando:

Ha cancelado la carga.
La fase de carga supera los 90 minutos
Ha alcanzado uno de sus cuatro límites de carga (bytes diarios, bytes por hora o límite de líneas por hora)

Intento de superar el límite de carga de bytes diario

{"response":{"status":"ERROR","error_code":"RATE_LIMIT_EXCEEDED","errors":["Member
exceeds maximum allowed bytes per day"]}}

Intento de superar el límite de carga de bytes por hora

{"response":{"status":"ERROR","error_code":"RATE_LIMIT_EXCEEDED","errors":["Member
exceeds maximum allowed bytes per hour"]}}

Intento de superar el límite de carga de líneas diarias

{"response":{"status":"ERROR","error_code":"RATE_LIMIT_EXCEEDED","errors":["Member
exceeds maximum allowed number of lines per day"]}}

Intento de superar el límite de carga de líneas por hora

{"response":{"status":"ERROR","error_code":"RATE_LIMIT_EXCEEDED","errors":["Member
exceeds maximum allowed lines per hour"]}}

Superación del tiempo máximo para cargar

{"response":{"status":"ERROR","error_code":"RATE_LIMIT_EXCEEDED","errors":["Maximum
upload time exceeded"]}}

Posibles errores de procesamiento

Formato no válido

Si el valor del num_invalid_format campo es mayor que "0", compruebe los valores del campo (consulte el error_log_linesejemplo siguiente). Tenga en cuenta lo siguiente en el error_log_lines campo:

num_invalid_format indica que hubo un problema al analizar una línea en el archivo cargado.
"failed with an illegal number of fields" indica que el número de campos de un segment_fields bloque no coincidía con lo que se definió en la configuración del segmento por lotes (consulte Configuración inicial de la cuenta de BSS para obtener más información). En el ejemplo siguiente, la configuración indica tres campos: SEG_ID, VALUE, , EXPIRATION, pero el analizador solo encontró dos campos: SEG_ID, VALUE
```
segment_fields: [SEG_ID,VALUE,EXPIRATION]
```

`num_invalid_format` y `error_log_lines` ejemplo

"batch_segment_upload_job": {
phase": "completed",
"error_code": null,
"time_to_process": "0.01",
"percent_complete": 100,
"num_valid": 0,
"num_invalid_format": 1,
"num_valid_user": 0,
"num_invalid_user": 0,
"num_invalid_segment": 0,
"num_invalid_timestamp": 0,
"num_unauth_segment": 0,
"num_past_expiration": 0,
"num_inactive_segment": 0,
"num_other_error": 0,
"error_log_lines": "num_invalid_format-WINDOWSADID-USER-ID;SEG_ID:VALUE~9 failed with an illegal number of fields",
"segment_log_lines": null,
"start_time": "2015-08-13 18:40:32",
"uploaded_time": "2015-08-13 18:42:32",
"validated_time": "2015-08-13 18:42:32",
"completed_time": "2015-08-13 18:42:33",
"id": 123412341234,
"job_id": "Pm3oCUf5CSVKIOt4mAqOzdt6K3qInj1431542432",
"member_id": 958,
"created_on": "2015-08-13 18:40:32",
"last_modified": "2015-08-13 18:42:33"
}

Ver el historial de carga de archivos

Para ver los metadatos sobre todas las cargas de archivos de segmento en los últimos 30 días, realice una GET llamada al servicio con member_id el especificado en la cadena de consulta. La respuesta JSON incluirá una matriz de batch_segment_upload_job objetos. Para obtener más información sobre los campos específicos del batch_segment_upload_job objeto, consulte Campos JSON.

Nota:

El historial de carga de archivos solo está disponible durante los últimos 30 días.

$ curl -b cookies 'https://api.appnexus.com/batch-segment?member_id=456'
{
   "response" : {
      "batch_segment_upload_job" : [
         {
           "phase": "completed",
            "start_time": "2012-05-22 16:48:55",
            "uploaded_time": "2012-05-22 16:48:56",
            "validated_time": "2012-05-22 16:49:01",
            "completed_time": "2012-05-22 16:49:01",
            "error_code": null,
            "time_to_process": "0.04",
            "percent_complete": 100,
            "num_valid": 0,
            "num_invalid_format": 0,
            "num_invalid_user": 2,
            "num_invalid_segment": 0,
            "num_unauth_segment": 1,
            "num_past_expiration": 0,
            "num_inactive_segment": 0,
            "num_other_error": 0,
            "error_log_lines": " \n\nnum_unauth_segment-4013681496264948522;5013:0,5014:1550\nnum_invalid_user-7652266028043224430;5848:0,5849:1440,5850:1440\nnum_invalid_user-8802117132500293405;5851:0,5847:-1",
            "id": 98,
            "job_id": "T1v98eIOlCZndeLGSXD0nrs57L8ES11337705335",
            "member_id": 456,
            "created_on": "2012-05-22 16:48:55",
            "last_modified": "2012-05-22 16:49:01"
         },
         ...
    }
  }
}

Nota:

Nuestra API limita las respuestas a 100 objetos a través de la paginación. Para ver objetos adicionales, anexe uno de estos objetos a la llamada API:

&start_element=101

&sort=last_modified.desc

Puede obtener más información sobre la paginación en Limitación, Paginación y Filtrado.

Campos JSON

Sugerencia

Para averiguar por qué campos puede filtrar y ordenar, realice una llamada GET a https://api.appnexus.com/batch-segment/meta.

Fields	Tipo	Descripción
`batch_segment_upload_job`	object	Objeto cuyos campos contienen metadatos que describen el trabajo de carga y procesamiento. Si usa la API impbus, se trata de una matriz que contiene un solo objeto. Consulte Trabajo de carga de segmentos por lotes a continuación para obtener más información.
`id`	Entero	Este es el identificador del `batch_segment_upload_job` objeto asociado a esta solicitud. Valor predeterminado: número generado automáticamente.
`status`	string	Estado de la llamada API; Las llamadas correctas devuelven `"OK"`.

Trabajo de carga de segmentos por lotes

Cuando se solicita el estado del trabajo de procesamiento, el sistema devuelve un batch_segment_upload_job objeto (si es un proveedor de datos, se trata de una matriz que contiene un solo objeto). En función de la solicitud que realice al servicio, contendrá algunos o todos los metadatos siguientes. Para obtener más información sobre la secuencia necesaria de solicitudes, vea Agregar un archivo de segmento para el procesamiento a continuación.

Nota:

La mayoría de los metadatos solo estarán presentes cuando "phase" = "completed."

Fields	Tipo	Descripción
`completed_time`	date	Hora a la que se completó el procesamiento de archivos.
`created_on`	date	Fecha de creación de este objeto.
`error_code`	Entero	Si `"phase" = "error"`es , este código de error describe el tipo de error encontrado. Tenga en cuenta que un código de error solo se mostrará aquí si se produjo un error con la carga, validación o procesamiento del propio archivo (es decir, no incluye el formato no válido o errores de segmento no válidos). Los errores comunes se deben a archivos ilegibles y superan los límites de objetos definidos. Devuelve `null` si no se encontró ningún error.
`error_log_lines`	string	Cadena que contiene líneas separadas por líneas nuevas. Cada línea muestra un error de validación o el motivo de un error al cargar el archivo. Puede elegir cuántas líneas (200 de forma predeterminada) aparecen en este campo.
`id`	Entero	Identificador único de este objeto.
`job_id`	string	Cadena de caracteres alfanuméricos que identifica de forma única el trabajo de procesamiento asociado a este archivo.
`last_modified`	date	La fecha de modificación más reciente de este objeto (normalmente a través de `POST`).
`member_id`	Entero	Su id. de miembro.
`num_inactive_segment`	Entero	Número de segmentos inactivos en el archivo. Desduplicado.
`num_invalid_format`	Entero	Número de líneas cargadas que contienen errores de formato (esto depende de la configuración de formato de archivo determinada). Las líneas duplicadas también se considerarán un formato no válido.
`num_invalid_segment`	Entero	Número de segmentos no válidos en el archivo. Desduplicado.
`num_invalid_timestamp`	Entero	Número de marcas de tiempo no válidas en el archivo.
`num_invalid_user`	Entero	Se trata de un recuento de líneas de entrada únicas que tienen un usuario no válido o inexistente
`num_other_error`	Entero	Se trata de un valor de marcador de posición que no está actualmente en uso.
`num_past_expiration`	Entero	Número de segmentos expirados en el archivo. Desduplicado.
`num_unauth_segment`	Entero	Número de segmentos en el archivo al que no está autorizado el acceso. Desduplicado.
`num_valid`	Entero	Número de líneas válidas en el archivo cargado. Cada combinación de usuario/segmento se considera 1 línea.
`num_valid_user`	Entero	Se trata de un recuento de líneas de entrada únicas que tienen un identificador de usuario válido.
`percent_complete`	Entero	Porcentaje del procesamiento que se ha completado, dado el actual `phase` en el momento de la solicitud.
`phase`	enumeración	Estado de procesamiento actual, uno de `"error"`, `"starting"`, `"uploading"`, `"validating"`, `"processing"`o `"completed"`.
`segment_log_lines`	string	Cadena que contiene líneas separadas por líneas nuevas. Cada línea muestra un segmento y cuántos usuarios se agregaron correctamente a él. Este campo tiene como valor predeterminado 200 líneas.
`start_time`	date	Hora a la que comenzó la carga de archivos.
`time_to_process`	decimal	Cuánto tiempo tardó en procesarse el archivo de segmento, en minutos.
`upload_url`	string	Dirección URL donde cargará el archivo de datos del segmento.
`uploaded_time`	date	Hora a la que se cargó el archivo asociado a este identificador de trabajo.
`validated_time`	date	Hora a la que se completó la validación de archivos.

Servicio de segmento de batch: script PHP de ejemplo

Compartir a través de

Licitadores: API de servicio de segmento de Batch

Adición de un archivo de segmento para su procesamiento

Paso 1. Solicitud de una dirección URL de carga y un identificador de trabajo

Paso 2. Publicar el archivo en la dirección URL de carga

Ejemplo de dirección URL de carga SSL

Paso 3. Comprobación del estado del trabajo

Posibles errores de carga

Intento de cargar un archivo de más de 0,5 GB

Código de error en el trabajo de carga de segmentos por lotes

Intento de superar el límite de carga de bytes diario

Intento de superar el límite de carga de bytes por hora

Intento de superar el límite de carga de líneas diarias

Intento de superar el límite de carga de líneas por hora

Superación del tiempo máximo para cargar

Posibles errores de procesamiento

Formato no válido

`num_invalid_format` y `error_log_lines` ejemplo

Ver el historial de carga de archivos

Campos JSON

Trabajo de carga de segmentos por lotes

Recursos adicionales

Compartir a través de

Licitadores: API de servicio de segmento de Batch

Adición de un archivo de segmento para su procesamiento

Paso 1. Solicitud de una dirección URL de carga y un identificador de trabajo

Paso 2. Publicar el archivo en la dirección URL de carga

Ejemplo de dirección URL de carga SSL

Paso 3. Comprobación del estado del trabajo

Posibles errores de carga

Intento de cargar un archivo de más de 0,5 GB

Código de error en el trabajo de carga de segmentos por lotes

Intento de superar el límite de carga de bytes diario

Intento de superar el límite de carga de bytes por hora

Intento de superar el límite de carga de líneas diarias

Intento de superar el límite de carga de líneas por hora

Superación del tiempo máximo para cargar

Posibles errores de procesamiento

Formato no válido

num_invalid_format y error_log_lines ejemplo

Ver el historial de carga de archivos

Campos JSON

Trabajo de carga de segmentos por lotes

Tema relacionado

Recursos adicionales

`num_invalid_format` y `error_log_lines` ejemplo