このページは Cloud Translation API によって翻訳されました。

Private Aggregation API の基礎

Private Aggregation API の主なコンセプト

このドキュメントの対象者

Private Aggregation API クロスサイトデータにアクセスできるワークレットから集約したデータ収集が可能です。ここで紹介するコンセプトは、レポートを構築するデベロッパーにとって重要です。 Protected Audience API です。

クロスサイト用のレポートシステムを構築しているデベロッパーの場合測定します
マーケティング担当者、データサイエンティスト、その他の概要レポートの場合消費者、これらのメカニズムを理解することで、最適化済み概要レポートを取得することもできます

主な用語

このドキュメントを読む前に、インフラストラクチャの主な用語と概念について説明します。ここでは、それぞれの用語について詳しく説明します。

集計キー（バケットとも呼ばれます）は、データポイントを収集できますたとえばブラウザが国をレポートする場所データのバケット表示されます。集計キーには複数のディメンション（例: 国や ID など）が含まれます。
集計可能な値は個々のデータポイント集約キーに集約されます。新規ユーザーの数をフランスのユーザーがコンテンツを閲覧した場合、France は次のディメンションのディメンションです。 1 の viewCount は集計可能な値です。
集計可能レポートは、ブラウザ内で生成され、暗号化されます。対象: Private Aggregation API: 単一のイベントに関するデータが含まれます。
集計サービス 集計可能レポートのデータを処理して概要レポートを作成します。
概要レポートは、集計サービスの最終出力です。ノイズの多い集計ユーザーデータと詳細なコンバージョンデータが含まれている。
ワークレットは、特定の JavaScript 関数を実行し、リクエスト元に情報を返します。ワークレット内では外部ページとの通信や通信はできません。

プライベートアグリゲーションのワークフロー

集計キーと UDM イベントを指定して Private Aggregation API を集計可能値を指定すると、ブラウザは集計可能レポートを生成します。レポート一括処理を行うサーバーに送られます一括処理されたレポートは集計サービスによって後で処理され、概要レポートが生成されます。

クライアントからコレクタ、そしてアグリゲーションへと続くデータフロー
概要レポートを生成するサービス。

Private Aggregation API を呼び出すと、クライアント（ブラウザ）によって集計可能レポートをサーバーに送信して収集します。
サーバーがクライアントからレポートを収集してバッチ処理し、集計サービスに送信されます
十分な数のレポートを収集したら、バッチ処理して高信頼実行環境で実行され、Google Cloud Storage 概要レポートを作成します

で確認できます。

このセクションで説明するワークフローは、アトリビューションレポート API。ただし、レポートでは、インプレッションイベントとコンバージョンから収集されたデータが関連付けられる異なるタイミングで発生します。プライベートアグリゲーションでは測定します

集計キー

集計キー（略して「キー」）は、集計対象となるバケットを集計可能な値が累積されます1 つ以上のディメンションをエンコードできます。渡します。ディメンションは、さらに取得したい側面を表しますユーザーの年齢層や広告のインプレッション数などあります

たとえば、複数のサイトに埋め込まれたウィジェットがあり、ウィジェットを見たユーザーの国を分析できます。検索中たとえば “私のウィジェットを見たユーザーの数どこから来たんですか？」この質問に関するレポートを作成するには、集計キーを設定します 2 つのディメンション（ウィジェット ID と国 ID）をエンコードしています。

Private Aggregation API に提供されるキーは、 BigInt、複数のディメンションで構成されています。この例のディメンションはウィジェット ID と国 ID ですウィジェット ID は最大 4 桁であるとします 1234 などの長さ。各国はアルファベット順の数字にマッピングされます。（例: アフガニスタンは 1、フランスは 61、ジンバブエは「195」）。したがって、集計可能キーは 7 桁になり、最初の 4 桁は WidgetID では予約され、最後の 3 文字は CountryID 用に予約されています。

たとえば、キーがフランス（国 ID 061）のユーザー数を表すとします。 3276、集計キーは3276061です。

集計キー
ウィジェット ID	国 ID
3,276	061

例: ディメンションに使用可能なキースペースがある場合よりも少ない場合は、先頭にゼロを追加します。たとえば国 ID に 3 桁の数字がある場合、アルジェリアの国 ID は 003。

集計キーは、次のようなハッシュメカニズムを使用して生成することもできます。 SHA-256。たとえば、 {"WidgetId":3276,"CountryID":67} はハッシュ化して次の値 BigInt: 42943797454801331377966796057547478208888578253058197330928948081739249096287n。ハッシュ値が 128 ビットを超える場合は、切り捨てられないように短縮できます。バケットの最大許容値 2^128−1 を超えています。

共有ストレージワークレットでは、 crypto、 TextEncoder モジュールハッシュ値を生成できますハッシュの生成について詳しくは、以下をご覧ください。 SubtleCrypto.digest() オン MDN。

次の例は、ハッシュ化された鍵ファイルからバケットキーを生成する方法を value:

async function convertToBucket(data) {
  // Encode as UTF-8 Uint8Array
  const encodedData = new TextEncoder().encode(data);

  // Generate SHA-256 hash
  const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);

  // Truncate the hash
  const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));

  // Convert the byte sequence to a decimal
  return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}

const data = {
  WidgetId: 3276,
  CountryID: 67
};

const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);

console.log(bucket); // 126200478277438733997751102134640640264n

集計可能な値

集計可能な値は、多数のユーザーのキーごとに合計され、集計データが生成されます。概要レポートの概要値の形式で提供されます。

ここで、先ほど出した質問例に戻りましょう。「何人のユーザーがフランスのウィジェットを見た人はいますか？」この質問の答えは「私のウィジェット ID 3276 を見た約 4,881 人のユーザーがフランスの料理です。」集計可能な値は、ユーザーごとに 1、「4, 881 人のユーザー」です。集計されたすべての集計可能な値の合計である、集計値 集計キー。

集計キー		集計可能な値
ウィジェット ID	国 ID	視聴回数
3,276	061	1

この例では、ウィジェットを表示するユーザーごとに値を 1 ずつ増やしています。実際には、集計可能な値を調整することで、信号雑音比を改善できます。比率。

掛金の予算

Private Aggregation API への各呼び出しは、コントリビューションと呼ばれます。データを保護するにはユーザーのプライバシー、制限されています。

すべての集計キーの集計可能な値を合計する場合は、資金提供の予算より低くする必要があります予算の範囲はワークレットごとに設定される origin、1 日あたり Protected Audience API と共有ストレージのワークレットは別個のものです。ローリングウィンドウが使用されます。新しい予算を超過すると、集計可能レポートは予算を超過し、作成されます。

寄付予算はパラメータ L₁ で表され、バックストップは 2²⁰、1 日あたり 10 分あたり 2¹⁶（65,536）に設定

（1,048,576）。詳しくは、説明パラメータの詳細をご覧ください。

寄与の予算の値は任意ですが、ノイズはその値にスケーリングされます。この予算を使用して、サマリー値の信号対雑音比を最大化できます（詳しくは、ノイズとスケーリングのセクションをご覧ください）。

寄付の予算について詳しくは、 explainer。寄付予算をご覧ください。

集計可能レポート

ユーザーが Private Aggregation API を呼び出すと、ブラウザによって後で集計サービスによって処理される集計可能レポートサマリーの生成に時間をかけるレポートをご覧ください。「集計可能レポートは JSON 形式で、 {aggregation key, aggregatable value} のペアです。集計可能レポートは、ランダムに 1 時間の遅延を伴って送信されます。

コントリビューションは暗号化され、集計サービスの外部で読み取ることはできません。集計サービスはレポートを復号し、概要レポートを生成します。「ブラウザの暗号鍵と集計データの復号鍵のサービスは、鍵管理サービスとして機能するコーディネーターによって発行されます。コーディネーターは、検証するサービスイメージのバイナリハッシュのリストを保持します。呼び出し元が復号鍵を受け取れることを確認します。

debug による集計可能レポートの例モードを有効にします。

  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
      "payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
    }
  ],
  "debug_key": "777",
  "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"

集計可能レポートは chrome://private-aggregation-internals ページ:

Private Aggregation API の内部ページのスクリーンショット

テスト目的で [Send Selected Reports] のボタンをクリックすると、サーバーにレポートが送信されます。

集計可能レポートを収集してバッチ処理する

ブラウザが集計可能レポートをワークレットの起点に送信する Private Aggregation API の呼び出しを含む path:

共有ストレージの場合: /.well-known/private-aggregation/report-shared-storage
Protected Audience の場合: /.well-known/private-aggregation/report-protected-audience

これらのエンドポイントでは、コレクタとして機能するサーバーを運用する必要があります。クライアントから送信された集計可能レポートを受信します。

サーバーはレポートをバッチ処理し、そのバッチを集計サービスに送信する。暗号化されていない状態で入手可能な情報に基づいてバッチを作成します。集計可能レポートのペイロード（shared_info フィールドなど）。次のことが理想的です。バッチごとに 100 件以上のレポートが含まれている必要があります。

毎日または毎週の単位でバッチ処理できます。この戦略は柔軟であり、また、予想される特定のイベントのバッチ処理戦略を変更できます。ボリュームの増加（例: インプレッション数が増加することが予想される日）バッチには、同じ API バージョン、レポート生成元、スケジュール設定できます。

集計サービス

このサービスは TEE で実行され、集計可能レポートを復号し、
ノイズを追加して、最終的な概要レポートを作成します。

集計サービス暗号化された集計可能レポートをコレクタから受信し、サマリーを生成するできます。

レポートペイロードを復号するために、集計サービスは復号鍵をフェッチします。示されます。高信頼実行環境（TEE）で実行される。これにより、データの整合性、データの機密性、コードの完全性お客様がサービスを所有、運営していても、 TEE で処理されているデータを可視化します

概要レポート

概要レポートノイズを付加して収集したデータを表示できます。こちらから概要レポートも作成できます。

概要レポートには、JSON 辞書形式の Key-Value ペアのセットが含まれます。各ペアに含まれるもの:

bucket: 2 進数の文字列としての集計キー。もし使用される集計キーは「123」、バケットは「1111011」です。
value: 特定の測定目標のサマリー値。ノイズが追加された、使用可能なすべての集計可能レポートです。

例:

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

ノイズとスケーリング

ユーザーのプライバシーを保護するため、集計サービスは概要レポートがリクエストされるたびに発生します。ノイズ値は、ラプラス確率からランダムに導き出される提供します。Google Cloud のノイズの追加方法を直接制御することはできません。ノイズの追加方法にノイズを除去できます。

ノイズ分布は、集計可能なすべての使用できます。したがって、集計可能値が高いほど、ノイズの影響が小さくなります。あります

たとえば、ノイズ分布の標準偏差が 100 であるとします。 0 を基準とします。収集された集計可能レポート値（または「集計可能値」）が 200 しかない場合、ノイズの標準偏差は集計された値の 50% を占めます集計可能値が 20,000 の場合ノイズの標準偏差は集計値の 0.5% にすぎないでしょう。したがって、 SN 比はかなり高くなります

したがって、集計可能な値にスケーリングファクタを乗算すると、ノイズを低減します。スケーリングファクタは、特定のイベントをどの程度スケーリングするかを集計可能値を指定します

スケーリングファクタを大きくして値をスケールアップすると、ノイズを軽減できます。ただし、この場合、すべてのバケットにわたるすべての貢献度の合計も発生します。寄付の予算の上限に早く到達します値をスケールダウンする小さいスケーリングファクタ定数を選択すると、相対ノイズは増加しますが、予算の上限に達するリスクを低減できます

適切なスケーリングファクタを計算するには、分担予算をすべてのキーにわたる集計可能な値の最大合計。

詳しくは、寄付予算のドキュメントをご覧ください。

対応してフィードバックを共有する

Private Aggregation API は現在検討中であり、今後変更される可能性があります。実現します。この API をお試しいただき、ご意見やご感想がございましたら、ぜひお聞かせください。

GitHub: explainer、質問の投稿や、ディスカッションできます。 * デベロッパーサポート: プライバシーサンドボックスデベロッパーサポートリポジトリをご覧ください。 * Shared Storage API に参加するグループ Protected Audience API グループをご覧ください。

Private Aggregation API の基礎

このドキュメントの対象者

主な用語

プライベート アグリゲーションのワークフロー

集計キー

集計可能な値

掛金の予算

集計可能レポート

集計可能レポートを収集してバッチ処理する

集計サービス

概要レポート

ノイズとスケーリング

対応してフィードバックを共有する

プライベートアグリゲーションのワークフロー