使用汇总服务部署和管理请求

成功部署汇总服务后，您可以使用 createJob 和 getJob 端点与该服务进行交互。下图直观呈现了这两个端点的部署架构：

Aggregation Service API 概览
图 1.Aggregation Service API 概览

如需详细了解 createJob 和 getJob 端点，请参阅汇总服务 API 文档。

创建作业

如需创建作业，请向 createJob 端点发送 POST 请求。bash 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>"
  }
}

成功创建作业会导致 HTTP 状态代码为 202。

请注意，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_bucket_name` 中指定的输入存储分区中提取 `input_data_blob_prefix` 中指定的所有可汇总的 AVRO 报告。
字符：`a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
input_data_blob_prefix 字符串 这是存储分区路径。对于单个文件，您可以使用路径。对于多个文件，您可以在路径中使用前缀。
示例：文件夹/文件会收集 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 初始配置中注册的。
job_parameters.reporting_site 字符串 与 attribution_report_to 相互排斥。这是收到报告的报告网址或报告来源的主机名。网站来源是在 Aggregation Service 初始配置中注册的。 注意：您可以在单个请求中提交多个具有不同来源的报告，前提是所有来源都属于此参数中指定的同一报告网站。
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" 标志的报告。从 v2.10.0 开始，调试运行不会消耗隐私预算。

获取作业

当广告技术平台想要了解所请求批次的状态时，可以调用 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 初始配置中注册的网站的一部分。这在 createJob 请求中指定。
job_parameters.reporting_site 字符串 与 attribution_report_to 相互排斥。这是报告网址的主机名，或收到报告的来源。来源是指在 Aggregation Service 初始配置中注册的网站的一部分。请注意，您可以在同一请求中提交包含多个报告来源的报告，前提是所有报告来源都属于此参数中提及的同一网站。这在 createJob 请求中指定。此外，请验证该存储分区是否仅包含您在创建作业时要汇总的报告。系统会处理添加到输入数据存储分区中的所有报告，前提是报告来源与作业参数中指定的报告网站相匹配。 Aggregation Service 仅会考虑与作业的已注册报告来源匹配的数据分桶中的报告。例如，如果注册的来源是 https://exampleabc.com，则仅包含来自 https://exampleabc.com 的报告，即使存储分区包含来自子网域 (https://1.exampleabc.com 等) 或完全不同网域 (https://3.examplexyz.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”。)