1. 前提条件
若要完成此 Codelab，您需要满足一些前提条件。每个要求都会相应地标记为“本地测试”或“汇总服务”所需。
1.1. 下载本地测试工具（本地测试）
若要进行本地测试，您需要下载本地测试工具。该工具将根据未加密的调试报告生成摘要报告。
您可以在 GitHub 中的 Lambda JAR 归档中下载本地测试工具。该文件应命名为 LocalTestingTool_{version}.jar。
1.2. 确保已安装 JAVA JRE（本地测试和汇总服务）
打开“终端”，然后使用 java --version 检查您的机器是否安装了 Java 或 openJDK。
如果未安装，您可以从 Java 网站或 openJDK 网站下载并安装。
1.3. 下载可汇总报告转换器（本地测试和汇总服务）
您可以从 Privacy Sandbox 演示版 GitHub 代码库下载可汇总报告转换器的副本。
1.4. 启用 Ad Privacy API（本地测试和汇总服务）
在浏览器中，前往 chrome://settings/adPrivacy 并启用所有 Ad Privacy API。
确保已启用第三方 Cookie。
在浏览器中，前往 chrome://settings/cookies，然后选择“在无痕模式下阻止第三方 Cookie”。
1.5. 网页版和 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 在 classpath 上可用。
terraform -v
1.9. Postman（适用于汇总服务 AWS）
在本 Codelab 中，请使用 Postman 进行请求管理。
如需创建工作区，请前往顶部导航栏中的“工作区”部分，然后选择“创建工作区”。
选择“空白工作区”，点击“下一步”，然后将其命名为“隐私沙盒”。选择“个人”，然后点击“创建”。
使用“导入”按钮将 JSON 文件导入“我的工作区”。
这将为您创建 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”。
确保在“Report Body”（报告正文）中，aggregation_coordinator_origin 包含 https://publickeyservice.msmt.aws.privacysandboxservices.com，这表示报告是可汇总的 AWS 报告。
将 JSON“Report Body”（报告正文）放入 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 demo 会创建存储分区键。由于此网站的私密汇总处于调试模式，因此您可以使用“Report Body”（报告正文）中的 debug_cleartext_payload 获取存储分区键。
从报告正文中复制 debug_cleartext_payload。
打开用于调试私有汇总的载荷解码器工具，将 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. 汇总服务部署
如需部署汇总服务，请按以下步骤操作：
第 3 步：汇总服务部署：在 AWS 上部署汇总服务
第 3.1 步克隆汇总服务代码库
第 3.2 步下载预构建依赖项
第 3.3 步创建开发环境
第 3.4 步部署汇总服务
3.1. 克隆汇总服务代码库
在本地环境中，克隆汇总服务 GitHub 代码库。
git clone https://github.com/privacysandbox/aggregation-service.git
3.2. 下载预构建的依赖项
克隆 Aggregation Service 代码库后，前往代码库的 Terraform 文件夹和相应的云文件夹。如果您的 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 文件，然后按 i 以 input 身份修改该文件。
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，然后按 i 以 input 身份修改文件。
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. 汇总服务输入创建
继续创建 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 - Attribution Reporting - 摘要报告
[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”。
确保在“Report Body”（报告正文）中，aggregation_coordinator_origin 包含 https://publickeyservice.msmt.aws.privacysandboxservices.com，这表示报告是可汇总的 AWS 报告。
将 JSON“Report Body”（报告正文）放入 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 演示版会创建存储分区键。由于此网站的私密汇总处于调试模式，因此您可以使用“Report Body”（报告正文）中的 debug_cleartext_payload 获取存储分区键。
请从报告正文中复制 debug_cleartext_payload。
打开 goo.gle/ags-payload-decoder，将 debug_cleartext_payload 粘贴到“INPUT”（输入）框中，然后点击“Decode”（解码）。
该页面会返回存储分区键的十进制值。以下是存储分区键的示例。
现在，我们已经有了存储分区密钥，接下来创建 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 API 创建摘要报告并查看摘要报告。
第 5.1 步使用 createJob 端点批量处理
第 5.2 步使用 getJob 端点检索批处理状态
第 5.3 步查看摘要报告
5.1. 使用 createJob 端点进行批处理
在 Postman 中，打开“Privacy Sandbox”集合，然后选择“createJob”。
选择“Body”，然后选择“raw”以放置请求载荷。
createJob 载荷架构可在 github 上找到，如下所示。将 <> 替换为适当的字段。
{
"job_request_id": "<job_request_id>",
"input_data_blob_prefix": "<report_folder>/<report_name>.avro",
"input_data_bucket_name": "<bucket_name>",
"output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
"output_data_bucket_name": "<bucket_name>",
"job_parameters": {
"output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
"output_domain_bucket_name": "<bucket_name>",
"attribution_report_to": "<reporting origin of report>",
"reporting_site": "<domain of reporting origin(s) of report>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
"report_error_threshold_percentage": "10",
"debug_run": "true"
}
}
点击“发送”后，系统会使用 job_request_id 创建作业。汇总服务接受请求后，您应该会收到 HTTP 202 响应。如需查看其他可能的返回代码，请参阅 HTTP 响应代码
5.2. 使用 getJob 端点检索批处理状态
如需检查作业请求的状态，您可以使用 getJob 端点。在“隐私沙盒”集合中，选择“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",
"reporting_site": "<domain of reporting origin(s) of report>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
},
"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，该 JSON 类似于以下图片。
如果您的 createJob 请求将 debug_run 作为 true，则您可以在 output_data_blob_prefix 中的调试文件夹中接收摘要报告。该报告采用 AVRO 格式，可以使用上一个命令转换为 JSON。
该报告包含存储分区键、未添加噪声的指标以及添加到未添加噪声的指标中以形成摘要报告的噪声。报告类似于以下图片。
注释还包含 in_reports 和 in_domain，分别表示：
- in_reports - 该分桶键可在可汇总报告中使用。
- in_domain - 存储分区密钥位于 output_domain AVRO 文件中。