1. 前提条件
要执行此 Codelab，需要满足一些前提条件。系统会相应地标记每项要求，是“本地测试”还是“汇总服务”要求。
1.1. 下载本地测试工具（本地测试）
您需要下载本地测试工具才能进行本地测试。该工具将根据未加密的调试报告生成摘要报告。
本地测试工具可从 GitHub 的 Lambda JAR 归档中下载。它应命名为 LocalTestingTool_{version}.jar。
1.2. 确保已安装 JAVA JRE（本地测试和汇总服务）
打开 Terminal（终端），然后使用 java --version 检查机器是否已安装 Java 或 openJDK。
如果尚未安装，您可以从 Java 网站或 openJDK 网站下载并安装。
1.3. 下载可汇总报告转换器（本地测试和汇总服务）
您可以从 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 flag 和 CLI 开关停用注册。
若要在我们的演示中使用 Chrome flag，请前往 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 管理请求。
如需创建工作区，请前往“工作区”顶部导航项，然后选择“创建工作区”。
选择空白工作区，点击下一步并将其命名为“Privacy Sandbox”。选择个人，然后点击创建。
使用 Import 按钮将 JSON 文件导入到 My Workspace 中。
此操作将为您创建 Privacy Sandbox 集合以及 createJob 和 getJob HTTP 请求。
通过“Environment quick look”（环境快速查看）更新 AWS“Access Key”和“Secret Key”。
点击修改，然后更新“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 端点中收到的报告正文。
确保报告正文中的 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. 解析调试报告中的存储分区键
Aggregation Service 在批处理时需要两个文件。可汇总报告和输出网域文件。输出网域文件包含您要从可汇总报告中检索的键。若要创建 output_domain.avro 文件，您需要可从报告中检索到的存储分区键。
存储分区密钥由 API 的调用方设计，演示包含预先构建的示例存储分区密钥。此演示为不公开汇总启用了调试模式，因此您可以从“报告正文”解析调试明文载荷，以检索存储分区密钥。不过，在这种情况下，存储分区密钥是由网站 Privacy Sandbox demo 创建的。由于此网站的不公开汇总处于调试模式，因此您可以使用“报告正文”中的 debug_cleartext_payload 来获取存储分区键。
从报告正文中复制 debug_cleartext_payload。
打开 Debug payload Der for Private Aggregation 工具，将您的 debug_cleartext_payload 粘贴到“INPUT”框中，然后点击“INPUT”。
此页面会返回存储分区键的十进制值。以下是一个示例存储分区键。
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 步：克隆 Aggregation Service Repository
第 3.2 步：下载预构建的依赖项
第 3.3 步：创建一个开发环境
第 3.4 步：部署汇总服务
3.1. 克隆 Aggregation Service 代码库
在您的本地环境中，克隆 Aggregation Service 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 文件，然后按 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. 部署汇总服务
如需部署 Aggregation Service，请在同一文件夹
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 - 归因报告 - 摘要报告
[reporting-origin] /.well-known/attribution-reporting/report-aggregate-attribution
对于此 Codelab，您将手动执行报告收集。在生产环境中，广告技术平台应以编程方式收集和转换报告。
在 chrome://private-aggregation-internals 中，复制 [reporting-origin]/.well-known/private-aggregation/report-shared-storage 端点中收到的报告正文。
确保报告正文中的 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 端点进行批处理
第 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": "<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 端点检索批处理状态
如需检查作业请求的状态，您可以使用 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-news.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 的调试文件夹中收到摘要报告。报告为 AVRO 格式，可以使用之前的命令转换为 JSON。
该报告包含桶键、无噪声指标，以及为形成摘要报告而添加到无噪声指标的噪声。报告类似于下图。
注解还包含 in_reports 和 in_domain，这意味着：
- in_reports - 分区键在可汇总报告中提供。
- in_domain - 存储分区密钥在 output_domain AVRO 文件中可用。