此页面由 Cloud Translation API 翻译。

了解 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_bucket_name 中指定的输入存储分区中提取 `input_data_blob_prefix` 中指定的所有可汇总的 avro 报告。字符数：`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 互斥。这是收到报告的报告网址或报告来源。来源将是汇总服务初始配置中注册的网站的一部分。
`job_parameters.reporting_site`	字符串	与 `attribution_report_to` 相互排斥。这是收到报告的报告网址或报告来源的主机名。来源将是汇总服务初始配置中注册的网站的一部分。注意：您可以在同一请求中提交包含多个报告来源的报告，前提是所有报告来源都属于此参数中提及的同一报告网站。
`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”。)详细了解如何过滤 ID。
`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` 相互排斥。这是收到报告的报告网址或报告来源。来源将是汇总服务初始配置中注册的网站的一部分。这在 `createJob` 请求中指定。
`job_parameters.reporting_site`	字符串	与 `attribution_report_to` 相互排斥。这是收到报告的报告网址或报告来源的主机名。来源将是汇总服务初始配置中注册的网站的一部分。请注意，您可以在同一请求中提交包含多个报告来源的报告，前提是所有报告来源都属于此参数中提及的同一报告网站。这在 `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”。)详细了解如何过滤 ID。