1. 前提条件
如需执行此 Codelab，必须满足一些前提条件。每项要求都会相应地注明是“本地测试”还是“聚合服务”需要。
1.1. 下载本地测试工具（本地测试）
使用本地测试时，您需要下载本地测试工具。该工具将根据未加密的调试报告生成摘要报告。
您可以在 GitHub 中的 Lambda JAR 归档中下载本地测试工具。应将其命名为 LocalTestingTool_{version}.jar。
1.2. 确保已安装 JAVA JRE（本地测试和汇总服务）
打开“Terminal”（终端）并使用 java --version 检查机器是否已安装 Java 或 openJDK。
如果未安装，您可以从 Java 网站或 openJDK 网站下载并安装。
1.3. 下载 Aggregatable Report Converter（本地测试和汇总服务）
您可以从 Privacy Sandbox 演示 GitHub 代码库中下载可汇总报告转换器的副本。
1.4. 启用 Privacy Sandbox API（本地测试和聚合服务）
在浏览器中，前往 chrome://flags/#privacy-sandbox-ads-apis 并启用 Privacy Sandbox API。
确保已启用第三方 Cookie。
在浏览器中，前往 chrome://settings/cookies，然后选择“在无痕模式下阻止第三方 Cookie”。
1.5. Web 和 Android 注册（汇总服务）
如需在生产环境中使用 Privacy Sandbox API，请确保您已针对 Chrome 和 Android 完成注册和证明。
对于本地测试，可以使用 Chrome 标志和 CLI 开关停用注册。
若要在我们的演示中使用 Chrome 标志，请前往 chrome://flags/#privacy-sandbox-enrollment-overrides 并将替换项更新为您的网站；如果您要使用我们的演示版网站，则无需更新。
1.6. 汇总服务新手入门（汇总服务）
整合服务要求必须通过培训，协调员才能使用服务。填写汇总服务新手入门表单，提供您的报告网站地址、AWS 账号 ID 和其他信息。
1.7. 云服务提供商（汇总服务）
汇总服务需要使用采用云环境的可信执行环境。Amazon Web Services (AWS) 和 Google Cloud (GCP) 支持汇总服务。此 Codelab 将仅介绍 AWS 集成。
AWS 提供了一种名为 Nitro Enclaves 的可信执行环境。确保您拥有 AWS 账号，并按照 AWS CLI 安装和更新说明设置您的 AWS CLI 环境。
如果是新的 AWS CLI，您可以按照 CLI 配置说明来配置 AWS CLI。
1.7.1. 创建 AWS S3 存储分区
创建一个 AWS S3 存储分区来存储 Terraform 状态，并创建另一个 S3 存储分区来存储报告和摘要报告。您可以使用提供的 CLI 命令。将 <> 中的字段替换为适当的变量。
aws s3api create-bucket --bucket <tf_bucket_name> --region us-east-1
aws s3api create-bucket --bucket <report_bucket_name> --region us-east-1
1.7.2. 创建用户访问密钥
按照 AWS 指南创建用户访问密钥。这将用于调用在 AWS 上创建的 createJob 和 getJob API 端点。
1.7.3. AWS 用户和群组权限
要在 AWS 上部署汇总服务，您需要为用于部署该服务的用户提供特定权限。对于此 Codelab，请确保用户拥有管理员权限，以确保在部署时拥有完整权限。
1.8. Terraform（汇总服务）
此 Codelab 使用 Terraform 部署汇总服务。确保 Terraform 二进制文件已安装到您的本地环境中。
将 Terraform 二进制文件下载到本地环境中。
下载 Terraform 二进制文件后，解压缩该文件并将 Terraform 二进制文件移动到 /usr/local/bin。
cp <directory>/terraform /usr/local/bin
检查以确保 Terraform 在类路径上可用。
terraform -v
1.9. Postman（适用于汇总服务 AWS）
对于此 Codelab，请使用 Postman 来管理请求。
前往“工作区”顶部的导航项，然后选择创建工作区，以创建工作区。
选择“Blank workspace”，然后点击“Next”并将其命名为“Privacy Sandbox”。选择个人，然后点击创建。
使用 Import（导入）按钮，将 JSON 文件导入“My Workspace”（我的工作区）。
这将为您创建 Privacy Sandbox 集合以及 createJob 和 getJob HTTP 请求。
通过“环境快速查看”更新 AWS“访问密钥”和“密钥”。
点击修改，然后更新“access_key”和“secret_key”的“当前值”。请注意，本文档的第 3.1.4 节中提供了 frontend_api_id。我们建议您使用 us-east-1 区域。但是，如果您想在其他区域中进行部署，请务必将已发布的 AMI 复制到您的帐号中，或使用提供的脚本自行构建。
2. 本地测试 Codelab
您可以使用计算机上的本地测试工具执行汇总，并使用未加密的调试报告生成摘要报告。
Codelab 步骤
第 2.1 步：触发报告：触发私密汇总报告以便收集报告。
第 2.2 步：创建可汇总的调试报告：将收集的 JSON 报告转换为 AVRO 格式的报告。
此步骤与广告技术平台从 API 报告端点收集报告并将 JSON 报告转换为 AVRO 格式的报告时类似。
第 2.3 步：解析调试报告中的存储分区键：存储分区键由广告技术平台设计。在此 Codelab 中，由于存储分区是预定义的，因此请检索所提供的存储分区键。
第 2.4 步：创建输出网域 AVRO：检索存储分区密钥后，创建输出网域 AVRO 文件。
第 2.5 步：使用本地测试工具创建摘要报告：使用本地测试工具在本地环境中创建摘要报告。
第 2.6 步：查看摘要报告：查看本地测试工具创建的摘要报告。
2.1. 触发器报告
前往 Privacy Sandbox 演示网站。这会触发不公开的汇总报告。您可以访问以下网址查看该报告：chrome://private-aggregation-internals。
如果您的报告处于待处理状态，您可以选择该报告并点击发送所选报告。
2.2. 创建可汇总的调试报告
在 chrome://private-aggregation-internals 中，复制 [reporting-origin]/.well-known/private-aggregation/report-shared-storage 端点中收到的报告正文。
确保“Report Body”中的 aggregation_coordinator_origin 包含 https://publickeyservice.msmt.aws.privacysandboxservices.com，这表示该报告是 AWS 可汇总报告。
将 JSON“报告正文”放入 JSON 文件中。在此示例中，您可以使用 vim。不过，您可以根据需要使用任何文本编辑器。
vim report.json
将报告粘贴到 report.json 中，然后保存您的文件。
找到后，前往报告文件夹，并使用 aggregatable_report_converter.jar 帮助创建可汇总的调试报告。这会在当前目录中创建一个名为 report.avro 的可汇总报告。
java -jar aggregatable_report_converter.jar \
--request_type convertToAvro \
--input_file report.json \
--debug
2.3. 解析调试报告中的存储分区密钥
汇总服务在进行批处理时需要两个文件。可汇总报告和输出网域文件。输出网域文件包含您要从可汇总报告中检索的密钥。如需创建 output_domain.avro 文件，您需要可从报告中检索到的存储分区键。
存储分区密钥由 API 的调用方设计，此演示包含预先构建的示例存储分区密钥。由于该演示版为“不公开汇总”启用了调试模式，因此您可以从“Report Body”解析调试明文载荷以检索存储分区密钥。不过，在这种情况下，由网站 privacy Sandbox 演示创建存储分区密钥。由于此网站的不公开汇总处于调试模式，因此您可以使用报告正文中的 debug_cleartext_payload 获取存储分区键。
从报告正文中复制 debug_cleartext_payload。
打开 Debug payload Der for Private Aggregation 工具，将 debug_cleartext_payload 粘贴到“INPUT”框中，然后点击“Decode”。
页面返回存储分区键的小数值。以下是一个示例存储分区键。
2.4. 创建输出域 AVRO
现在，我们已经有了存储分区键，接下来复制存储分区键的小数值。继续使用存储分区密钥创建 output_domain.avro。确保将
java -jar aggregatable_report_converter.jar \
--request_type createDomainAvro \
--bucket_key <bucket key>
该脚本会在当前文件夹中创建 output_domain.avro 文件。
2.5. 使用本地测试工具创建摘要报告
我们将使用在第 1.1 节中下载的 LocalTestingTool_{version}.jar 来创建摘要报告。请使用以下命令。您应该将 LocalTestingTool_{version}.jar 替换为为 LocalTestingTool 下载的版本。
运行以下命令，以在本地开发环境中生成摘要报告：
java -jar LocalTestingTool_{version}.jar \
--input_data_avro_file report.avro \
--domain_avro_file output_domain.avro \
--output_directory .
运行该命令后，您应该会看到如下图所示的内容。完成后，系统将创建报告 output.avro。
2.6. 查看摘要报告
系统会以 AVRO 格式创建摘要报告。为了能够读取此内容，您需要将其从 AVRO 转换为 JSON 格式。理想情况下，广告技术平台应进行编码，以将 AVRO 报告转换回 JSON。
对于我们的 Codelab，我们将使用提供的 aggregatable_report_converter.jar 工具将 AVRO 报告转换回 JSON。
java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file output.avro
系统将返回如下图所示的报告。以及在同一目录中创建的 output.json 报告。
在您选择的编辑器中打开该 JSON 文件，查看摘要报告。
3. Aggregation Service 部署
如需部署汇总服务，请按以下步骤操作：
第 3 步：汇总服务部署：在 AWS 上部署汇总服务
第 3.1 步：克隆 Aggregation Service Repository
第 3.2 步：下载预构建依赖项
第 3.3 步：创建开发环境
第 3.4 步：部署汇总服务
3.1. 克隆汇总服务代码库
在本地环境中，克隆汇总服务 GitHub 代码库。
git clone https://github.com/privacysandbox/aggregation-service.git
3.2. 下载预构建依赖项
克隆 Aggregation Service 仓库后，前往该仓库的 Terraform 文件夹和相应的 Cloud 文件夹。如果您的 cloud_provider 是 AWS，则可以继续执行
cd <repository_root>/terraform/aws
在 download_prebuilt_dependencies.sh。
bash download_prebuilt_dependencies.sh
3.3. 创建开发环境
在 dev 的文件夹。
mkdir dev
将 demo 文件夹内容复制到 dev 文件夹中。
cp -R demo/* dev
将其移至“dev”文件夹。
cd dev
更新您的 main.tf 文件，然后按 input 的 i 以编辑该文件。
vim main.tf
移除 # 并更新存储分区和键名称，取消对红色框中代码的注释。
对于 AWS main.tf：
未加注释的代码应如下所示。
backend "s3" {
bucket = "<tf_state_bucket_name>"
key = "<environment_name>.tfstate"
region = "us-east-1"
}
更新完成后，请保存更新，并按 esc -> :wq! 退出编辑器。这会保存 main.tf 的更新。
接下来，将 example.auto.tfvars 重命名为 dev.auto.tfvars。
mv example.auto.tfvars dev.auto.tfvars
更新 dev.auto.tfvars，然后按 input 的 i 以编辑该文件。
vim dev.auto.tfvars
使用汇总服务初始配置期间提供的正确 AWS ARN 参数、环境和通知电子邮件，更新下图红色框中的字段。
更新完成后，按 esc -> :wq!。这将保存 dev.auto.tfvars 文件，它应如下图所示。
3.4. 部署汇总服务
如需部署聚合服务，请在同一文件夹
terraform init
这应返回如下图所示的内容：
初始化 Terraform 后，请创建 Terraform 执行计划。该函数会返回要添加的资源数量以及其他与下图类似的其他信息。
terraform plan
您可以在下面的“方案”摘要中了解相关信息。如果是全新部署，您应该会看到将添加的资源数量，其中 0 代表更改，0 代表销毁。
完成此操作后，您就可以继续应用 Terraform。
terraform apply
Terraform 在提示您确认是否执行相应操作后，在值中输入 yes。
terraform apply 完成后，系统会返回 createJob 和 getJob 的以下端点。系统也会返回您需要在第 1.9 节中在 Postman 中更新的 frontend_api_id。
4. Aggregation Service 输入创建
继续创建 AVRO 报告，以便在汇总服务中进行批处理。
第 4 步：创建汇总服务输入：创建汇总服务报告，以便针对汇总服务进行批量处理。
第 4.1 步：触发报告
第 4.2 步：收集可汇总报告
第 4.3 步：将报告转换为 AVRO
第 4.4 步：创建输出域 AVRO
4.1. 触发器报告
前往 Privacy Sandbox 演示网站。这会触发不公开的汇总报告。您可以访问以下网址查看该报告：chrome://private-aggregation-internals。
如果您的报告处于待处理状态，您可以选择该报告并点击发送所选报告。
4.2. 收集可汇总的报告
从相应 API 的 .well-known 端点收集可汇总报告。
- 不公开汇总
[reporting-origin] /.well-known/private-aggregation/report-shared-storage - 归因报告 - 摘要报告
[reporting-origin] /.well-known/attribution-reporting/report-aggregate-attribution
对于此 Codelab，您将手动执行报告收集。在生产环境中，广告技术平台应以编程方式收集并转换报告。
在 chrome://private-aggregation-internals 中，复制 [reporting-origin]/.well-known/private-aggregation/report-shared-storage 端点中收到的报告正文。
确保“Report Body”中的 aggregation_coordinator_origin 包含 https://publickeyservice.msmt.aws.privacysandboxservices.com，这表示该报告是 AWS 可汇总报告。
将 JSON“报告正文”放入 JSON 文件中。在此示例中，您可以使用 vim。不过，您可以根据需要使用任何文本编辑器。
vim report.json
将报告粘贴到 report.json 中，然后保存您的文件。
4.3. 将报告转换为 AVRO
从 .well-known 端点收到的报告采用 JSON 格式，需要转换为 AVRO 报告格式。获得 JSON 报告后，转到报告文件夹，然后使用 aggregatable_report_converter.jar 创建可汇总的调试报告。这会在当前目录中创建一个名为 report.avro 的可汇总报告。
java -jar aggregatable_report_converter.jar \
--request_type convertToAvro \
--input_file report.json
4.4. 创建输出域 AVRO
如需创建 output_domain.avro 文件，您需要可从报告中检索到的存储分区键。
存储分区密钥由广告技术平台设计。但在本例中，存储分区密钥由网站 Privacy Sandbox 演示网站创建。由于此网站的不公开汇总处于调试模式，因此您可以使用报告正文中的 debug_cleartext_payload 获取存储分区键。
接下来，从报告正文中复制 debug_cleartext_payload。
打开 goo.gle/ags-payload-decoder，将您的 debug_cleartext_payload 粘贴到“INPUT”框中，然后点击“INPUT”。
页面返回存储分区键的小数值。以下是一个示例存储分区键。
现在，我们有了存储分区密钥，接下来创建 output_domain.avro。确保将
java -jar aggregatable_report_converter.jar \
--request_type createDomainAvro \
--bucket_key <bucket key>
该脚本会在当前文件夹中创建 output_domain.avro 文件。
4.5. 将报告移至 AWS 存储分区
创建 AVRO 报告（在第 3.2.3 节）和输出域（第 3.2.4 节）后，接下来将报告和输出域移入报告 S3 分桶。
如果您在本地环境中设置了 AWS CLI，请使用以下命令将报告复制到相应的 S3 存储分区和报告文件夹。
aws s3 cp report.avro s3://<report_bucket_name>/<report_folder>/
aws s3 cp output_domain.avro s3://<report_bucket_name>/<output_domain_folder>/
5. 汇总服务使用情况
从 terraform apply 中，您将返回 create_job_endpoint、get_job_endpoint 和 frontend_api_id。复制 frontend_api_id 并将其放入您在前提条件部分 1.9 中设置的 postman 全局变量 frontend_api_id。
第 5 步：Aggregation Service Usage：使用 Aggregation Service API 创建摘要报告并查看摘要报告。
第 5.1 步：使用 createJob Endpoint 进行批处理
第 5.2 步：使用 getJob Endpoint 检索批处理状态
第 5.3 步查看汇总报告
5.1. 使用 createJob 端点进行批处理
在 Postman 中，打开 Privacy Sandbox 集合，然后选择“createJob”。
选择“Body”，然后选择“raw”以放置您的请求载荷。
github 中提供了 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>",
"report_error_threshold_percentage": "10",
"debug_run": "true"
}
}
点击“Send”后，将使用 job_request_id 创建作业。汇总服务接受请求后，您应该会收到 HTTP 202 响应。您可以在 HTTP 响应代码中找到其他可能的返回代码
5.2. 使用 getJob Endpoint 检索批量状态
如需检查作业请求的状态，您可以使用 getJob 端点。在“Privacy Sandbox”集合中选择“getJob”。
在“Params”中，将 job_request_id 值更新为 createJob 请求中发送的 job_request_id。
getJob 的结果应返回 HTTP 状态为 200 的作业请求的状态。请求“Body”包含 job_status、return_message 和 error_messages 等必要信息（如果作业出错）。
由于生成的演示报告的报告网站与 AWS ID 上初始设置的网站不同，因此您可能会收到包含 PRIVACY_BUDGET_AUTHORIZATION_ERROR return_code 的响应。这很正常，因为报告来源的网站与针对 AWS ID 启用的报告网站不匹配。
{
"job_status": "FINISHED",
"request_received_at": "2023-12-07T22:50:58.830956Z",
"request_updated_at": "2023-12-07T22:51:10.526326456Z",
"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>",
"postback_url": "",
"result_info": {
"return_code": "PRIVACY_BUDGET_AUTHORIZATION_ERROR",
"return_message": "Aggregation job successfully processed",
"error_summary": {
"error_counts": [],
"error_messages": []
},
"finished_at": "2023-12-07T22:51:10.517730898Z"
},
"job_parameters": {
"debug_run": "true",
"output_domain_bucket_name": "<output_domain_bucket_name>",
"output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
"attribution_report_to": "https://privacy-sandbox-demos-dsp.dev"
},
"request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}
5.3. 查看汇总报告
在输出 S3 存储分区中收到摘要报告后，您可以将其下载到本地环境中。摘要报告采用 AVRO 格式，并可转换回 JSON。您可以使用 aggregatable_report_converter.jar 通过以下命令读取报告。
java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file <summary_report_avro>
这将返回每个存储分区键的汇总值的 JSON，类似于下图。
如果您的 createJob 请求包含的 debug_run 为 true，则您可以在 output_data_blob_prefix 中的“debug”文件夹中收到摘要报告。报告采用 AVRO 格式，可以使用之前的命令将其转换为 JSON。
该报告包含桶键、未添加噪声的指标，以及添加到不带噪声的指标以生成摘要报告的噪声。报告类似于下图。
这些注解还包含 in_reports 和 in_domain，这意味着：
- in_reports - 存储分区键在可汇总报告中可用。
- in_domain - 存储分区密钥可在 output_domain AVRO 文件中找到。