Información sobre la API de Aggregation Service

Después de la implementación, el servicio de agregación expondrá dos extremos para el uso de la tecnología publicitaria: createJob y getJob.

Diagrama de AgS

Puedes obtener más información sobre los extremos createJob y getJob en la documentación de la API de Aggregation Service.

createJob

Se llama al extremo createJob a través de una solicitud HTTP POST y requiere un cuerpo de solicitud. Una vez que se realice la solicitud createJob, recibirás una respuesta HTTP 202 correcta.

  POST https://<api-gateway>/stage/v1alpha/createJob

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

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 comprender el modo de depuración, consulta la documentación de la ejecución de depuración de la 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 tomará todos los informes 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 de acceso en el bucket. Para archivos individuales, puedes usar la ruta de acceso. Si hay varios archivos, puedes usar el prefijo en la ruta de acceso.
Ejemplo: folder/file recopilará 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 es sobre 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 enviará el output_data. Esto es sobre el almacenamiento en la nube de la tecnología publicitaria.
job_parameters Diccionario Campo obligatorio. Esto contendrá los diferentes campos, como los siguientes:
  • output_domain_blob_prefix
  • output_domain_bucket_name
  • attribution_report_to
  • reporting_site
  • debug_privacy_epsilon
  • report_error_threshold_percentage
job_parameters.output_domain_blob_prefix String Al igual que input_data_blob_prefix, esta será la ruta de acceso en output_domain_bucket_name en la que se ubicará tu dominio de salida AVRO. Si hay 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 del dominio de salida. Esto se encuentra en el almacenamiento en la nube de la tecnología publicitaria.
job_parameters.attribution_report_to String Mutuamente excluyente de reporting_site. Esta será la URL o el origen de los informes en los que se recibió la denuncia. El origen será parte del sitio que se registró en la integración del servicio de agregación.
job_parameters.reporting_site String Es mutuamente excluyente con attribution_report_to. Este será el nombre de host de la URL o el origen de los informes en el que se recibió la denuncia. El origen será parte del sitio que se registró en la integración del servicio de agregación. Nota: 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 de informes que se menciona en este parámetro.
job_parameters.debug_privacy_epsilon Punto flotante, doble Campo opcional. Si no se pasa ninguno, el valor predeterminado es 10. Se puede usar un valor de 0 a 64. El valor puede variar.
job_parameters.report_error_threshold_percentage Doble Campo opcional. Este es el umbral del porcentaje de informes que pueden fallar antes de que el trabajo comience a fallar. 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 este trabajo. Este valor, junto con report_error_threshold_percentage, habilitará la falla anticipada del trabajo cuando se excluyan los informes debido a errores.
job_parameters.filtering_ids String Campo opcional. Una lista de IDs de filtros sin firma separados por comas. Se filtrarán 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 ejecutas una ejecución de depuración, se agregan informes y anotaciones de resumen de depuración con ruido y sin ruido para indicar qué claves están presentes en la entrada o los informes del dominio. Además, los duplicados en lotes tampoco se aplican. Ten en cuenta que la ejecución de depuración solo considera los informes que tienen la marca "debug_mode": "enabled" y las ejecuciones de depuración consumen el presupuesto.

getJob

Cuando la tecnología publicitaria quiere conocer el estado de un lote solicitado, puede llamar al extremo getJob. Se puede llamar al extremo getJob con una llamada GET HTTPS junto con el parámetro job_request_id en la solicitud.

  GET https://<api-gateway>/stage/v1alpha/getJob?job_request_id=<job_request_id>

Deberías obtener una respuesta como esta. Se mostrará el estado del trabajo y los mensajes 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 único de trabajo o lote 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 a 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 almacenarán los informes de resumen una vez generados. Este campo está configurado en createJob.
request_processing_started_at String La hora en la que comenzó el último intento de procesamiento. Esto excluirá 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 createJob y toda la información disponible en el trabajo. Se mostrarán return_code, return_message, finished_at y error_summary.
result_info.return_code String El código que se muestra del resultado del trabajo. Esta información será necesaria cuando se produzca un problema en el servicio de agregación para comprender cuál podría ser el problema.
result_info.return_message String Es el mensaje (éxito o error) que se muestra como resultado de la tarea. Esta información también se necesitará durante la investigación de fallas del servicio de agregación.
result_info.error_summary Diccionario Los errores que se muestran para el trabajo. Aquí se indicará la cantidad de informes que fallaron y cuál es el tipo de error.
result_info.finished_at Marca de tiempo Es la marca de tiempo del momento en que finalizó el trabajo.
result_info.error_summary.error_counts Lista Se mostrará una lista de los mensajes de error y la cantidad de informes que fallaron con el mismo mensaje de error. Cada recuento de errores contendrá la categoría, error_count, description.
result_info.error_summary.error_messages Lista Se mostrará 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 Este campo y reporting_site son mutuamente excluyentes. Esta será la URL o el origen del informe en el que se recibió el informe. El origen será 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. Este será el nombre de host de la URL o el origen de los informes en el que se recibió la denuncia. El origen será parte del sitio que se registró en la integración del servicio de agregación. Tenga en cuenta que puede enviar informes con varios orígenes en la misma solicitud, siempre y cuando todos estos orígenes pertenezcan al mismo sitio de informes 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 agregados a ese bucket de datos de entrada con orígenes en los informes que coincidan con el sitio de informes especificado en el parámetro de trabajo. Por ejemplo, si una tecnología publicitaria registró un origen de informes https://exampleabc.com, pero dentro del bucket de datos de entrada, agrega informes de https://1.exampleabc.com, https://2.exampleabc.com y https://3.examplexyz.com. Solo se agregarán los informes que se hayan agregado en el bucket que coincida con el origen de informes registrado en la tarea, que sería https://exampleabc.com.
job_parameters.debug_privacy_epsilon Punto flotante, doble Campo opcional. Si no se pasa ninguno, el valor predeterminado es 10. Se puede usar un valor de 0 a 64. El valor puede variar. Esto se especifica en la solicitud createJob.
job_parameters.report_error_threshold_percentage Doble Campo opcional. Este es el umbral del porcentaje de informes que pueden fallar antes de que la tarea comience a fallar. Si se deja vacío, el valor predeterminado es 10%. Esto se especifica en la solicitud createJob.
job_parameters.input_report_count Valor largo Campo opcional. Cantidad total de informes proporcionados como datos de entrada para este trabajo. Este valor, junto con report_error_threshold_percentage, habilitará la falla anticipada del trabajo cuando se excluyan los informes debido a errores. Esto 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 filtrarán 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").