Получайте и храните агрегированные отчеты

В этом руководстве описывается, как зашифрованные отчеты об измерениях доставляются поставщикам рекламных технологий. Браузеры и клиенты Chrome отправляют эти отчеты в назначенные конечные точки отчетности, где платформа рекламных технологий получает и хранит агрегированные отчеты. Эти конечные точки, расположенные по .well-known URL-адресам в источнике отчетов поставщика, размещаются на платформе, что позволяет поставщикам рекламных технологий использовать API отчетов по атрибуции или API частного агрегирования для доступа к ним.

Процесс получения и хранения агрегированных отчетов в службе агрегирования Privacy Sandbox.
Рисунок 1. Служба агрегирования: обработка агрегированных отчетов.

Следующие шаги подробно описывают процесс службы агрегации для получения и хранения агрегированных отчетов:

  1. При срабатывании браузер отправляет сводные отчеты, содержащие подробную информацию как о межсайтовых данных, так и о конверсиях.
  2. Браузер доставляет зашифрованные отчеты на .well-known URL-адрес в домене отчетов о рекламных технологиях.
  3. Система передает пакеты отчетов в службу агрегирования для обработки.
  4. Служба агрегирования статистически обобщает отчеты.
  5. Служба агрегирования добавляет шум к обобщенным данным для повышения конфиденциальности пользователей.
  6. Система предоставляет отчеты рекламным компаниям для анализа и измерений.

В следующей таблице описаны отладочные и действующие конечные точки для API частного агрегирования и 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
Конечная точка отладки:
Для разработки и тестирования API частного агрегирования.
Живые конечные точки:
Получает и обрабатывает отчеты об измерениях в реальных условиях
API отчетов по атрибуции
Конечная точка отладки:
[reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution
Живая конечная точка:
[reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution
Конечная точка отладки:
Для разработки и тестирования API отчетов по атрибуции.
Живые конечные точки:
  • Рабочая конечная точка для сводных отчетов по атрибуции.
  • Получает и обрабатывает совокупные отчеты об атрибуции в реальных производственных средах для измерения.

Источники отчетов получают отчеты JSON через вызовы POST. Затем система преобразует эти отчеты в формат Avro и помещает их в облачное хранилище. После пакетной обработки система отправляет отчеты Avro в службу агрегации для обобщения.

Платформы рекламных технологий отправляют запрос на агрегирование в Службу агрегирования, когда пакет отчетов Avro считается готовым к обработке. Этот сервис, размещенный в облачной среде платформы рекламных технологий, извлекает необходимые отчеты Avro из одного и того же места хранения. В целях безопасности служба агрегации должна быть настроена на использование утвержденного образа контейнера. Доступные образы контейнеров можно найти в репозитории изолированной программной среды/службы агрегации GitHub .

Ниже показаны типичные примеры отчетов, возвращаемых каждым API:

  • Пример отчета 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\"}"
  }
  • Пример отчета 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 см. в файле example.avsc в этом репозитории avrodoc/schemata на GitHub .

Пример кода JavaScript можно найти в разделе «Сбор, преобразование и пакетная обработка отчетов» на странице «Сбор и пакетирование агрегированных отчетов», расположенной в репозитории Privacysandbox/aggregation-service GitHub.

У вас есть возможность хранить все отчеты в одном файле AVRO или распределять их по нескольким файлам. Хотя файлы AVRO не имеют ограничений по размеру, оптимальная производительность обычно достигается, когда количество файлов варьируется от количества процессоров в вашем облачном экземпляре до 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\"}"
}

Спецификация файла домена

Для создания сводных отчетов с помощью службы агрегирования требуются ваши агрегированные отчеты (отчеты JSON, преобразованные в Avro) и связанный файл домена. Система извлекает предварительно объявленные ключи из ваших агрегированных отчетов и включает их в сводные отчеты в выходных доменах. Подробную информацию об этих важнейших ключах агрегации можно найти в разделах «Понимание ключей агрегации для отчетов по атрибуции» и «Ключи агрегации» статьи «Основы 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. При преобразовании в шестнадцатеричный формат она равна 559 для добавления в выходной домен Avro.
Рисунок 2. Диаграмма иллюстрирует преобразование ключа сегмента в шестнадцатеричное, а затем в представление байтовой строки, которое в конечном итоге используется для заполнения схемы AVRO выходного домена.

Пакетные отчеты

Подробную информацию о бюджетах конфиденциальности и стратегиях пакетной обработки см. в документации по стратегиям пакетной обработки . Обратите внимание, что агрегированные отчеты имеют ограничение MAX_REPORT_AGE (в настоящее время 90 дней) между scheduled_report_time и датой выполнения пакета.

Сводные отчеты

После пакетной обработки служба агрегации создает сводный отчет в формате Avro, используя схему results.avsc .

После завершения задания сводный отчет сохраняется в поле output_data_blob_prefix в сегменте output_data_bucket_name , как указано в запросе createJob .

Для пакетов службы агрегации, в которых включен debug_run , создаются два отчета: сводный отчет и сводный отчет об отладке. Сводный отчет об отладке находится в папке output_data_blob_prefix/debug . В сводном отчете об отладке используется схема debug_results.avsc .

И сводный отчет, и отчет об отладке называются [output_data_blob_prefix]-1-of-1.avro . Если ваш output_data_blob_prefixsummary/summary.avro , отчет находится в папке сводки с именем summary-1-of-1.avro .

Пример results.avsc

Ниже приведен пример схемы Avro для results.avsc :

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

Ниже приведен пример схемы Avro для debug_results.avsc :

  {
  "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 включает следующие поля:

  • сегмент: уникальный идентификатор агрегирования данных (например, «\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.