在 AWS 上使用匯總服務

1. 先決條件

如要執行這個程式碼研究室，您必須符合幾項必要條件。每項規定都會標示是否適用於「本機測試」或「匯總服務」。

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

您必須下載本機測試工具才能進行本機測試。這項工具會根據未加密的偵錯報表產生摘要報表。

您可以在 GitHub 中的 Lambda JAR 封存檔下載本機測試工具。其名稱應為 LocalTestingTool_{version}.jar。

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

開啟「Terminal」，然後使用 java --version 檢查機器是否已安裝 Java 或 openJDK。

使用 java\n--version 檢查 Java JRE 版本

如果尚未安裝，您可以前往 Java 網站或 openJDK 網站下載及安裝。

1.3. 下載可匯總報表轉換工具 (本機測試和匯總服務)

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

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

在瀏覽器中前往 chrome://settings/adPrivacy，然後啟用所有 Ad Privacy API。

確認已啟用第三方 Cookie。

在瀏覽器中前往 chrome://settings/cookies，然後選取「在無痕模式中封鎖第三方 Cookie」。

第三方 Cookie chromesetting

1.5. 網頁和 Android 註冊 (匯總服務)

如要在正式版環境中使用 Privacy Sandbox API，請務必為 Chrome 和 Android 完成註冊和認證程序。

進行本機測試時，您可以使用 Chrome 旗標和 CLI 切換鈕停用註冊功能。

如要使用 Chrome 旗標進行示範，請前往 chrome://flags/#privacy-sandbox-enrollment-overrides，然後更新網站的覆寫值。如果您要使用我們的示範網站，則無需更新。

隱私權沙箱註冊覆寫 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 值區來儲存 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 是否可在 classpath 上使用。

terraform -v

1.9. Postman (匯總服務 AWS 專用)

在本程式碼研究室中，請使用 Postman 管理要求。

如要建立工作區，請前往頂端導覽選單中的「工作區」，然後選取「建立工作區」。

postmanworkspace

選取「空白工作區」，按一下「下一步」，然後將其命名為「Privacy Sandbox」。選取「個人」，然後按一下「建立」。

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

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

匯入 Postman JSON 檔案

系統會為您建立 Privacy Sandbox 集合，以及 createJob 和 getJob HTTP 要求。

Postman 匯入集合

透過「環境快速檢視」更新 AWS「存取金鑰」和「密鑰」。

Postman 環境快速瀏覽

按一下「編輯」，然後更新「access_key」和「secret_key」的「Current Value」(目前值)。請注意，frontend_api_id 會在本文件的 3.1.4 節中提供。我們建議您使用 us-east-1 區域。不過，如果您想在其他區域部署，請務必將已發布的 AMI 複製到您的帳戶，或使用提供的指令碼執行自建作業。

Postman 全域變數

Postman 編輯全域變數

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 查看這份報表。

chrome private aggregationinternals

如果報表狀態為「待處理」，您可以選取報表，然後按一下「傳送所選報表」。

傳送私密匯總報表

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 報表。

private aggregationreport

將 JSON 格式的「Report Body」放入 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. 剖析偵錯報表中的值區鍵

匯總服務在批次處理時需要兩個檔案。可匯總的報表和輸出網域檔案。輸出網域檔案包含您要從可匯總報表擷取的鍵。如要建立 output_domain.avro 檔案，您需要從報表擷取值區鍵。

值區鍵是由 API 呼叫端設計，示範包含預先建構的值區鍵範例。由於這個示範已為私人匯總啟用偵錯模式，因此您可以剖析「報表主體」中的偵錯明文酬載，擷取值區鍵。不過，在本例中，網站 Privacy Sandbox 示範會建立值區鍵。由於這個網站的私人匯總資料處於偵錯模式，您可以使用「報表主體」中的 debug_cleartext_payload 取得值區鍵。

從報表主體複製 debug_cleartext_payload。

從 reportbody 偵錯明文酬載

開啟「Debug payload decoder for Private Aggregation」工具，將 debug_cleartext_payload 貼到「INPUT」方塊中，然後按一下「Decode」。

payloaddecoder

這個頁面會傳回值區塊鍵的小數值。以下是值區鍵的範例。

酬載 decoderresult

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。

本機測試摘要報表 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. 下載預先建構的依附元件

複製匯總服務存放區後，請前往存放區的 Terraform 資料夾和對應的雲端資料夾。如果您的 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 檔案，然後按下 input 的 i 編輯檔案。

vim main.tf

移除紅色方塊中的 # 並更新值集和鍵名，即可取消註解紅色方塊中的程式碼。

AWS main.tf：

AWS 主要的 tffile

無註解的程式碼應如下所示。

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 參數。

編輯開發人員自動 tfvars 檔案

更新完成後，請依序按下 esc -> :wq!。這會儲存 dev.auto.tfvars 檔案，檔案內容應如下圖所示。

更新開發人員自動 tfvarsfile

3.4. 部署匯總服務

如要部署匯總服務，請在同一個資料夾 /terraform/aws/environments/dev 中初始化 Terraform。

terraform init

這項指令應會傳回類似下圖的內容：

terraforminit

初始化 Terraform 後，請建立 Terraform 執行計畫。系統會傳回要新增的資源數量和其他額外資訊，如下圖所示。

terraform plan

您可以在下方查看「企劃書」摘要。如果這是新的部署作業，您應該會看到新增資源的數量，以及 0 個變更和 0 個刪除的資源。

terraformplan

完成後，您就可以繼續套用 Terraform。

terraform apply

系統提示您確認要由 Terraform 執行動作時，請在值中輸入 yes。

terraform applyprompt

terraform apply 完成後，系統會傳回 createJob 和 getJob 的以下端點。第 1.9 節中，您需要在 Postman 中更新的 frontend_api_id 也會一併傳回。

terraform applycomplete

4. 匯總服務輸入內容建立

請繼續建立匯總服務中的 AVRO 報表，以便匯總。

步驟 4：匯總服務輸入內容建立作業：建立匯總服務的匯總服務報表。
步驟 4.1.觸發報表
步驟 4.2.收集可匯總報表
步驟 4.3. 將報表轉換為 AVRO
步驟 4.4 建立輸出網域 AVRO

4.1. 觸發條件報表

前往 Privacy Sandbox 示範網站。這會觸發私人匯總報表。您可以前往 chrome://private-aggregation-internals 查看這份報表。

chrome private aggregationinternals

如果報表狀態為「待處理」，您可以選取報表，然後按一下「傳送所選報表」。

傳送私密匯總報表

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 報表。

private aggregationreport

將 JSON 格式的「Report Body」放入 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 檔案，您需要從報表擷取值區鍵。

值區塊鍵是由廣告技術設計，但在本例中，網站 Privacy Sandbox 示範會建立值區塊鍵。由於這個網站的私人匯總資料處於偵錯模式，您可以使用「報表主體」中的 debug_cleartext_payload 取得值區鍵。

請從報表內文複製 debug_cleartext_payload。

從 reportbody 偵錯明文酬載

開啟 goo.gle/ags-payload-decoder，然後將 debug_cleartext_payload 貼到「INPUT」方塊中，並按一下「Decode」。

payloaddecoder

這個頁面會傳回值區塊鍵的小數值。以下是值區鍵的範例。

酬載 decoderresult

有了值區鍵後，請繼續建立 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 requestbody

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"
  }
}

點選「Send」後，系統會使用 job_request_id 建立工作。匯集服務接受要求後，您應該會收到 HTTP 202 回應。如需其他可能的傳回代碼，請參閱 HTTP 回應代碼

postman createJob requeststatus

5.2. 使用 getJob 端點擷取批次狀態

如要查看工作要求的狀態，您可以使用 getJob 端點。在「Privacy Sandbox」集合中選取「getJob」。

在「Params」中，將 job_request_id 值更新為 createJob 要求中傳送的 job_request_id。

postman getJobrequest

getJob 的結果應會傳回工作要求的狀態，並附上 HTTP 狀態 200。要求的「Body」包含必要資訊，例如 job_status、return_message 和 error_messages (如果工作發生錯誤)。

postman getJob requeststatus

由於系統產生的示範報表報表網站與 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，如下圖所示。

summaryreport

如果 createJob 要求包含 debug_run 做為 true，您可以在 output_data_blob_prefix 中的偵錯資料夾中收到摘要報表。報表採用 AVRO 格式，可使用前述指令轉換為 JSON。

報表包含值區鍵、未經雜訊處理的指標，以及加入至未經雜訊處理指標的雜訊，以便形成摘要報表。報表會像下圖所示。

偵錯摘要報表

註解也包含 in_reports 和 in_domain，分別代表：

  • in_reports - 可匯總報表內的桶別鍵。
  • in_domain：bucket 索引鍵可在 output_domain AVRO 檔案中使用。