1. 前提条件
この Codelab を実行するには、いくつかの前提条件を満たす必要があります。各要件は、「ローカルテスト」に必要なかどうかに応じてマークされています。または「集計サービス」とも呼ばれます。
1.1. ローカル テストツール（ローカルテスト）をダウンロードする
ローカルテストを行うには、ローカル テストツールをダウンロードする必要があります。このツールは、暗号化されていないデバッグ レポートから概要レポートを生成します。
ローカル テストツールは、GitHub の Lambda JAR アーカイブからダウンロードできます。LocalTestingTool_{version}.jar という名前にします。
1.2. JAVA JRE がインストールされていることを確認してください（ローカルテストと集約サービス）
[ターミナル] を開きます。java --version を使用して、マシンに Java または openJDK がインストールされているかどうかを確認します。
インストールされていない場合は、Java のサイトまたは openJDK のサイトからダウンロードしてインストールできます。
1.3. 集計可能レポート コンバータ（ローカルテストおよび集計サービス）をダウンロード
集計可能レポート コンバータのコピーは、Privacy Sandbox Demos GitHub リポジトリからダウンロードできます。
1.4. Ad Privacy API（ローカルテストおよび集計サービス）を有効にする
ブラウザで chrome://settings/adPrivacy に移動し、Ad Privacy API をすべて有効にします。
サードパーティ Cookie が有効になっていることを確認します。
ブラウザで chrome://settings/cookies にアクセスし、[シークレット モードでサードパーティの Cookie をブロックする] を選択します。
1.5. ウェブと Android の登録（集計サービス）
プライバシー サンドボックス API を本番環境で使用するには、Chrome と Android の両方で登録と認証が完了している必要があります。
ローカルテストの場合は、Chrome フラグと CLI スイッチを使用して登録を無効にできます。
デモで Chrome フラグを使用するには、chrome://flags/#privacy-sandbox-enrollment-overrides に移動して、自分のサイトでオーバーライドを更新します。デモサイトを使用する場合は、更新の必要はありません。
1.6. 集計サービスのオンボーディング（集計サービス）
集約サービスを使用するには、コーディネーターへのオンボーディングが必要です。集計サービスのオンボーディング フォームに、レポートサイトのアドレス、AWS アカウント ID などの情報を入力します。
1.7.クラウド プロバイダ（集約サービス）
集約サービスでは、クラウド環境を使用する高信頼実行環境を使用する必要があります。集約サービスは、アマゾン ウェブ サービス（AWS）と Google Cloud（GCP）でサポートされています。この Codelab では、AWS との統合についてのみ説明します。
AWS では、Nitro Enclaves と呼ばれる高信頼実行環境を提供しています。AWS アカウントがあることを確認し、AWS CLI のインストールと更新の手順に沿って AWS CLI 環境を設定します。
AWS CLI が新しい場合は、CLI の構成手順で AWS CLI を構成できます。
1.7.1.AWS S3 バケットを作成する
Terraform の状態を保存する AWS S3 バケットと、レポートとサマリー レポートを保存する別の 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 API エンドポイントと 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 を使用します。
[ワークスペース] に移動してワークスペースを作成します。上部のナビゲーション項目をクリックして [Create Workspace] を選択します。
[Blank workspace] を選択し、次へをクリックして「Privacy Sandbox」という名前を付けます。[個人用] を選択します。[作成] をクリックします。
事前構成済みのワークスペースの JSON 構成ファイルとグローバル環境ファイルをダウンロードします。
JSON ファイルを「My Workspace」にインポートします。[インポート]を使用して] ボタンを離します。
これにより、プライバシー サンドボックスのコレクションが createJob および getJob HTTP リクエストとともに作成されます。
AWS のアクセスキーを更新する「秘密鍵」「環境の概要」をご覧ください。
[Edit] をクリックします。[現在の値]を「access_key」の両方「secret_key」を指定します。なお、frontend_api_id については、このドキュメントのセクション 3.1.4 で説明します。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. トリガー レポート
プライバシー サンドボックスのデモサイトにアクセスします。これにより、非公開集計レポートがトリガーされます。レポートは chrome://private-aggregation-internals で確認できます。
レポートが [保留中] と表示されている場合ステータスが表示されたら、そのレポートを選択して [Send Selected Reports] をクリックします。
2.2. デバッグ集計可能レポートを作成
chrome://private-aggregation-internals で、「Report Body」をコピーします。エンドポイントで[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. デバッグ レポートのバケットキーを解析する
集計サービスでは、バッチ処理時に 2 つのファイルが必要です。集計可能レポートと出力ドメイン ファイル。出力ドメイン ファイルには、集計可能レポートから取得するキーが含まれています。output_domain.avro ファイルを作成するには、レポートから取得できるバケットキーが必要です。
バケットキーは API の呼び出し元によって設計されます。デモには、事前に作成されたバケットキーの例が含まれています。このデモではプライベート アグリゲーションのデバッグモードが有効になっているため、[Report Body] からデバッグ クリアテキスト ペイロードを解析できます。バケットキーを取得..この場合は、サイトのプライバシー サンドボックスのデモによってバケットキーが作成されます。このサイトの非公開集計はデバッグモードであるため、[Report Body] の debug_cleartext_payload を使用できますバケットキーを取得します
レポート本文から debug_cleartext_payload をコピーします。
[Debug payload decoder for Private Aggregation] ツールを開き、[入力] に debug_cleartext_payload を貼り付けます。[デコード] をクリックします。
バケットキーの 10 進数値が返されます。バケットキーの例を次に示します。
2.4. 出力ドメイン AVRO を作成する
バケットキーが作成できたので、バケットキーの 10 進数値をコピーします。バケット鍵を使用して 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.集計サービス リポジトリのクローンを作成します。
ステップ 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
以下の [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. トリガー レポート
プライバシー サンドボックスのデモサイトにアクセスします。これにより、非公開集計レポートがトリガーされます。レポートは chrome://private-aggregation-internals で確認できます。
レポートが [保留中] と表示されている場合ステータスが表示されたら、そのレポートを選択して [Send Selected Reports] をクリックします。
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 で、「Report Body」をコピーします。エンドポイントで[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 ファイルを作成するには、レポートから取得できるバケットキーが必要です。
バケットキーは広告テクノロジーによって設計されています。ただし、この場合は、サイトのプライバシー サンドボックスのデモによってバケットキーが作成されます。このサイトの非公開集計はデバッグモードであるため、[Report Body] の debug_cleartext_payload を使用できますバケットキーを取得します
では、レポート本文から debug_cleartext_payload をコピーします。
goo.gle/ags-payload-decoder を開き、[入力] に debug_cleartext_payload を貼り付けます[デコード] をクリックします。
バケットキーの 10 進数値が返されます。バケットキーの例を次に示します。
バケットキーが作成できたので、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 Endpoint を使用してバッチ処理する
ステップ 5.2.getJob Endpoint を使用してバッチ ステータスを取得する
ステップ 5.3.概要レポートの確認
5.1. createJob エンドポイントを使用したバッチ処理
Postman で「プライバシー サンドボックス」を開きます[createJob] を選択します。
[Body] を選択します。[raw] を選択します配置する必要があります
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 レスポンス コードで確認できます。
5.2. getJob Endpoint を使用してバッチ ステータスを取得する
ジョブ リクエストのステータスを確認するには、getJob エンドポイントを使用します。[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-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 が返されます。
createJob リクエストに debug_run が true として含まれている場合、概要レポートは output_data_blob_prefix にある debug フォルダに届きます。レポートは AVRO 形式であり、上記のコマンドを使用して JSON に変換できます。
このレポートには、バケットキー、ノイズのない指標、ノイズのない指標に追加されたノイズが含まれ、概要レポートが作成されます。レポートは次の画像のようになります。
アノテーションには in_reports と in_domain も含まれています。これは、次のことを意味します。
- in_reports - バケットキーは集計可能レポート内で使用できます。
- in_domain - バケットキーは output_domain AVRO ファイル内で使用できます。