1. 必要條件
如要執行本程式碼研究室，您必須具備幾項必備條件。系統會據此標示出「本機測試」或「匯總服務」的必要性。
1.1. 下載本機測試工具 (本機測試)
本機測試必須下載本機測試工具。這項工具會從未加密的偵錯報表產生摘要報表。
您可以在 GitHub 的 Lambda JAR 封存檔案中下載本機測試工具。名稱應命名為 LocalTestingTool_{version}.jar。
1.2. 確保已安裝 JAVA JRE (本機測試與匯總服務)
開啟「Terminal」(終端機)，並使用 java --version 檢查電腦是否已安裝 Java 或 openJDK。
如果尚未安裝，您可以從 Java 網站或 openJDK 網站下載並安裝。
1.3. 下載可匯總報表轉換器 (本機測試和匯總服務)
您可以前往 Privacy Sandbox Demos GitHub 存放區下載可匯總報表轉換工具的副本。
1.4. 啟用 Privacy Sandbox API (本機測試和匯總服務)
在瀏覽器上前往 chrome://flags/#privacy-sandbox-ads-apis，並啟用 Privacy Sandbox 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) 支援匯總服務。本程式碼研究室僅涵蓋 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 上部署匯總服務，您必須將特定權限提供給用來部署服務的使用者。在本程式碼研究室中，請確保使用者擁有管理員權限，確保在部署時擁有完整權限。
1.8. Terraform (匯總服務)
本程式碼研究室使用 Terraform 部署匯總服務。確認您的本機環境已安裝 Terraform 二進位檔。
將 Terraform 二進位檔下載至本機環境。
下載 Terraform 二進位檔後，請擷取檔案，並將 Terraform 二進位檔移至 /usr/local/bin。
cp <directory>/terraform /usr/local/bin
確認類別路徑上可以使用 Terraform。
terraform -v
1.9. Postman (適用於匯總服務 AWS)
在本程式碼研究室中，請使用 Postman 管理要求。
如要建立工作區，請前往「工作區」頂端導覽項目，然後選取「建立工作區」。
選取「Blank workspace」和「Privacy Sandbox」。選取「Personal」(個人)，然後按一下 [Create] (建立)。
使用「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. 本機測試程式碼研究室
您可以使用電腦上的本機測試工具，透過未加密的偵錯報表執行匯總作業並產生摘要報表。
程式碼研究室步驟
步驟 2.1：觸發事件報表：觸發私人匯總報表，才能收集報表。
步驟 2.2：建立可偵錯的可匯總報表：將收集到的 JSON 報表轉換為 AVRO 格式報表。
這個步驟類似廣告技術從 API 報表端點收集報表，並將 JSON 報表轉換為 AVRO 格式報表的時間類似。
步驟 2.3：從偵錯報表中剖析值區金鑰：值區鍵是由廣告技術設計。在本程式碼研究室中，由於值區是預先定義，因此請依指示擷取值區金鑰。
步驟 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 的呼叫端設計，demo 則包含預先建構的範例值區金鑰。由於示範模式已啟用「私人匯總」的偵錯模式，因此您可以從「報表主體」剖析偵錯明文酬載，擷取值區金鑰。不過在本範例中，Privacy Sandbox 示範網站會建立值區金鑰。這個網站的私人匯總功能處於偵錯模式，因此您可以使用「報表內文」中的 debug_cleartext_payload 取得值區鍵。
從報表內文複製 debug_cleartext_payload。
開啟「Debug payload decoder 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。
在程式碼研究室中，我們會使用提供的 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. 下載預先建構的依附元件
複製匯總服務存放區後，請前往存放區的 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，並為 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. 建立匯總服務輸入內容
繼續建立 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
在本程式碼研究室中，您將手動執行報表收集作業。在實際工作環境中，廣告技術應以程式輔助方式收集報表並轉換。
在 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」方塊中，然後按一下「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 節中設定的海報全域變數 frontend_api_id。
步驟 5：匯總服務使用情形：使用 Aggregation Service API 建立摘要報告並查看摘要報告。
步驟 5.1：使用 createJob 端點進行批次處理
步驟 5.2：使用 getJob Endpoint 擷取批次狀態
步驟 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 Endpoint 擷取批次狀態
如要查看工作要求的狀態，您可以使用 getJob 端點。在「Privacy Sandbox」getJob集合中選取「getJob」getJob。
在「Params」中，將工作_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 檔案中取得值區金鑰。