Después de implementar correctamente el servicio de agregación, puedes usar los extremos createJob
y getJob
para interactuar con el servicio. En el siguiente diagrama, se proporciona una representación visual de la arquitectura de implementación de estos dos extremos:

Puedes obtener más información sobre los extremos createJob
y getJob
en la documentación de la API de Aggregation Service.
Crea un trabajo
Para crear un trabajo, envía una solicitud POST al extremo createJob
.
bash
POST https://<api-gateway>/stage/v1alpha/createJob
-+
Un ejemplo del cuerpo de la solicitud para createJob
:
{
"job_request_id": "<job_request_id>",
"input_data_blob_prefix": "<report_folder>/<report_name>.avro",
"input_data_bucket_name": "<input_bucket_name>",
"output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
"output_data_bucket_name": "<output_bucket_name>",
"job_parameters": {
"output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
"output_domain_bucket_name": "<output_domain_bucket_name>",
"attribution_report_to": "<reporting origin of report>",
"reporting_site": "<host name of reporting origin>"
}
}
Si la creación de la tarea se realiza correctamente, se muestra un código de estado HTTP 202.
Ten en cuenta que reporting_site
y attribution_report_to
son excluyentes de forma mutua y solo se requiere uno.
También puedes solicitar un trabajo de depuración si agregas debug_run
a job_parameters
.
Para obtener más información sobre el modo de depuración, consulta nuestra documentación sobre la ejecución de depuración de agregación.
{
"job_request_id": "<job_request_id>",
"input_data_blob_prefix": "<report_folder>/<report_name>.avro",
"input_data_bucket_name": "<input_bucket_name>",
"output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
"output_data_bucket_name": "<output_bucket_name>",
"job_parameters": {
"output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
"output_domain_bucket_name": "<output_domain_bucket_name>",
"attribution_report_to": "<reporting origin of report>"
"debug_run": "true"
}
}
Campos de la solicitud
Parámetro | Tipo | Descripción |
---|---|---|
job_request_id |
String |
Es un identificador único generado por la tecnología publicitaria que debe tener letras ASCII con 128 caracteres o menos. Esto identifica la solicitud de trabajo por lotes y toma todos los informes de AVRO agregables especificados en "input_data_blob_prefix" del bucket de entrada especificado en "input_data_bucket_name" que se aloja en el almacenamiento en la nube de la tecnología publicitaria.
Caracteres: `a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
|
input_data_blob_prefix |
String |
Esta es la ruta del bucket. Para archivos individuales, puedes usar la ruta de acceso. Para varios archivos, puedes usar el prefijo en la ruta de acceso.
Ejemplo: La carpeta o el archivo recopilan todos los informes de folder/file1.avro, folder/file/file1.avro y folder/file1/test/file2.avro. |
input_data_bucket_name |
String | Este es el bucket de almacenamiento para los datos de entrada o los informes agregables. Esto se encuentra en el almacenamiento en la nube de la tecnología publicitaria. |
output_data_blob_prefix |
String | Esta es la ruta de acceso de salida en el bucket. Se admite un solo archivo de salida. |
output_data_bucket_name |
String |
Este es el bucket de almacenamiento al que se envía el output_data . Esto existe en el almacenamiento en la nube de la tecnología publicitaria.
|
job_parameters |
Diccionario |
Campo obligatorio. Este campo contiene los diferentes campos, como los siguientes:
|
job_parameters.output_domain_blob_prefix |
String |
Al igual que input_data_blob_prefix , esta es la ruta de acceso en output_domain_bucket_name donde se encuentra tu dominio de salida AVRO. Para varios archivos, puedes usar el prefijo en la ruta de acceso. Una vez que el servicio de agregación completa el lote, se crea el informe de resumen y se coloca en el bucket de salida output_data_bucket_name con el nombre output_data_blob_prefix .
|
job_parameters.output_domain_bucket_name |
String | Este es el bucket de almacenamiento para el archivo AVRO de tu dominio de salida. Esto se encuentra en el almacenamiento en la nube de la tecnología publicitaria. |
job_parameters.attribution_report_to |
String | Este valor es mutuamente exclusivo de "reporting_site", que es la URL o el origen del informe en el que se recibió el informe. El origen del sitio se registra en la integración del servicio de agregación. |
job_parameters.reporting_site |
String |
Es mutuamente excluyente con attribution_report_to . Es el nombre de host de la URL de informes o el origen de informes en el que se recibió el informe. El origen del sitio se registra en la integración del servicio de agregación.
Nota: Puedes enviar varios informes con orígenes diferentes en una sola solicitud, siempre y cuando todos los orígenes pertenezcan al mismo sitio de informes especificado en este parámetro.
|
job_parameters.debug_privacy_epsilon |
Número de punto flotante, doble | Campo opcional. Si no se pasa ningún valor, el valor predeterminado es 10. Se puede usar un valor de 0 a 64. |
job_parameters.report_error_threshold_percentage |
Doble | Campo opcional. Este es el porcentaje máximo de informes con errores permitidos antes de que falle la tarea. Si se deja en blanco, el valor predeterminado es 10%. |
job_parameters.input_report_count |
valor largo |
Campo opcional. Es la cantidad total de informes proporcionados como datos de entrada para la tarea. Este valor, junto con report_error_threshold_percentage , permite que el trabajo falle antes cuando se excluyen los informes debido a errores.
|
job_parameters.filtering_ids |
String |
Campo opcional. Es una lista de IDs de filtrado sin firmar separados por comas. Se filtran todas las contribuciones que no coincidan con el ID de filtrado. (p.ej.,"filtering_ids": "12345,34455,12" ). El valor predeterminado es 0.
|
job_parameters.debug_run |
Booleano |
Campo opcional. Cuando se ejecuta una ejecución de depuración, se agregan informes y anotaciones de resumen de depuración con y sin ruido para indicar qué claves están presentes en la entrada o los informes del dominio. Además, no se aplican los duplicados entre lotes. Ten en cuenta que la ejecución de depuración solo considera los informes que tienen la marca "debug_mode": "enabled" . A partir de la versión 2.10.0, las ejecuciones de depuración no consumen el presupuesto de privacidad.
|
Obtener un trabajo
Cuando una tecnología publicitaria quiere conocer el estado de un lote solicitado, puede llamar al extremo getJob
. Se llama al extremo getJob
con una solicitud GET HTTPS junto con el parámetro job_request_id
.
GET https://<api-gateway>/stage/v1alpha/getJob?job_request_id=<job_request_id>
Deberías obtener una respuesta que muestre el estado del trabajo junto con cualquier mensaje de error:
{
"job_status": "FINISHED",
"request_received_at": "2023-07-17T19:15:13.926530Z",
"request_updated_at": "2023-07-17T19:15:28.614942839Z",
"job_request_id": "PSD_0003",
"input_data_blob_prefix": "reports/output_reports_2023-07-17T19:11:27.315Z.avro",
"input_data_bucket_name": "ags-report-bucket",
"output_data_blob_prefix": "summary/summary.avro",
"output_data_bucket_name": "ags-report-bucket",
"postback_URL": "",
"result_info": {
"return_code": "SUCCESS",
"return_message": "Aggregation job successfully processed",
"error_summary": {
"error_counts": [],
"error_messages": []
},
"finished_at": "2023-07-17T19:15:28.607802354Z"
},
"job_parameters": {
"debug_run": "true",
"output_domain_bucket_name": "ags-report-bucket",
"output_domain_blob_prefix": "output_domain/output_domain.avro",
"attribution_report_to": "https://privacy-sandcastle-dev-dsp.web.app"
},
"request_processing_started_at": "2023-07-17T19:15:21.583759622Z"
}
Campos de respuesta
Parámetro | Tipo | Descripción |
---|---|---|
job_request_id |
String |
Este es el ID de trabajo o lote único que se especificó en la solicitud createJob .
|
job_status |
String | Este es el estado de la solicitud de trabajo. |
request_received_at |
String | Es la hora en que se recibió la solicitud. |
request_updated_at |
String | La hora en la que se actualizó el trabajo por última vez. |
input_data_blob_prefix |
String |
Este es el prefijo de datos de entrada que se configuró en createJob .
|
input_data_bucket_name |
String |
Este es el bucket de datos de entrada de la tecnología publicitaria en el que se almacenan los informes agregables. Este campo se establece en createJob .
|
output_data_blob_prefix |
String |
Este es el prefijo de datos de salida que se configuró en createJob .
|
output_data_bucket_name |
String |
Este es el bucket de datos de salida de la tecnología publicitaria en el que se almacenan los informes de resumen generados. Este campo se establece en createJob .
|
request_processing_started_at |
String |
La hora en la que comenzó el último intento de procesamiento. Esto excluye el tiempo de espera en la cola de trabajos.
(Tiempo de procesamiento total = request_updated_at - request_processing_started_at )
|
result_info |
Diccionario |
Este es el resultado de la solicitud createJob y consta de toda la información disponible.
Se muestran los valores return_code , return_message , finished_at y error_summary .
|
result_info.return_code |
String | Es el código de devolución del resultado del trabajo. Esta información es necesaria para solucionar problemas en el servicio de agregación. |
result_info.return_message |
String | El mensaje de éxito o error que se muestra como resultado de la tarea. Esta información también es necesaria para solucionar problemas del servicio de agregación. |
result_info.error_summary |
Diccionario | Los errores que muestra el trabajo Contiene la cantidad de informes junto con el tipo de errores que se encontraron. |
result_info.finished_at |
Marca de tiempo | Es la marca de tiempo que indica que se completó el trabajo. |
result_info.error_summary.error_counts |
Lista |
Se muestra una lista de los mensajes de error junto con la cantidad de informes que fallaron con el mismo mensaje de error. Cada recuento de errores contiene una categoría, error_count y description .
|
result_info.error_summary.error_messages |
Lista | Se muestra una lista de los mensajes de error de los informes que no se pudieron procesar. |
job_parameters |
Diccionario |
Contiene los parámetros de trabajo proporcionados en la solicitud createJob . Propiedades relevantes, como "output_domain_blob_prefix" y "output_domain_bucket_name"
|
job_parameters.attribution_report_to |
String |
Es mutuamente excluyente con reporting_site . Esta es la URL del informe o el origen desde el que se recibió. El origen forma parte del sitio que se registró en la integración del servicio de agregación. Esto se especifica en la solicitud createJob .
|
job_parameters.reporting_site |
String |
Es mutuamente excluyente con attribution_report_to . Es el nombre de host de la URL del informe o el origen desde el que se recibió el informe. El origen forma parte del sitio que se registró en la integración del servicio de agregación. Ten en cuenta que puedes enviar informes con varios orígenes de informes en la misma solicitud, siempre que todos los orígenes de informes pertenezcan al mismo sitio que se menciona en este parámetro. Esto se especifica en la solicitud createJob . Además, asegúrate de que el bucket solo contenga los informes que deseas agregar en el momento de crear la tarea. Se procesarán todos los informes que se agreguen al bucket de datos de entrada con orígenes de informes que coincidan con el sitio de informes especificado en el parámetro de trabajo.
El servicio de agregación solo considera los informes dentro del bucket de datos que coinciden con el origen de informes registrado del trabajo. Por ejemplo, si el origen registrado es https://exampleabc.com, solo se incluyen los informes de https://exampleabc.com, incluso si el bucket contiene informes de subdominios (https://1.exampleabc.com , etc.) o dominios completamente diferentes (https://3.examplexyz.com ).
|
job_parameters.debug_privacy_epsilon |
Número de punto flotante, doble |
Campo opcional. Si no se pasa ningún valor, se usa el valor predeterminado de 10. Los valores pueden ser de 0 a 64. Este valor se especifica en la solicitud createJob .
|
job_parameters.report_error_threshold_percentage |
Doble |
Campo opcional. Este es el porcentaje de umbral de informes que pueden fallar antes de que falle el trabajo. Si no se asigna ningún valor, se usa el valor predeterminado del 10%. Esto se especifica en la solicitud createJob .
|
job_parameters.input_report_count |
Valor largo | Campo opcional. Es la cantidad total de informes proporcionados como datos de entrada para este trabajo. El parámetro "report_error_threshold_percentage", combinado con este valor, activa la falla del trabajo antes de tiempo si se excluye una cantidad significativa de informes debido a errores. Este parámetro de configuración se especifica en la solicitud "createJob". |
job_parameters.filtering_ids |
String |
Campo opcional. Es una lista de IDs de filtrado sin firmar separados por comas. Se filtran todas las contribuciones que no coincidan con el ID de filtrado. Esto se especifica en la solicitud createJob .
(p.ej., "filtering_ids":"12345,34455,12" ). El valor predeterminado es “0”.)
|