在 AWS 上使用匯總服務

1. 必要條件

如要執行這個程式碼研究室，必須符合幾項先決條件。系統會根據每項要求，標示出「本機測試」或「匯總服務」的需求條件。

1.1. 下載本機測試工具 (本機測試)

本機測試將需要下載本機測試工具。這項工具會從未加密的偵錯報表中產生摘要報表。

本機測試工具可從 GitHub 的 Lambda JAR Archives 中下載。路徑應命名為 LocalTestingTool_{version}.jar。

1.2. 確保已安裝 JAVA JRE (本機測試與匯總服務)

開啟「終端機」，並使用 java --version 檢查機器是否已安裝 Java 或 OpenJDK。

如果尚未安裝，請前往 Java 網站或 openJDK 網站下載並安裝。

1.3. 下載可匯總報表轉換器 (本機測試與匯總服務)

您可以從 Privacy Sandbox 示範 GitHub 存放區下載可匯總報表轉換工具副本。

1.4. 啟用廣告隱私權 API (本機測試與匯總服務)

透過瀏覽器前往 chrome://settings/adPrivacy，並啟用���有廣告隱私權 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」。選取「個人」，然後按一下「建立」。

下載預先設定的工作區 JSON 設定和全域環境檔案。

使用「Import」按鈕，將 JSON 檔案匯入「我的工作區」。

這項操作會為您建立 Privacy Sandbox 集合以及 createJob 和 getJob HTTP 要求。

透過「Environment Quick Look」功能更新 AWS 的「存取金鑰」和「密鑰」。

按一下「編輯」，然後更新「access_key」和「secret_key」的「Current Value」。請注意，就必須遵守本文件第 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「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 呼叫端所設計，demo 包含預先建構的範例值區金鑰。由於這項示範已啟用私密匯總的偵錯模式，因此您可以透過報告內文剖析偵錯明文酬載，以擷取值區金鑰。不過，在這個情況下，網站的隱私沙箱示範模式會建立值區金鑰。由於這個網站的私人匯總功能處於偵錯模式，因此你可以使用「報告內文」中的 debug_cleartext_payload 取得值區鍵。

複製報表內文中的 debug_cleartext_payload。

開啟「Debug payload decoder for Private Aggregation」工具，並將 debug_cleartext_payload 貼到「INPUT」INPUT方塊中，然後按一下「Decode」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。

在程式碼研究室中，我們會使用提供的 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 資料夾。如果您的 cloud_provider 是 AWS，可以繼續 /terraform/aws

cd <repository_root>/terraform/aws

在 /terraform/aws 中執行 download_prebuilt_dependencies.sh。

bash download_prebuilt_dependencies.sh

3.3. 建立開發環境

在 /terraform/aws/environments 中建立開發環境。建立名為 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/aws/environments/dev 初始化 Terraform。

terraform init

這應該會傳回類似以下圖片的內容：

初始化 Terraform 後，請建立 Terraform 執行計畫。在這裡可以傳回要新增的資源數量，以及其他類似下圖的資訊。

terraform plan

您可以在下方「計畫」摘要中得知。如果這是全新的部署作業，您應該會看到新增的資源數量 (0 為 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「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 示範網站會建立值區金鑰。由於這個網站的私人匯總功能處於偵錯模式，因此你可以使用「報告內文」中的 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：匯總服務使用情形：使用匯總服務 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」。getJobgetJob

在「Params」中，將 task_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 的偵錯資料夾中收到摘要報表。報表為 AVRO 格式，您可以使用先前的指令將報表轉換成 JSON。

報表中包含值區鍵、未雜訊的指標，以及為了形成摘要報表而加入的未雜訊指標。報表類似下圖。

註解也包含 in_reports 和 in_domain，這表示：

• in_reports - 範圍鍵會列在可匯總報表中。
• in_domain - 值區金鑰位於 output_domain AVRO 檔案內。