接收並儲存報表 (&A)；儲存可匯總報表

廣告技術觸發成效評估 API (Attribution Reporting API 或 Private Aggregation API) 時，加密報表會從 Chrome 瀏覽器/用戶端傳送至廣告技術的回報端點，也就是含有廣告技術回報來源的 .well-known URL。回報端點由廣告技術代管，用於收集經過加密的報表。

AgS 報告圖表

以下是每個 API 的端點：

  • 私密匯總

    • 偵錯 [reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage
    • 直播 [reporting-origin]/.well-known/private-aggregation/report-shared-storage或 /.well-known/private-aggregation/report-protected-audience

  • 歸因報表

    • 偵錯 [reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution
    • 直播 [reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution

廣告技術會透過 POST 呼叫，以 JSON 格式接收報表。廣告技術會收集這些 JSON 報表，然後轉換為匯總服務中使用的 AVRO 格式。轉換完成後，AVRO 報表會儲存在廣告技術的雲端儲存空間，以利日後匯出。

廣告技術準備好執行批次作業後，就會透過匯總服務觸發匯總工作要求，從廣告技術的雲端儲存空間擷取報表。匯總服務託管於廣告技術的雲端儲存空間，且應具備已加入許可清單的映像檔。

收到的報表如下所示：

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 報表

進行批次處理時，可匯總報表需採用 AVRO 格式。如要建立 AVRO 報表，您需要報表 AVRO 結構定義 (AVSC)。

您可以在匯總服務 GitHub 存放區中找到 JavaScript 程式碼範例。

您可以為所有報表建立 1 個 AVRO 檔案，或是將報表拆分成多個 AVRO 檔案。AVRO 大小沒有限制。基於效能考量，建議您將 AVRO 檔案數量保持在 Cloud 執行個體可用的 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 位元組 酬載必須經過 Base64 解碼，並轉換成 payload 的位元組陣列，才能用於即時報表 / 實際工作環境報表。
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 報表，並轉換為 AVRO 格式。輸出網域包含預先宣告的鍵，這類鍵會從可匯總報表收集，並寫入摘要報表。進一步瞭解這些歸因報表中的鍵和私密匯總中的鍵。輸出網域會包含欄位值區，值區值會是您的值區金鑰。

網域檔案也必須採用 AVRO 格式，並使用以下結構定義：

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

值區金鑰

值區金鑰應為值區金鑰的十六進位位元組字串。舉例來說，如果在 Decimal 中鍵入 1369，轉換為 16 進制後，就會是 559。接著，您需要將 559 轉換為位元組字串，再加進輸出網域 AVRO

AgS 值區索引鍵圖表

批次報表

如要進一步瞭解隱私權預算和批次處理，請參閱批次處理策略文件。此外，請注意，可匯總的報表只能在特定時間範圍內批次處理。報表的日期範圍不得超過 scheduled_report_time 和批次執行日期之間的 MAX_REPORT_AGE (目前為 90 天)。

摘要報表

完成批次處理後，匯總服務會以 AVRO 格式建立摘要報表。摘要報表使用 results.avsc 結構定義。

摘要報表位於 createJob 要求中所述的 output_data_bucket_name 值區的 output_data_blob_prefix 中。

對於已啟用 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

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

debug_results.avsc

  {
  "type": "record",
  "name": "DebugAggregatedFact",
  "fields": [
      {
        "name": "bucket",
        "type": "bytes",
        "doc": "Histogram bucket used in aggregation. 128-bit integer encoded as a 16-byte big-endian bytestring. Leading 0-bits will be left out."
      },
      {
        "name": "unnoised_metric",
        "type": "long",
        "doc": "Unnoised metric associated with 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 的內容。

result.json (範例)

匯總服務產生的 AVRO 報表可能會類似，因為您會看到值區鍵和摘要/匯總值，以及值區值的雜訊。

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

debug_results.json (範例)

來自匯總服務的偵錯 AVRO 報表應如下所示：您接收值區金鑰 unnoised_metric (不含雜訊的值區金鑰摘要) 以及加入 unnoised_metric 的雜訊。

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

註解也會包含 in_reports 和/或 in_domain，代表以下意思：

  • in_reports：可匯總報表中提供的桶鍵
  • in_domain：值區鍵可在 output_domain AVRO 檔案中使用