集計可能レポートを受信して保存する

このガイドでは、暗号化された測定レポートが広告テクノロジー プロバイダに配信される仕組みについて説明します。Chrome ブラウザとクライアントは、これらのレポートを指定されたレポート エンドポイントに送信します。広告テクノロジー プラットフォームは、集計可能レポートを受信して保存します。これらのエンドポイントは、プロバイダのレポート送信元内の .well-known URL にあり、プラットフォームによってホストされます。これにより、広告テクノロジー プロバイダは Attribution Reporting API または Private Aggregation API を使用してエンドポイントにアクセスできます。

プライバシー サンドボックス集計サービス内で集計可能レポートを受け取って保存するプロセス。
図 1. 集計サービス: 集計可能レポートの処理。

次の手順では、集計可能なレポートを受信して保存する Aggregation Service のプロセスについて説明します。

  1. トリガーされると、ブラウザは、クロスサイト データとコンバージョン データの両方に関する詳細を含む集計レポートを送信します。
  2. ブラウザは、暗号化されたレポートを広告テクノロジー レポート ドメイン内の .well-known URL に配信します。
  3. システムは、レポートのバッチを集計サービスに転送して処理します。
  4. 集計サービスは、レポートを統計的に要約します。
  5. 集計サービスは、要約されたデータにノイズを追加してユーザーのプライバシーを強化します。
  6. 広告テクノロジー企業は、分析と測定の目的でレポートを利用できます。

次の表に、Private Aggregation API と Attribution Reporting API のデバッグ エンドポイントとライブエンドポイントを示します。

API エンドポイント 説明
Private Aggregation API
デバッグ エンドポイント:
[reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage
ライブ エンドポイント:
  • [reporting-origin]/.well-known/private-aggregation/report-shared-storage
  • [reporting-origin]/.well-known/private-aggregation/report-protected-audience
デバッグ エンドポイント:
Private Aggregation API の開発とテストに使用します。
ライブ エンドポイント:
本番環境で測定レポートを受信して処理する
Attribution Reporting API
デバッグ エンドポイント:
[reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution
ライブ エンドポイント:
[reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution
デバッグ エンドポイント:
Attribution Reporting API の開発とテストに使用します。
ライブ エンドポイント:
  • 集計アトリビューション レポートの本番環境エンドポイント。
  • 測定のために、本番環境で集計アトリビューション レポートを受信して処理します。

レポート送信元は、POST 呼び出しを介して JSON レポートを受信します。その後、これらのレポートは Avro 形式に変換され、Cloud Storage に保存されます。バッチ処理後、システムは Avro レポートを集計サービスに送信して要約します。

広告テクノロジー プラットフォームは、Avro レポートのバッチが処理の準備ができていると判断されると、集計サービスへの集計ジョブ リクエストをトリガーします。このサービスは、広告テクノロジー プラットフォームのクラウド環境内でホストされ、同じストレージ ロケーションから必要な Avro レポートを取得します。セキュリティ上の理由から、承認済みのコンテナ イメージを使用するように Aggregation Service を構成する必要があります。使用可能なコンテナ イメージについては、プライバシー サンドボックス/集計サービスの GitHub リポジトリをご覧ください。

各 API から返されるレポートの代表的な例を次に示します。

  • Private Aggregation API レポートの例:
  {
    "aggregation_coordinator_origin": "https://publickeyservice.msmt.aws.privacysandboxservices.com",
    "aggregation_service_payloads": [ {
        "key_id": "1a2baa3f-5d48-46cf-91f0-772633c12640",
        "payload": "8Cjr1s3FVkCYkjzBvyzJn14yardVjd5N4vLCA69LQAPbIkJ0B58hAqUGBCNXpvTjW9ZpIoZbCSiUOsUDuoA/S+tqVolLMkame6sWC07cfUmZcVsbU+La3pzTMtCgdtNc8MIWgD3C63CMw7rWroRlechewVUajvAYVK/0HJq0YyGrTiFZZm36zi0jjyHLAXKV8p1Lvy1d0o/wnBxC5oVo5BV6LPkxqQEcoYS2GyixUuht6wD0RzuH+BxxuH6vY/ynp2xDrnwftjvqwDUAxUWLFTunthM6BXZVxlrvOBim1h2dvPqWSyKZ5gafo+MgW9EM4SraavNM3XzZSCjdtAfSMJMrynSu2j0opyAq+9e1jq1xeYN00yZrJ0Y/GTI45IGjgCnVmvmuoI9ucW2SnXP31CQBwHqk4gtUgMsYGFSUYfhtnAQ/8TSbaXyS2LX+cQW87LqkvIraWw6o37O24VFBreFoFFXpu3IUeCZfji+Sr4/ykfZuHeMzQbBavyNnHKzPZlbLSXMiucx4/vWzYyOzHeIlbtupXVvbi40V2PieDShaSbjI266kGgFkeCk6z51AaAGebDPtRT1lhBpcoQ6JdF0Yp5VWSnyFARKFtCZ1aEBrlUlrEHLUQY/pFtmDxJQiicRz1YPjR8jRr3C7hlRhWwov0dMocqnMz5209hHGVZWSsaGc9kWjtxREW2ULXfoIwOGbX+WZsyFW2RhXksQPJ5fhyNc4ROkAzUthLb68gC5e0yZHvmLIAU4hcWe0UanJv+jRljn8PAPaJHKFUxQNJyBA7mTbn5mkpycxGrX6T3ZYdPHqvckqt9llJZWjr8NneizzZFRuJk423BDs38fXkvcTAsAckd2Zu0u2KC45WR93sN2/CWrqB7/QU9BsgNdonl/ehAWhU1LbcRRvBTcR9+0wL7vRL7cv5LG3+gRYRKsWI6U2nDSWp0cNpo9+HU0JNiifa5X0cguihqU2bSk6ABozgRtCZ7m+7eqWXMLSzBdmc1CPUoQppo6Wmf6ujdNqI6v2S6pDH781lph8Z2v7ZpxGdhVVPEL51cVn"
    } ],
    "debug_key": "1234",
    "shared_info": "{\"api\":\"shared-storage\",\"report_id\":\"05e3b948-cb8d-4404-be29-bfeac7ad9710\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1707784729\",\"version\":\"0.1\"}"
  }
  • Attribution Reporting API レポートの例
  {
    "aggregation_coordinator_origin": "https://publickeyservice.msmt.aws.privacysandboxservices.com",
    "aggregation_service_payloads": [ {
        "key_id": "2dee0f3f-2aee-4a4a-8238-9154ed3d6f72",
        "payload": "pHvTHhcxvNKaCmnLpvYQsXlJpiNRuFO5Zj1QqUlqgWPOfuoHLfiXiFjmpvY8a53/OYnS4bKwHwJReFcofldsu8E9BzTTJ3CEk+B7vbEjnDPaljhpIBMTuQXy3QHGK4slWR/yNZVm2uXRWR/DVVzXziBoTDjN7qaPstRoLKUUMdfY2u8oq4tnLY00Y+NDZttZ4wJvC7hPmvY3lqHjdl14JPD2ytZZ4NViYzno3WKdH/oZc0jhGK4zI38lAM0qpahF/B9yb4zOu7IRIjQpNx73P8naDyddxLldoVlW/qHpO04FguWymscvI/8i6NwUR6Kj8seRlWS0iIUhETt/ai3lilKUHUb+uz0YG2kxjoXq7Ldk+MP56nNl67ZRNi2YZ7bOGI/okYWoT/wt2uWPe/5xAEMmadxl0hQQrG7YXHRSD8rDnaVPXo+AKIxdg727yJeB1ZENZvovl/kIevdRAmdBe2h1U3J6Uz6psly/46fvjgkj5QD+kO2uaYirzvmwS19luJsN/Qvh/R3ZO4qlJIQI0nDJPWwUJ4ODpyVmj4a0xQp3t2ESEnf4EmY7+khn3xpF5+MwEWKES2ZeDf7SHalR99pvZA8G3Fr8M0PWFmT00cmKCBwpQgZyd3Eay70UlqdkbFEedxiCVWKNNOUz41m5KG/7K3aR+dYx57l57Wct4gOFQg3jiUEBJWrFIVCXf12BT5iz5rBQh1N1CUt2oCOhYL/sPuBl6OV5GWHSIj8FUdpoDolqKXWINXfE88MUijE2ghNRpJN25BXIErUQtO9wFQv7zotC6d2BIaF0x8AkKg/7yzBQRySX/FZP3H3lMkpOz9rQMV8DjZ2lz7nV4k6CFo8qhT6cpYJD7GpYl81xJbglNqcJt5Pe5YUHrdBMyAFsTh3yoJvYnhQib/0xVN/a93lbYccxsd0yi375n4Xz0i1HUoe2ps+WlU8XysAUA1agG936eshaY1anTtbJbrcoaH+BNSacKiq4saprgUGl4eDjaR/uBhvUnO52WkmAGon8De3EFMZ/kwpPBNSXi7/MIAMjotsSKBc19bfg"
    } ],
    "shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://privacy-sandbox-demos-shop.dev\",\"report_id\":\"5b052748-f5fb-4f14-b291-de03484ed59e\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1707786751\",\"source_registration_time\":\"0\",\"version\":\"0.1\"}",
    "source_debug_key": "123456789",
    "trigger_debug_key": "123456789"
  }

JSON レポートを Avro レポートに変換する

集計可能なレポートは、バッチ処理のために Apache Avro データシリアル化形式である必要があります。Avro レポートを作成するには、AVSC スキーマを使用する必要があります。AVSC スキーマ ファイルは、Avro レコードの構造とデータ型を定義します。AVSC スキーマの例については、この avrodoc/schemata GitHub リポジトリの example.avsc ファイルを参照してください。

JavaScript コードのサンプルは、privacysandbox/aggregation-service GitHub リポジトリの 集計可能なレポートの収集とバッチ処理ページの [レポートの収集、変換、バッチ処理] セクションで確認できます。

すべてのレポートを 1 つの AVRO ファイルに保存することも、複数のファイルに分散することもできます。AVRO ファイルにはサイズの上限はありませんが、通常、ファイル数がクラウド インスタンスの CPU 数から 1, 000 までの範囲にあると、最適なパフォーマンスが得られます。

次のコードサンプルは、集計可能なレポートの Avro スキーマを示しています。レポート フィールドには、payload、key_id、shared_info があります。

  {
    "type": "record",
    "name": "AggregatableReport",
    "fields": [
      {
        "name": "payload",
        "type": "bytes"
      },
      {
        "name": "key_id",
        "type": "string"
      },
      {
        "name": "shared_info",
        "type": "string"
      }
    ]
  }
パラメータ 型 説明
payload バイト payload は、ライブ レポートまたは本番環境レポートのいずれかに対して base64 でデコードし、バイト配列に変換する必要があります。
debug_cleartext_payload バイト デバッグ レポート用にペイロードを base64 でデコードし、debug_cleartext_payload からバイト配列に変換する必要があります。
key_id 文字列 これはレポートに表示される key_id 文字列です。key_id は 128 ビットのユニバーサルに一意の識別子です。
shared_info 文字列 これは、レポートの shared_info フィールドで見つかった、改ざんされていない文字列です。

JSON レポートの例を次に示します。

{
   "aggregation_coordinator_identifier": "aws-cloud",
   "aggregation_service_payloads": [{
      "debug_cleartext_payload": "omRkYXhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAFWW1vcGVyYX",
      "key_id": "3c6e2850-edf6-4886-eb70-eb3f2a7a7596",
      "payload": "oapYz92Mb1yam9YQ2AnK8dduTt2RwFUSApGcKqXnG1q+aGXfJ5DGpSxMj0NxdZgp7Cq"
   }],
   "debug_key": "1234",
   "shared_info":
"{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"b029b922-93e9-4d66-a8c6-8cdeec762aed\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1719251997\",\"version\":\"0.1\"}"
}

ドメイン ファイルの仕様

Aggregation Service で概要レポートを生成するには、集計可能なレポート（JSON レポートを Avro に変換したもの）と、関連するドメイン ファイルが必要です。システムは、集計可能レポートから事前宣言されたキーを抽出し、出力ドメイン内の概要レポートに含めます。これらの重要な集計キーの詳細については、アトリビューション レポートの集計キーについてと、Private Aggregation API の基本の集計キーをご覧ください。出力ドメインには、バケットキー値を表す bucket フィールドも含まれます。

ドメイン ファイルは、次のスキーマを使用して Avro 形式にする必要があります。

  {
    "type": "record",
    "name": "AggregationBucket",
    "fields": [
      {
        "name": "bucket",
        "type": "bytes",
        "doc": "A single bucket that appears in the aggregation service output. It is an 128-bit integer value encoded as a 16-byte big-endian bytestring."
      }
    ]
  }

バケットキー

出力ドメイン内のバケットキーは、16 進バイト文字列として表す必要があります。

次に例を示します。

バケットキーが小数値 1369 の場合:

  1. 1369 を 16 進数に変換すると 559 になります。

  2. 16 進数の文字列「559」をバイト文字列に変換します。

バケットキーのこのバイト文字列表現は、出力ドメインの Avro スキーマに含める必要があります。

重要な考慮事項:

  • データ型: Avro スキーマ内のバケットキーは、16 進バイト文字列の表現に対応するようにバイト型として定義する必要があります。

  • 変換: 10 進数から 16 進数、バイト文字列への変換は、Python または Java を使用して実装できます。

このアプローチにより、バケットキーが適切にフォーマットされ、出力ドメインの Avro スキーマ内の想定されるデータ型と互換性があることが保証されます。

バケットキーは 16 進数バイト文字列にする必要があります。たとえば、1369 という小数値のバイト文字列について考えてみましょう。16 進数に変換すると、Avro 出力ドメインに追加する値は 559 になります。
図 2. この図は、バケットキーを 16 進数に変換し、バイト文字列表現に変換するプロセスを示しています。この変換は、最終的に出力ドメインの AVRO スキーマに入力するために使用されます。

バッチ レポート

プライバシー バジェットとバッチ処理戦略の詳細については、バッチ処理戦略のドキュメントをご覧ください。なお、集計可能なレポートには、scheduled_report_time とバッチ実行日の間に MAX_REPORT_AGE の上限（現在は 90 日）があります。

概要レポート

バッチ処理後、Aggregation Service は results.avsc スキーマを使用して Avro 形式の概要レポートを作成します。

ジョブの完了時に、概要レポートは createJob リクエストで指定されたように、output_data_bucket_name バケット内の output_data_blob_prefix に保存されます。

debug_run が有効になっている集計サービス バッチの場合、概要レポートとデバッグ概要レポートの 2 つのレポートが作成されます。デバッグ概要レポートは output_data_blob_prefix/debug フォルダにあります。デバッグ概要レポートは debug_results.avsc スキーマを使用します。

概要レポートとデバッグ レポートの両方の名前は [output_data_blob_prefix]-1-of-1.avro です。output_data_blob_prefix が summary/summary.avro の場合、レポートは summary-1-of-1.avro という名前の概要フォルダにあります。

results.avsc の例

results.avsc の Avro スキーマの例を次に示します。

{
  "type": "record",
  "name": "AggregatedFact",
  "fields": [
    {
      "name": "bucket",
      "type": "bytes",
      "doc": "Histogram bucket used in aggregation. It is an 128-bit integer value encoded as a 16-byte big-endian bytestring. Leading 0-bits are left out."
    },
    {
      "name": "metric",
      "type": "long",
      "doc": "The metric associated with the bucket"
    }
  ]
}

この Avro スキーマの例では、AggregatedFact という名前のレコードを定義しています。

debug_results.avsc の例

debug_results.avsc の Avro スキーマの例を次に示します。

  {
  "type": "record",
  "name": "DebugAggregatedFact", Output domains include summary reports that contain pre-declared keys extracted from your aggregatable reports.
  "fields": [
      {
        "name": "bucket",
        "type": "bytes",
        "doc": "This represents the histogram bucket used in aggregation. It's a 128-bit integer, encoded as a 16-byte big-endian bytestring, with leading zero bytes omitted.."
      },
      {
        "name": "unnoised_metric",
        "type": "long",
        "doc": "The raw metric for the bucket."
      },
      {
        "name": "noise",
        "type": "long",
        "doc": "The noise applied to the metric in the regular result."
      }
      {
        "name":"annotations",
        "type": {
          "type": "array",
          "items": {
            "type":"enum",
            "name":"bucket_tags",
            "symbols":["in_domain","in_reports"]
          }
       }
    ]
  }

変換すると、概要レポートは results.json の例のようになります。debug_run が有効になっている場合、デバッグ概要レポートの戻り値は debug_results.json の例と同様です。

Avro レポートの形式

集計サービスから受信した Avro レポートは通常、一貫した形式に準拠しています。Avro レポート形式には、次のフィールドが含まれています。

  • bucket: データ集計の一意の識別子（例: \u0005Y）。

  • metric: 対応するバケットの集計値。この値には、プライバシー保護のためにノイズが追加されていることがよくあります。

    次に例を示します。

  {
    "bucket": "\u0005Y",
    "metric": 26308
  }

debug_results.json の例

集計サービスからの Avro デバッグ レポートは、次の debug_results.json の例のようになります。これらのレポートには、バケットキー、unnoised_metric（ノイズ適用前のバケットキーの概要）、その指標に追加されたノイズが含まれます。

  {
    "bucket": "\u0005Y",
    "unnoised_metric": 128,
    "noise": -17948,
    "annotations": [
      "in_reports",
      "in_domain"
    ]
  }

アノテーションには次の値も含まれます。

  • in_reports: 集計可能なレポート内で使用できるバケットキー

  • in_domain: output_domain Avro ファイル内で使用可能なバケットキー