1. 先決條件
如要完成本程式碼研究室，請務必符合以下條件：每個規定都會標示為「本機測試」或「匯總服務」的必要條件。
1.1. 下載本機測試工具 (本機測試)
如要進行本機測試，請下載本機測試工具。這項工具會根據未加密的偵錯報表產生摘要報表。
您可以在 Github 的 Lambda JAR 封存檔中下載本機測試工具。名稱應為 LocalTestingTool_{version}.jar。
1.2. 確認已安裝 JAVA JRE (本機測試和匯總服務)
開啟「終端機」，並使用 java --version 檢查機器是否已安裝 Java 或 openJDK。
使用 `java --version` 檢查 java jre 版本。
如果尚未安裝，請從 Java 網站或 openJDK 網站下載並安裝。
1.3. 下載可匯總報表轉換器 (本機測試和匯總服務)
您可以從 Privacy Sandbox Demos Github 存放區下載可彙整報表轉換器的副本。
1.4. 啟用廣告隱私權 API (本機測試和匯總服務)
在瀏覽器中前往 chrome://settings/adPrivacy，然後啟用所有廣告隱私權 API。
確認已啟用第三方 Cookie。
在瀏覽器中前往 chrome://settings/cookies，然後選取「在無痕模式中封鎖第三方 Cookie」。
第三方 Cookie 的 Chrome 設定。
1.5. 網頁和 Android 註冊 (匯總服務)
如要在正式版環境中使用 Privacy Sandbox API，請務必完成 Chrome 和 Android 的註冊和認證。
如要進行本機測試，可以使用 Chrome 旗標和 CLI 切換器停用註冊功能。
如要在示範中使用 Chrome 旗標，請前往 chrome://flags/#privacy-sandbox-enrollment-overrides 並更新覆寫項目 (如果使用我們的示範網站，則不需要更新)。
Privacy Sandbox 註冊覆寫 Chrome 旗標。
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 Bucket 來儲存 Terraform 狀態，並建立另一個 S3 Bucket 來儲存報表和摘要報表。您可以使用提供的 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 (匯總服務)
本程式碼研究室會使用 Terraform 部署 Aggregation Service。確認 Terraform 二進位檔已安裝至本機環境。
將 Terraform 二進位檔下載到本機環境。
下載 Terraform 二進位檔後，請解壓縮檔案，然後將 Terraform 二進位檔移至 /usr/local/bin。
cp <directory>/terraform /usr/local/bin
確認 Terraform 是否位於類別路徑中。
terraform -v
1.9. Postman (適用於匯總服務 AWS)
在本程式碼研究室中，請使用 Postman 管理要求。
前往頂端導覽列的「工作區」，然後選取「建立工作區」，即可建立工作區。
Postman 工作區
選取「空白工作區」，按一下「下一步」，然後將工作區命名為「Privacy Sandbox」。選取「個人」，然後按一下「建立」。
使用「匯入」按鈕，將 JSON 檔案匯入「我的工作區」。
匯入 Postman JSON 檔案。
系統會為您建立 Privacy Sandbox 集合，以及 createJob 和 getJob HTTP 要求。
已匯入的 Postman 集合。
透過「環境快速查看」更新 AWS「存取金鑰」和「密鑰」。
Postman 環境快速瀏覽。
按一下「編輯」，然後更新「access_key」和「secret_key」的「目前值」。請注意，frontend_api_id 會在本文件的第 3.1.4 節中提供。建議使用 us-east-1 區域。不過，如要在其他區域部署，請確認您已將發布的 AMI 複製到帳戶中，或使用提供的指令碼自行建構。
Postman 全域變數。 
Postman 編輯全域變數。
2. 本機測試程式碼研究室
您可以使用電腦上的本機測試工具執行匯總作業，並使用未加密的偵錯報告產生摘要報表。
程式碼研究室步驟
步驟 2.1：觸發報表：觸發私密匯總報表，以便收集報表。
步驟 2.2：建立可匯總的偵錯報表：將收集到的 JSON 報表轉換為 AVRO 格式的報表。
這個步驟與廣告技術從 API 報表端點收集報表，並將 JSON 報表轉換為 AVRO 格式報表時類似。
步驟 2.3：從偵錯報表剖析 bucket 鍵：bucket 鍵是由廣告技術設計。在本程式碼研究室中，由於值區是預先定義，請按照提供的內容擷取值區鍵。
步驟 2.4：建立輸出網域 AVRO：擷取 bucket 金鑰後，建立輸出網域 AVRO 檔案。
步驟 2.5：使用本機測試工具建立摘要報表：使用本機測試工具，在本機環境中建立摘要報表。
步驟 2.6：查看摘要報表：查看本機測試工具建立的摘要報表。
2.1. 觸發條件報表
前往 Privacy Sandbox 試用版網站。這會觸發私有匯總報表。如要查看報表，請前往 chrome://private-aggregation-internals。
Chrome 私密匯總內部功能。
如果報表處於「待處理」狀態，您可以選取報表，然後按一下「傳送所選報表」。
傳送私人匯總報表。
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 中，然後儲存檔案。
報表 JSON 檔案。
取得該檔案後，請前往報表資料夾，並使用 aggregatable_report_converter.jar 建立可匯總的偵錯報表。這會在目前的目錄中建立名為 report.avro 的可匯總報表。
java -jar aggregatable_report_converter.jar \
--request_type convertToAvro \
--input_file report.json \
--debug
2.3. 從偵錯報告剖析 bucket 鍵
匯總服務在批次處理時需要兩個檔案。可匯總的報表和輸出網域檔案。輸出網域檔案包含您要從可匯總報表擷取的金鑰。如要建立 output_domain.avro 檔案，您需要可從報表擷取的值區金鑰。
Bucket 金鑰是由 API 呼叫端設計，試用版包含預先建構的範例 bucket 金鑰。由於這個範例已啟用私密匯總的偵錯模式，因此您可以從「Report Body」(報表主體) 剖析偵錯明文酬載，以擷取 bucket 金鑰。不過，在本例中，網站 Privacy Sandbox 示範會建立 bucket 鍵。由於這個網站的私密匯總功能處於偵錯模式，因此您可以使用「報表主體」中的 debug_cleartext_payload 取得 bucket 鍵。
從報表內文複製 debug_cleartext_payload。
從報表主體偵錯明文酬載。
開啟私有匯總的偵錯酬載解碼器工具，將 debug_cleartext_payload 貼到「INPUT」方塊中，然後按一下「Decode」。
酬載解碼器。
網頁會傳回 bucket 鍵的十進位值。以下是值區金鑰範例。
酬載解碼器結果。
2.4. 建立輸出網域 AVRO
現在我們有了 bucket 鍵，請複製 bucket 鍵的十進位值。接著，請使用 bucket 金鑰建立 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。
本機測試摘要報告 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。
摘要 avro 檔案已轉換為 json。
在您選擇的編輯器中開啟 JSON 檔案，即可查看摘要報表。
3. 部署匯總服務
如要部署匯總服務，請按照下列步驟操作：
步驟 3：部署匯總服務：在 AWS 上部署匯總服務
步驟 3.1. 複製匯總服務存放區
步驟 3.2. 下載預先建構的依附元件
步驟 3.3. 建立開發環境
步驟 3.4. 部署匯總服務
3.1. 複製匯總服務存放區
在本機環境中，複製 Aggregation Service 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
移除 # 並更新 bucket 和金鑰名稱，取消註解紅框中的程式碼。
適用於 AWS main.tf：
AWS 主要 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 參數，更新下圖紅框中的欄位。
編輯開發自動 tfvars 檔案。
更新完成後，請依序按下 esc -> :wq!。這樣就會儲存 dev.auto.tfvars 檔案，內容應如下圖所示。
更新開發自動 tfvars 檔案。
3.4. 部署匯總服務
如要部署匯總服務，請在相同資料夾
terraform init
這時應該會傳回類似下圖的內容：
Terraform init。
初始化 Terraform 後，請建立 Terraform 執行計畫。系統會傳回要新增的資源數量和其他額外資訊，類似於下圖。
terraform plan
您可以在下方看到「方案」摘要。如果是全新部署作業，您應該會看到要新增的資源數量，以及要變更和刪除的資源數量 (皆為 0)。
Terraform 方案。
完成後，即可繼續套用 Terraform。
terraform apply
Terraform 提示您確認執行動作時，請在值中輸入 yes。
Terraform 套用提示。
terraform apply 完成後，系統會傳回 createJob 和 getJob 的下列端點。系統也會傳回您需要在 Postman 的第 1.9 節中更新的 frontend_api_id。
Terraform apply complete.
4. 建立匯總服務輸入內容
接著，請在匯總服務中建立 AVRO 報表，以便進行批次處理。
步驟 4：建立匯總服務輸入內容：建立匯總服務報表，並批次處理這些報表，以便匯總服務使用。
步驟 4.1. 觸發報表
步驟 4.2。收集可匯總報表
步驟 4.3. 將報表轉換為 AVRO
步驟 4.4。建立輸出網域 AVRO
4.1. 觸發條件報表
前往 Privacy Sandbox 示範網站。這會觸發私有匯總報表。如要查看報表，請前往 chrome://private-aggregation-internals。
Chrome 私密匯總內部功能。
如果報表處於「待處理」狀態，您可以選取報表，然後按一下「傳送所選報表」。'
傳送私人匯總報表。
4.2. 收集可匯總報表
從相應 API 的 .well-known 端點收集可匯總報表。
- Private Aggregation
[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 中，然後儲存檔案。
報表 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 檔案，您需要可從報表擷取的值區金鑰。
廣告技術會設計 bucket 鍵，但在此情況下，網站 Privacy Sandbox 示範會建立 bucket 鍵。由於這個網站的私密匯總功能處於偵錯模式，因此您可以使用「報表主體」中的 debug_cleartext_payload 取得 bucket 鍵。
請從報表內文複製 debug_cleartext_payload。
從報表主體偵錯明文酬載。
開啟 goo.gle/ags-payload-decoder，將 debug_cleartext_payload 貼到「INPUT」方塊中，然後按一下「Decode」。
酬載解碼器。
網頁會傳回 bucket 鍵的十進位值。以下是值區金鑰範例。
酬載解碼器結果。
有了 bucket 金鑰後，請繼續建立 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：匯總服務使用情形：使用匯總服務 API 建立摘要報表，並查看摘要報表。
步驟 5.1. 使用 createJob 端點批次處理
步驟 5.2。使用 getJob 端點擷取批次狀態
步驟 5.3. 查看摘要報表
5.1. 使用 createJob 端點進行批次處理
在 Postman 中開啟「Privacy Sandbox」集合，然後選取「createJob」。
選取「Body」，然後選取「raw」來放置要求酬載。
postman createJob request body
createJob 酬載結構定義位於 GitHub，如下所示。將 <> 替換為適當的欄位。
{
"job_request_id": "<job_request_id>",
"input_data_blob_prefix": "<report_folder>/<report_name>.avro",
"input_data_blob_prefixes": [
"<report_folder>/<report_name-1>/",
"<report_folder>/<report_name-2>/",
"<report_folder>/<report_name>.avro"
], // Mutually exclusive to input_data_blob_prefix as of v2.11.0
"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>", // Mutually exclusive to attribution_report_to as of v2.7.0
"report_error_threshold_percentage": "10",
"debug_run": "true"
}
}
按一下「傳送」後，系統就會使用 job_request_id 建立工作。要求獲聚合服務接受後，您應該會收到 HTTP 202 回應。如需其他可能的回傳代碼，請參閱 HTTP 回應代碼
postman createJob request status
5.2. 使用 getJob 端點擷取批次狀態
如要查看工作要求狀態，可以使用 getJob 端點。在「Privacy Sandbox」集合中選取「getJob」。
在「Params」中，將 job_request_id 值更新為 createJob 要求中傳送的 job_request_id。
postman getJob request
getJob 的結果應會傳回工作要求狀態，以及 HTTP 狀態 200。要求「Body」包含必要資訊，例如 job_status、return_message 和 error_messages (如果工作發生錯誤)。
postman getJob 要求狀態
由於產生的示範報表與 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_blob_prefixes": [ // Mutually exclusive to input_data_blob_prefix as of v2.11.0
"<report_folder>/<report_name-1>/",
"<report_folder>/<report_name-2>/",
"<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>", // Mutually exclusive to attribution_report_to as of v2.7.0
},
"request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}
5.3. 查看摘要報表
在輸出 S3 Bucket 中收到摘要報表後，即可下載到本機環境。摘要報表採用 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 - bucket 金鑰位於 output_domain AVRO 檔案中。