接收及儲存可匯總報表

本指南說明如何將經過加密的評估報表傳送給廣告技術供應商。Chrome 瀏覽器和用戶端會將這些報表傳送至指定的回報端點，廣告技術平台會在該端點接收及儲存可匯總報表。這些端點位於供應商報表來源中的 .well-known 網址，由平台代管，讓廣告技術供應商使用 Attribution Reporting API 或 Private Aggregation API 存取這些端點。

在 Privacy Sandbox 匯總服務中接收及儲存可匯總的報表。
圖 1.匯總服務：可匯總報表處理程序。

下列步驟詳細說明匯總服務接收及儲存可匯總報表的程序：

  1. 觸發後，瀏覽器會傳送可匯總的報表，其中包含跨網站和轉換資料的詳細資料。
  2. 瀏覽器會將經過加密的報表傳送至廣告技術報表網域中的 .well-known 網址。
  3. 系統會將批次報表轉送至匯總服務進行處理。
  4. 匯總服務會統計並匯總報表。
  5. 匯總服務會在匯總資料中加入雜訊，以強化使用者隱私。
  6. 系統會將報表提供給廣告技術公司，以利分析和評估。

下表說明 Private Aggregation API 和 Attribution Reporting API 的偵錯和實際端點：

API 端點 說明
私密匯總 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 格式，並將報表儲存在雲端儲存空間中。在批次處理完成後，系統會將 Avro 報表傳送至匯總服務進行匯總。

當一批 Avro 報表已準備好供處理時，廣告技術平台會向匯總服務觸發匯總工作要求。這項服務會在廣告技術平台的雲端環境中代管，並從相同的儲存位置擷取所需的 Avro 報表。基於安全考量，匯集服務必須設定為使用核准的容器映像檔。如要查看可用的容器映像檔，請參閱 Privacy Sandbox/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 檔案。

您可以在 privacysandbox/aggregation-service GitHub 存放區的「Collecting and Batching Aggregatable Reports」頁面「Collect, transform and batch reports」部分，找到 JavaScript 程式碼範例。

您可以彈性地將所有報表儲存在單一 AVRO 檔案中，或分散儲存在多個檔案中。雖然 AVRO 檔案沒有大小限制，但通常在檔案數量介於雲端執行個體的 CPU 數量至 1000 之間時，才能達到最佳效能。

以下程式碼範例顯示可匯總報表的 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\"}"
}

網域檔案規格

使用匯總服務產生摘要報表時，您必須提供可匯總的報表 (已轉換為 Avro 的 JSON 報表) 和相關聯的網域檔案。系統會從可匯總報表中擷取先前宣告的鍵，並將這些鍵納入輸出網域中的摘要報表。如要進一步瞭解這些重要的匯總鍵，請參閱「瞭解歸因報表的匯總鍵」和「私人匯總 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."
      }
    ]
  }

值區索引鍵

輸出網域中的值區鍵必須以十六進位字節字串表示。

例如：

如果值區索引鍵是十進位值 1369：

  1. 將 1369 轉換為十六進位值：559

  2. 將十六進位字串「559」轉換為位元組字串。

這個值區鍵的位元組字串表示法應包含在輸出網域 Avro 結構定義中。

重要事項：

  • 資料類型：Avro 結構定義中的桶鍵應定義為位元組類型，以便支援十六進位位元組字串表示法。

  • 轉換：您可以使用 Python 或 Java 實作從十進制轉換為十六進制，然後再轉換為位元組字串。

這種做法可確保桶值鍵的格式正確無誤，且與輸出網域的 Avro 結構定義中預期的資料類型相容。

值區鍵應為十六進位字節字串。舉例來說，假設一個位元組字串的十進制值為 1369。轉換為 16 進位格式後，這個值會是 559，可加進 Avro 輸出網域。
圖 2.此圖說明如何將值集索引鍵轉換為十六進制，然後轉換為位元組字串表示法，最後用於填入輸出網域 AVRO 結構定義。

批次報表

如要進一步瞭解隱私預算和批次處理策略，請參閱批次處理策略說明文件。請注意，可匯總的報表在 scheduled_report_time 和批次執行日期之間，有 MAX_REPORT_AGE 限制 (目前為 90 天)。

摘要報表

匯總後，匯總服務會使用 results.avsc 結構定義，以 Avro 格式建立摘要報表。

工作完成後，摘要報表會儲存在 output_data_bucket_name 值區內的 output_data_blob_prefix 中，如 createJob 要求所述。

對於已啟用 debug_run 的匯總服務批次，匯總服務會建立兩份報表：摘要報表和偵錯摘要報表。偵錯摘要報表位於 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：資料匯總的專屬 ID (例如「\u0005Y」)。

  • 指標：對應值區的加總值。這個值通常會加入雜訊，以提升隱私性。

    例如：

  {
    "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 檔案中可用的 bucket 鍵