Toplanabilir Raporları Alma ve Depolama

Reklam teknolojileri ölçüm API'lerini (Attribution Reporting API veya Private Aggregation API) tetiklediğinde, şifrelenmiş raporlar Chrome tarayıcıdan / istemci tarafında reklam teknolojisinin raporlama uç noktasına gönderilir. Bu uç nokta, reklam teknolojisinin raporlama kaynağına sahip bir .well-known URL'sidir. Raporlama uç noktası, şifrelenmiş raporları toplamak için reklam teknolojisi tarafından barındırılır.

AgS Rapor Diyagramı

API başına uç noktalar şunlardır:

  • Private Aggregation

    • [reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage hatalarını ayıkla
    • Canlı [reporting-origin]/.well-known/private-aggregation/report-shared-storage veya /.well-known/private-aggregation/report-protected-audience

  • İlişkilendirme Raporları

    • [reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution dosyasını hata ayıklama
    • Canlı [reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution

Reklam teknolojisi uzmanları, raporları bir POST çağrısı üzerinden JSON biçiminde alır. Reklam teknolojileri, bu JSON raporlarını toplar ve daha sonra Toplama Hizmeti'nde kullanılan AVRO biçimine dönüştürür. AVRO raporları dönüştürüldükten sonra daha sonra toplu hale getirmek üzere reklam teknolojisinin bulut depolama alanında depolanır.

Reklam teknolojisi toplu işleme hazır olduğunda, raporların reklam teknolojisinin bulut depolama alanından alındığı toplama hizmeti aracılığıyla bir toplama işi isteği tetikler. Toplama Hizmeti, reklam teknolojisinin bulut depolama alanında barındırılır ve izin verilenler listesinde bir resim içermelidir.

Alınan raporlar şuna benzer:

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'u AVRO raporlarına dönüştürme

Toplu işleme sırasında, toplanabilir raporların AVRO biçiminde olması gerekir. AVRO raporu oluşturmak için rapor AVRO şemasına (AVSC) ihtiyacınız vardır.

Aggregation Service GitHub deposunda örnek JavaScript kodu bulunmaktadır.

Tüm raporlarınız için 1 AVRO dosyanız olabilir veya raporları birden fazla AVRO dosyasına bölebilirsiniz. AVRO boyutu sınırsızdır. Performans nedeniyle, AVRO dosyalarının sayısının Cloud örneğiniz için kullanılabilen CPU sayısı ile 1.000 arasında bir sayı olması önerilir.

Aşağıda, Toplanabilir raporlar için AVRO Şeması verilmiştir. Raporlar için farklı alanlar payload, key_id ve shared_info'dir.

  {
    "type": "record",
    "name": "AggregatableReport",
    "fields": [
      {
        "name": "payload",
        "type": "bytes"
      },
      {
        "name": "key_id",
        "type": "string"
      },
      {
        "name": "shared_info",
        "type": "string"
      }
    ]
  }
Parametre Tür Açıklama
payload Bayt Canlı/üretim raporları için yükün base64 olarak kodunun çözülmesi ve payload'ten bir bayt dizisine dönüştürülmesi gerekir.
debug_cleartext_payload Bayt Hata ayıklama raporları için yükün base64 kodunun çözülmesi ve debug_cleartext_payload ürününden bir bayt dizisine dönüştürülmesi gerekir.
key_id Dize Bu, raporda bulunan key_id dizesi olacaktır. key_id, benzer şekilde 128 bitlik evrensel olarak benzersiz bir tanımlayıcı olacaktır.
shared_info Dize Bu, report shared_info alanında bulunan değiştirilmemiş dize olacaktır.

Aşağıda örnek bir rapor JSON'u verilmiştir:

{ 
   "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\"}"
}

Çıkış Alanı AVRO

Toplama Hizmeti'ni kullanarak özet raporlar oluşturmak için reklam teknolojisinde, toplanabilir raporlar ve alan dosyası gerekir. Toplanabilir raporlar, raporlama kaynağında alınan ve AVRO biçimine dönüştürülen JSON raporlarıdır. Çıkış alanları, toplanabilir raporlarınızdan toplanacak ve özet raporlarına yazılacak önceden tanımlanmış anahtarları içerir. İlişkilendirme raporlarındaki bu anahtarlar ve özel toplamadaki anahtarlar hakkında daha fazla bilgi edinin. Çıkış alanı, alan paketini içerir ve paket değeri, paket anahtarınız olur.

Ayrıca alan dosyasının, aşağıdaki şema kullanılarak AVRO biçiminde olması gerekir:

  {
    "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."
      }
    ]
  }

Paket Anahtarı

Paket anahtarı, paket anahtarının on altılık bir bayt dizesi olmalıdır. Buna örnek olarak Ondalık bir değer olarak 1369 anahtarı gösterilebilir. Onaltılık değer olarak dönüştürüldükten sonra 559 olur. Ardından, AVRO çıkış alanına eklemek için 559'u bir bayt dizesine dönüştürmeniz gerekir.

AgS Paket Anahtarı Diyagramı

Toplu raporlar

Gizlilik bütçeleri ve gruplandırma hakkında daha fazla bilgi edinmek için gruplandırma stratejileri belgesine gidin. Ayrıca, birleştirilebilir bir raporun yalnızca belirli bir süre içinde gruplandırılabileceğini unutmayın. Bir raporun scheduled_report_time ile toplu çalıştırma tarihi (şu anda 90 gün) arasındaki MAX_REPORT_AGE değerini aşmaması gerekir.

Özet Raporlar

Toplu işlemden sonra Toplama Hizmeti, özet raporu AVRO biçiminde oluşturur. Özet raporu results.avsc şemasını kullanır.

Özet rapor, createJob isteğinde belirtilen output_data_bucket_name paketindeki output_data_blob_prefix içinde yer alır.

error_run'ın etkin olduğu Toplama Hizmeti grupları için iki rapor oluşturur. Özet raporu ve hata ayıklama özeti raporu. Hata ayıklama özeti raporu output_data_blob_prefix/debug klasöründe yer alır.

Oluşturulan hata ayıklama raporunda debug_results.avsc şeması kullanılır.

Hem özet hem de hata ayıklama raporu [output_data_blob_prefix]-1-of-1.avro olarak adlandırılır. exit_data_blob_prefix değeriniz summary/summary.avro ise rapor summary-1-of-1.avro adlı özet klasöründe bulunur.

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"]
          }
       }
    ]
  }

Dönüştürüldükten sonra özet raporunuz results.json örneğine benzer bir görünüme sahip olur. debug_run etkinleştirildiğinde hata ayıklama özeti raporu, debug_results.json örneğine benzer bir sonuç döndürür.

results.json (örnek)

Toplama Hizmeti'nden gelen AVRO raporları, paket anahtarına ve paket değerlerine ek gürültüyle birlikte özet / toplam değere sahip olduğunuzda benzer görünebilir.

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

error_results.json (örnek)

Toplama Hizmeti'nden gelen hata ayıklama AVRO raporları, paket anahtarlarınızı, unnoised_metric'yi (paket anahtarlarının gürültü içermeyen özeti) ve unnoised_metric'ye eklenen gürültüyü aldığınız aşağıdakine benzer görünmelidir.

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

Ek açıklamalarda in_reports ve / veya in_domain ifadeleri de bulunacaktır. Bu durum şu anlamlara gelir:

  • in_reports: Paket anahtarı, toplanabilir raporlarda mevcuttur
  • in_domain: Paket anahtarı, output_domain AVRO dosyasında bulunur.