诊断您的环境（新建或升级的环境）

在使用汇总服务时，多种因素可能会导致问题，包括报告格式、输出网域问题和协调器问题。了解错误来源及其包含的任何元数据对于准确诊断问题至关重要。

指南主题：

验证客户端 Measurement API 设置

验证源服务器已正确注册后，请完成以下步骤：

  1. 检查您触发报告的方式。确认您收到的报告格式是否正确，具体取决于所使用的 API：

    • Attribution Reporting API
    • Private Aggregation API
      • Private Aggregation API 中的报告可以使用 contributeToHistogram 函数完成。验证您是否传递了分桶键和值。存储分区键应采用 BigInt 格式。（如需了解详情，请参阅 Private Aggregation API）

  2. 如果您正按照建议触发报告，但仍遇到此问题，请检查 Chrome 开发者控制台的“控制台”和“网络”标签页中是否显示错误。

如果您需要针对这些客户端 API 获得进一步的问题排查支持，请继续参阅我们的 Attribution Reporting API 调试指南和 Private Aggregation API + Shared Storage。

排查报告来源设置问题

报告来源服务器是指您已声明正确对应的 .well-known 端点（可汇总报告将发送到这些端点）的服务器。验证已部署的报告源服务器是否已正确注册。

您的报告来源是否正在接收报告？

验证已部署的报告来源服务器是否已正确注册。此服务器是您声明了正确的相应 .well-known 端点的位置，可汇总的报告将发送到这些端点。

客户端 Measurement API 匹配的可汇总端点
归因报告 POST /.well-known/attribution-reporting/report-aggregate-attribution
Private Aggregation + Shared Storage（组合） POST /.well-known/private-aggregation/report-shared-storage
Private Aggregation + Protected Audience（组合） POST /.well-known/private-aggregation/report-protected-audience

验证源服务器已正确注册后，请完成以下步骤：

  1. 检查您触发报告的方式。确认您收到的报告格式是否正确，具体取决于所使用的 API：

  2. 如果您按照建议触发报告，但问题仍然存在，请检查 Chrome 开发者控制台的“控制台”和“网络”标签页中是否观察到错误。

如果您需要针对这些客户端 API 获得进一步的问题排查支持，请继续参阅 Attribution Reporting API 的调试指南和 Private Aggregation API + Shared Storage。

排查汇总报告方面的问题

汇总报告由客户端衡量 API 生成，并发送到您的报告来源。这些报告应由您的报告端点转换为 AVRO 格式。如果此转化存在问题，或者报告本身不完整，您可能会在汇总服务中看到错误。

您的可汇总报告是否正确转换？

验证您的报告端点 (.well-known/…) 是否能将给定的可汇总 JSON 报告正确转换为 AVRO。

此问题会导致以下 API 错误：

错误 DECRYPTION_ERROR
示例 
                "result_info": {
                    "return_code": "REPORTS_WITH_ERRORS_EXCEEDED_THRESHOLD",
                    "return_message": "Aggregation job failed early because the number of reports excluded from aggregation exceeded threshold.",
                    "error_summary": {
                        "error_counts": [
                            {
                                "category": "DECRYPTION_ERROR",
                                "count": 1,
                                "description": "Unable to decrypt the report. This may be caused by: tampered aggregatable report shared info, corrupt encrypted report, or other such issues."
                            },
                            {
                                "category": "NUM_REPORTS_WITH_ERRORS",
                                "count": 1,
                                "description": "Total number of reports that had an error. These reports were not considered in aggregation. See additional error messages for details on specific reasons."
                            }
                        ],
                        "error_messages": []
                    }
                }
检查 这可能是由于解密错误所致，而解密错误可能是由未正确生成的 AVRO 报告（无论是可汇总的 AVRO 报告还是输出网域 AVRO）引起的。可汇总的 AVRO 报告是否正确生成？有效负载需要进行 base64 解码并转换为字节数组。验证报告是否采用 avro 格式。此外，请检查输出网域 AVRO 是否正确。存储分区会转换为转义的 Unicode 十六进制格式，然后转换为字节数组。 如果您看到多个错误计数，可以在汇总服务 GitHub 页面中详细了解这些错误。
错误 DECRYPTION_KEY_NOT_FOUND
示例 
                "result_info": {
                    "return_code": "REPORTS_WITH_ERRORS_EXCEEDED_THRESHOLD",
                    "return_message": "Aggregation job failed early because the number of reports excluded from aggregation exceeded threshold.",
                    "error_summary": {
                        "error_counts": [{
                            "category": "DECRYPTION_KEY_NOT_FOUND",
                            "count": 1,
                            "description": "Could not find decryption key on private key endpoint."
                        }, {
                            "category": "NUM_REPORTS_WITH_ERRORS",
                            "count": 1,
                            "description": "Total number of reports that had an error. These reports were not considered in aggregation. See additional error messages for details on specific reasons."
                        }],
                        "error_messages": []
                    }
                }
检查 Attribution Reporting API

对于 Attribution Reporting API，此错误可能是由触发注册问题引起的。检查他们是否已使用 aggregation_coordinator_origin 字段向正确的云注册触发器（相关说明请参阅此处）。您还可能会向其 Google Cloud 版的汇总服务提供 AWS 加密报告，或向其 AWS 版的汇总服务提供 Google Cloud 加密报告。请他们验证用于加密可汇总报告的公钥端点。对于 Google Cloud，可汇总报告中的 `aggregation_coordinator_origin` 字段应为 https://publickeyservice.msmt.gcp.privacysandboxservices.com。对于 AWS，该字段应为 https://publickeyservice.msmt.aws.privacysandboxservices.com。

Private Aggregation API

对于 Private Aggregation API，您必须使用 Private Aggregation API 说明中的“选择汇总协调器”部分中的示例来定义 `aggregationCoordinatorOrigin`。请将 https://publickeyservice.msmt.gcp.privacysandboxservices.com 指定为 aggregationCoordinatorOrigin。

例如：

                sharedStorage.run('someOperation', {'privateAggregationConfig':
                {'aggregationCoordinatorOrigin': ' https://publickeyservice.msmt.gcp.privacysandboxservices.com'}});
错误 DECRYPTION_KEY_FETCH_ERROR
示例 
                "result_info": {
                        "return_code": "REPORTS_WITH_ERRORS_EXCEEDED_THRESHOLD",
                        "return_message": "Aggregation job failed early because the number of reports excluded from aggregation exceeded threshold.",
                        "error_summary": {
                            "error_counts": [
                                {
                                    "category": "DECRYPTION_KEY_FETCH_ERROR",
                                    "count": 1,
                                    "description": "Fetching the decryption key for report decryption failed. This can happen using an unapproved aggregation service binary, running the aggregation service binary in debug mode, key corruption or service availability issues."
                                },
                                {
                                    "category": "NUM_REPORTS_WITH_ERRORS",
                                    "count": 1,
                                    "description": "Total number of reports that had an error. These reports were not considered in aggregation. See additional error messages for details on specific reasons."
                                }
                            ]
                        }
                }
检查 如果出现未经批准的二进制文件或调试模式问题，使用正确的二进制文件即可解决问题。按照此处的说明使用预构建的 AMI 或自行构建 AMI。

请完成以下步骤进行验证：

  1. 您可以使用 aggregatable_report_converter 工具将从 .well-known 端点收集的可汇总报告转换为 AVRO，并创建输出网域密钥。（注意：输出网域文件应为 16 字节的大端字节串。）

  2. 按照适用于您的公共云提供商的 Codelab 中的步骤操作，收集调试报告并使用输出网域密钥运行汇总服务作业： a. Google Cloud：按照汇总服务 Google Cloud Codelab 的步骤 3.1.2 到 3.2.3 操作 b. Amazon Web Services：按照 Aggregation Service AWS Codelab 的第 4.2 步到第 5.3 步操作。

如果此命令返回 SUCCESS 响应，则表示您的转化跟踪功能正常运行。

您的可汇总报告是否完好无损？

验证汇总报告、输出网域密钥和共享信息是否完整无缺。如需了解详情，请参阅示例代码，了解如何转换可汇总报告和创建网域文件。

您可能会看到与此问题对应的以下 API 错误：

错误 INPUT_DATA_READ_FAILED
端点 createJob
检查 createJob 请求中的 input_data_bucket_name、input_data_blob_prefix、output_data_bucket_name 和 output_data_blob_prefix 字段是否正确？输入报告数据位置是否包含要处理的报告？您是否有权从报告和输出网域的存储位置读取数据？

请完成以下步骤进行验证：

  1. 验证汇总报告：

    • 生成汇总报告，并使用 aggregatable_report_converter 工具将输出网域转换为 AVRO 格式。
    • 使用此可汇总报告和输出网域文件运行 createJob 请求。
    • 如果此方法返回 SUCCESS，则表示可汇总报告完好无损。如果此函数返回错误，则表示您的可汇总报告或报告和网域都存在问题。
    • 接下来，请检查网域文件。

  2. 验证输出网域文件：

    • 生成输出网域文件，并使用 aggregatable_report_converter 工具创建可汇总报告。
    • 使用此可汇总报告和输出网域文件运行 createJob 请求。
    • 如果此函数返回 SUCCESS，则表示输出网域完好无损，但您的代码在创建可汇总报告时存在问题。
    • 继续执行下一步，查看 shared_info。

  3. 验证分享的信息：

    • 验证您是否已启用调试报告。启用调试的报告将包含 debug_cleartext_payload 字段。
    • 创建用于本地测试工具的调试报告，并使用 debug_cleartext_payload 作为载荷。
    • 使用您的网域文件运行本地测试工具。如果这是 SUCCESS，则表示您的 shared_info 文件已被篡改。

如果您怀疑存在任何其他错误或篡改行为，请收集 JSON 汇总报告、网域密钥、生成的汇总 AVRO 报告和输出网域，然后继续执行后续步骤。

检查新部署版本

验证您的汇总服务版本是否仍受支持。确定您使用的版本后，请查看汇总服务版本列表，并确认您的版本没有支持终止警告：This release has reached its end of support on { date }。以下用于确定您已部署的版本的说明适用于受支持的公共云。

Google Cloud 的步骤

  1. 前往 Compute Engine > 虚拟机实例。
  2. 点击名称中包含 -worker- 的虚拟机实例。
  3. 找到 Custom Metadata 部分，然后找到键 tee-image-reference。
    • 注意：Terraform 在 Google Cloud 中预配的每个虚拟机都应具有此元数据（工作器模块中的 tee-image-reference 元数据）。
  4. tee-image-reference 的值将包含版本号。例如，以下路径的版本号为 v2.9.1。这些是预构建的映像，位于 Google Cloud 项目的 Artifact Registry 中。
    • 注意：如果您使用的是预构建的素材资源，则此参数非常重要；如果您未使用，则此参数应与您亲自为图片命名的名称和添加的标记相匹配。 （示例：us.docker.pkg.dev/<gcp_project_name>/artifacts:aggregation-service- container-artifacts-worker_mp_go_prod:2.9.1）

Amazon Web Services 的步骤

  1. 在 Amazon Web Services 控制台中，前往 EC2 实例。
  2. 点击名称为 aggregation-service-operator-dev-env 的实例。
  3. 在实例页面上，依次找到“详细信息”> AMI（Amazon 机器映像）
  4. 您的版本名称应包含在图片路径中。例如，以下路径的版本号为 v2.9.1。
    • 注意：如果您使用的是预构建的素材资源，则此参数非常重要；如果您未使用，则此参数应与您亲自为图片命名的名称和添加的标记相匹配。 （示例：aggregation-service-enclave_2.9.1--2024-10-03T01-24-25Z）

后续步骤

如果您找不到汇总服务问题的解决方案，请通过提交 GitHub 问题或技术支持表单通知我们。