了解 Aggregation Service API

部署后，汇总服务将公开两个端点供广告技术平台使用：createJob 和 getJob。

AgS 图

如需详细了解 createJob 和 getJob 端点，请参阅 Aggregation Service API 文档。

createJob

createJob 端点通过 HTTP POST 请求调用，并且需要请求正文。发出 createJob 请求后，您将收到 HTTP 202 成功响应。

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

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

请注意，reporting_site 和 attribution_report_to 互斥，只需使用其中一个即可。

您还可以通过将 debug_run 添加到 job_parameters 中来请求调试作业。如需了解调试模式，请参阅我们的汇总调试运行文档。

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

请求字段

参数 类型 说明
job_request_id 字符串 这是广告技术平台生成的唯一标识符，应采用 ASCII 字母，且不得超过 128 个字符。此属性用于标识批量作业请求，并将“input_data_blob_prefix”中指定的所有可汇总 avro 报告从 input_data_bucket_name 中指定的输入存储分区（托管在广告技术平台的云端存储空间）中获取。
字符数：`a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
input_data_blob_prefix 字符串 这是存储桶中的路径。对于单个文件，您可以使用路径。对于多个文件，您可以在路径中使用该前缀。
示例：folder/file 将收集来自 folder/file1.avro、folder/file/file1.avro、folder/file1/test/file2.avro 的所有报告。
input_data_bucket_name 字符串 这是用于存储输入数据或可汇总报告的存储分区。它位于广告技术平台的云端存储空间中。
output_data_blob_prefix 字符串 这是存储桶中的输出路径。支持单个输出文件。
output_data_bucket_name 字符串 这是将发送 output_data 的存储桶。此数据位于广告技术平台的云端存储空间中。
job_parameters 字典 必填字段。其中包含不同的字段，例如：
  • 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 字符串 与 input_data_blob_prefix 类似，这将是 output_domain_bucket_name 中输出领域 AVRO 所在的路径。对于多个文件，您可以在路径中使用该前缀。汇总服务完成批处理后，系统会创建摘要报告并将其放入名称为 output_data_blob_prefix 的输出存储桶 output_data_bucket_name 中。
job_parameters.output_domain_bucket_name 字符串 这是输出网域 AVRO 文件的存储桶。此数据位于广告技术平台的云端存储空间中。
job_parameters.attribution_report_to 字符串 与 reporting_site 互斥。这将是收到举报的举报网址或举报来源。该来源将成为在 Aggregation Service Onboarding 中注册的网站的一部分。
job_parameters.reporting_site 字符串 与 attribution_report_to 相互排斥。这是收到报告的报告网址或报告来源的主机名。该来源将成为在 Aggregation Service Onboarding 中注册的网站的一部分。 注意：只要所有举报来源都属于本参数中提及的同一个举报网站，您就可以在同一个请求中提交包含多个举报来源的报告。
job_parameters.debug_privacy_epsilon 浮点数，双精度 可选字段。如果未通过，默认值为 10。可以使用 0-64 之间的值。此值可以变化。
job_parameters.report_error_threshold_percentage 双精度 可选字段。这是在作业开始失败之前可以失败的报告所占百分比的阈值。如果留空，则默认为 10%。
job_parameters.input_report_count 长值 选填字段。作为此作业的输入数据提供的报告总数。当报告因错误而被排除时，此值与 report_error_threshold_percentage 结合使用可实现作业的提前失败。
job_parameters.filtering_ids 字符串 可选字段。以英文逗号分隔的未签名过滤 ID 列表。除匹配的过滤 ID 之外，所有其他贡献都会被滤除。 例如 "filtering_ids": "12345,34455,12"。默认值为“0”。
job_parameters.debug_run 布尔值 可选字段。执行调试运行时，系统会添加含噪声和未经过噪声的调试摘要报告和注解，以指明网域输入和/或报告中存在哪些键。此外，系统也不会强制执行批处理中的重复项。请注意，调试运行只会考虑带有 "debug_mode": "enabled" 标志的报告，而调试运行会消耗预算。

getJob

当广告技术平台想要了解所请求批次的状态时，可以调用 getJob 端点。可以使用 HTTPS GET 调用和请求中的 job_request_id 参数来调用 getJob 端点。

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

您应该会收到如下所示的响应。系统会返回作业的状态和错误消息。

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

响应字段

参数 类型 说明
job_request_id 字符串 这是 createJob 请求中指定的唯一作业 / 批次 ID。
job_status 字符串 这是作业请求的状态。
request_received_at 字符串 收到请求的时间。
request_updated_at 字符串 作业上次更新的时间。
input_data_blob_prefix 字符串 这是在 createJob 中设置的输入数据前缀。
input_data_bucket_name 字符串 这是广告技术平台的输入数据存储分区，可汇总报告会存储在其中。此字段设置为 createJob。
output_data_blob_prefix 字符串 这是在 createJob 中设置的输出数据前缀。
output_data_bucket_name 字符串 这是广告技术平台的输出数据存储分区，摘要报告生成后将存储在这里。此字段设置为 createJob。
request_processing_started_at 字符串 最新一次处理尝试的开始时间。这会排除在作业队列中等待的时间。 （总处理时间 = request_updated_at - request_processing_started_at）
result_info 字典 这是 createJob 的结果以及作业中的所有可用信息。 这会显示 return_code、return_message、finished_at 和 error_summary。
result_info.return_code 字符串 作业结果的返回代码。当汇总服务发生问题时，我们需要这些信息来了解可能存在的问题。
result_info.return_message 字符串 作为作业返回的消息（成功或失败）。在调查汇总服务故障时，我们也需要这些信息。
result_info.error_summary 字典 为作业返回的错误。其中将包含有多少报告因错误类型而失败。
result_info.finished_at 时间戳 作业完成的时间戳。
result_info.error_summary.error_counts 列表 这将返回错误消息列表以及出现相同错误消息的失败报告数量。每个错误计数将包含类别 error_count、description。
result_info.error_summary.error_messages 列表 这样会返回无法处理的报告的错误消息列表。
job_parameters 字典 它包含 createJob 请求中提供的作业参数。相关属性，例如 `output_domain_blob_prefix` 和 `output_domain_bucket_name`。
job_parameters.attribution_report_to 字符串 与 reporting_site 相互排斥。这是收到报告的报告网址或报告来源。该来源将成为在 Aggregation Service Onboarding 中注册的网站的一部分。这是在 createJob 请求中指定的。
job_parameters.reporting_site 字符串 与 attribution_report_to 相互排斥。这是收到报告的报告网址或报告来源的主机名。该来源将成为在 Aggregation Service Onboarding 中注册的网站的一部分。请注意，只要所有报告来源都属于本参数中提到的同一举报网站，您就可以在同一请求中提交包含多个报告来源的报告。这在 createJob 请求中指定。此外，请确保存储分区仅包含您要在创建作业时汇总的报告。系统会处理添加到该输入数据存储桶中的所有报告，前提是报告来源与作业参数中指定的报告网站相匹配。 例如，如果广告技术平台注册了报告来源 https://exampleabc.com，但在输入数据存储桶中添加了来自 https://1.exampleabc.com、https://2.exampleabc.com 和 https://3.examplexyz.com 的报告。只有已添加到存储分区且与作业中已注册的报告来源相匹配的报告才会被汇总，即 https://exampleabc.com。
job_parameters.debug_privacy_epsilon 浮点数，双精度 可选字段。如果未传递任何参数，则默认为 10。可以使用 0-64 之间的值。此值可以是不同的。这在 createJob 请求中指定。
job_parameters.report_error_threshold_percentage 双精度 选填字段。这是指在作业开始失败之前，可以失败的报告百分比的阈值。如果留空，则默认为 10%。这在 createJob 请求中指定。
job_parameters.input_report_count 长值 选填字段。作为此作业的输入数据提供的报告总数。将此值与 report_error_threshold_percentage 结合使用，可在报告因错误而被排除时让作业提前失败。这在 createJob 请求中指定。
job_parameters.filtering_ids 字符串 可选字段。以英文逗号分隔的无符号过滤 ID 列表。除匹配的过滤 ID 之外的所有内容都将被过滤掉。这在 createJob 请求中指定。 （例如 "filtering_ids":"12345,34455,12"。默认值为“0”。）