1. 前提条件
この Codelab を実行するには、いくつかの前提条件が必要です。各要件は、「ローカルテスト」と「集計サービス」のどちらで必須かに応じて示されています。
1.1. ローカルテストツール(ローカルテスト)をダウンロードする
ローカルテストを行うには、ローカルテストツールをダウンロードする必要があります。このツールは、暗号化されていないデバッグ レポートから概要レポートを生成します。
ローカルテストツールは、GitHub の Lambda JAR アーカイブからダウンロードできます。LocalTestingTool_{version}.jar
という名前になります。
1.2. Java JRE がインストールされていることを確認してください(ローカルテストと集計サービス)
[Terminal] を開き、java --version
を使用して、マシンに Java または openJDK がインストールされているかどうかを確認します。
インストールされていない場合は、Java のサイトまたは openJDK のサイトからダウンロードしてインストールできます。
1.3. 集計可能レポートのコンバータをダウンロードする(ローカルテストと集計サービス)
集計可能レポート コンバータのコピーは、プライバシー サンドボックスのデモ GitHub リポジトリからダウンロードできます。
1.4. プライバシー サンドボックスの API(ローカルテストと集計サービス)を有効にする
ブラウザで chrome://flags/#privacy-sandbox-ads-apis
に移動し、プライバシー サンドボックスの API を有効にします。
サードパーティ Cookie が有効になっていることを確認します。
ブラウザで chrome://settings/cookies
に移動し、[シークレット モードでサードパーティの Cookie をブロックする] を選択します。
1.5. ウェブと Android の登録(集計サービス)
本番環境でプライバシー サンドボックスの API を使用するには、Chrome と Android の両方で登録と証明書が完了している必要があります。
ローカルテストでは、Chrome フラグと CLI スイッチを使用して登録を無効にできます。
このデモで Chrome フラグを使用するには、chrome://flags/#privacy-sandbox-enrollment-overrides
に移動して、オーバーライドをサイトで更新します。デモサイトを使用する場合は、更新する必要はありません。
1.6. 集計サービスのオンボーディング(集計サービス)
アグリゲーション サービスを使用するには、コーディネーターへのオンボーディングが必要です。Aggregation Service Onboarding フォームに、レポートサイトのアドレス、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 を使用します。
上部のナビゲーション アイテムである [ワークスペース] に移動し、[ワークスペースを作成] を選択してワークスペースを作成します。
[Blank workspace] を選択し、[Next] をクリックして「Privacy Sandbox」という名前を付けます。[個人用] を選択し、[作成] をクリックします。
事前構成されたワークスペースの JSON 構成ファイルとグローバル環境ファイルをダウンロードします。
[Import] ボタンを使用して JSON ファイルを [My Workspace] にインポートします。
これにより、createJob
および getJob
HTTP リクエストとともに、プライバシー サンドボックス コレクションが作成されます。
環境クイック ルックで AWS の「Access Key」と「Secret Key」を更新します。
[編集] をクリックし、[access_key] と [secret_key] の両方の [現在の値] を更新します。frontend_api_id
はこのドキュメントのセクション 3.1.4 で提供されます。us-east-1 リージョンの使用をおすすめします。ただし、別のリージョンにデプロイする場合は、リリース済みの AMI をアカウントにコピーするか、提供されているスクリプトを使用してセルフビルドを実行してください。
2. ローカルテストの Codelab
マシン上のローカルテストツールを使用すると、暗号化されていないデバッグ レポートを使用して集計を実行し、概要レポートを生成できます。
Codelab の手順
ステップ 2.1. レポートを送信: 非公開の集計レポートをトリガーしてレポートを収集できます。
ステップ 2.2. Create aggregatable report: 収集した JSON レポートを AVRO 形式のレポートに変換します。
このステップは、広告テクノロジーが API レポート エンドポイントからレポートを収集し、JSON レポートを AVRO 形式のレポートに変換する場合と同様です。
ステップ 2.3. デバッグ レポートからバケットキーを解析する: バケットキーは広告テクノロジーによって設計されています。この Codelab ではバケットが事前定義されているため、指定されたバケットキーを取得します。
ステップ 2.4. 出力ドメイン AVRO を作成する: バケットキーを取得したら、出力ドメイン AVRO ファイルを作成します。
ステップ 2.5. ローカル テストツールを使用して概要レポートを作成する: ローカル テストツールを使用すると、ローカル環境で概要レポートを作成できるようになります。
ステップ 2.6. 概要レポートを確認する: ローカル テストツールによって作成された概要レポートを確認します。
2.1. レポートをトリガー
プライバシー サンドボックスのデモサイトにアクセスします。これにより、非公開の集計レポートがトリガーされます。レポートは chrome://private-aggregation-internals
でご覧いただけます。
レポートのステータスが [保留中] の場合は、レポートを選択して [選択したレポートを送信] をクリックします。
2.2. デバッグ集計可能レポートを作成する
chrome://private-aggregation-internals
で、[reporting-origin]/.well-known/private-aggregation/report-shared-storage
エンドポイントで受け取った「Report Body」をコピーします。
[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」のデバッグ クリアテキスト ペイロードを解析してバケットキーを取得できます。ただし、この場合、サイトのプライバシー サンドボックスのデモでバケットキーを作成します。このサイトの非公開集計はデバッグモードのため、「レポート本文」の debug_cleartext_payload
を使用してバケットキーを取得できます。
レポート本文から debug_cleartext_payload
をコピーします。
[Debug payload decoder for Private Aggregation] ツールを開き、debug_cleartext_payload
を [INPUT] ボックスに貼り付けて [INPUT] をクリックします。
このページに、バケットキーの 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. 集計サービス リポジトリのクローンを作成する
ローカル環境で、Aggregation Service 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
を更新し、i
を押して input
でファイルを編集します。
vim dev.auto.tfvars
次の画像の赤いボックス内のフィールドを、Aggregation Service のオンボーディング、環境、通知メールで提供される正しい AWS ARN パラメータで更新します。
更新が完了したら、esc
-> :wq!
を押します。dev.auto.tfvars
ファイルが保存され、次の画像のようになります。
3.4. 集計サービスをデプロイする
集計サービスをデプロイするには、同じフォルダ
で Terraform を初期化します。
terraform init
次の画像のような結果が返されます。
Terraform を初期化したら、Terraform の実行プランを作成します。追加するリソースの数と、次の図のようなその他の追加情報が返されます。
terraform plan
以下の [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. レポートをトリガー
プライバシー サンドボックスのデモサイトにアクセスします。これにより、非公開の集計レポートがトリガーされます。レポートは 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
この Codelab では、レポートの収集を手動で実行します。本番環境では、広告テクノロジーがプログラムでレポートを収集して変換することが想定されています。
chrome://private-aggregation-internals
で、[reporting-origin]/.well-known/private-aggregation/report-shared-storage
エンドポイントで受け取った「Report Body」をコピーします。
[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
ファイルを作成するには、レポートから取得できるバケットキーが必要です。
バケットキーは広告テクノロジーによって設計されます。ただし、この場合、サイトのプライバシー サンドボックスのデモでバケットキーを作成します。このサイトの非公開集計はデバッグモードのため、「レポート本文」の debug_cleartext_payload
を使用してバケットキーを取得できます。
レポート本文から debug_cleartext_payload
をコピーします。
goo.gle/ags-payload-decoder を開き、[INPUT] ボックスに debug_cleartext_payload
を貼り付け、[INPUT] をクリックします。
このページに、バケットキーの 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. 集計サービスの使用状況: 集計サービス 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"
}
}
[送信] をクリックすると、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-news.dev"
},
"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
リクエストに true
として debug_run
が含まれている場合は、output_data_blob_prefix
にあるデバッグ フォルダで概要レポートを受け取ることができます。レポートは AVRO 形式であり、前述のコマンドを使用して JSON に変換できます。
このレポートには、バケットキー、ノイズなしの指標、ノイズなしの指標に追加されるノイズが含まれ、概要レポートが形成されます。レポートは次の画像のようになります。
アノテーションには in_reports
と in_domain
も含まれています。これは、次のことを意味します。
- in_reports - バケットキーは集計可能レポート内で使用できます。
- in_domain - バケットキーは output_domain AVRO ファイル内で利用できます。