Работа с сервисом агрегации на AWS

1. Предварительные условия

Для выполнения этой Codelab требуется несколько предварительных условий. Каждое требование помечается соответствующим образом, требуется ли оно для «Локального тестирования» или «Службы агрегации».

1.1. Загрузите инструмент локального тестирования (локальное тестирование)

Для локального тестирования потребуется загрузить инструмент локального тестирования. Инструмент будет генерировать сводные отчеты на основе незашифрованных отчетов об отладке.

Инструмент локального тестирования доступен для загрузки в архиве Lambda JAR на Github . Он должен называться LocalTestingTool_{version}.jar .

1.2. Убедитесь, что установлена ​​JAVA JRE (служба локального тестирования и агрегирования).

Откройте « Терминал » и используйте java --version , чтобы проверить, установлена ​​ли на вашем компьютере Java или openJDK.

Если он не установлен, его можно скачать и установить с сайта Java или сайта openJDK .

1.3. Скачать конвертер агрегированных отчетов (служба локального тестирования и агрегирования)

Вы можете скачать копию конвертера агрегированных отчетов из репозитория Privacy Sandbox Demos Github .

1.4. Включить API конфиденциальности рекламы (служба локального тестирования и агрегирования)

В браузере перейдите по адресу chrome://settings/adPrivacy и включите все API конфиденциальности рекламы.

Убедитесь, что сторонние файлы cookie включены.

В браузере перейдите на chrome://settings/cookies и выберите « Блокировать сторонние файлы cookie в режиме инкогнито ».

1,5. Регистрация через Интернет и Android (служба агрегирования)

Чтобы использовать API-интерфейсы Privacy Sandbox в производственной среде, убедитесь, что вы завершили регистрацию и аттестацию как для Chrome, так и для Android.

Для локального тестирования регистрацию можно отключить с помощью флага Chrome и переключателя CLI .

Чтобы использовать флаг Chrome для нашей демонстрации, перейдите по адресу chrome://flags/#privacy-sandbox-enrollment-overrides и обновите переопределение на своем сайте. Если вы будете использовать наш демонстрационный сайт, обновление не требуется.

1.6. Подключение службы агрегации (Служба агрегации)

Служба агрегации требует регистрации координаторов, чтобы иметь возможность использовать эту службу. Заполните форму регистрации службы агрегации, указав адрес своего сайта отчетности, идентификатор учетной записи AWS и другую информацию.

1.7. Облачный провайдер (Служба агрегации)

Служба агрегации требует использования доверенной среды выполнения, которая использует облачную среду. Служба агрегации поддерживается в Amazon Web Services (AWS) и Google Cloud (GCP). Эта Codelab будет охватывать только интеграцию с AWS.

AWS предоставляет доверенную среду выполнения под названием Nitro Enclaves. Убедитесь, что у вас есть учетная запись AWS, и следуйте инструкциям по установке и обновлению AWS CLI, чтобы настроить среду AWS CLI.

Если ваш интерфейс командной строки AWS новый, вы можете настроить его с помощью инструкций по настройке интерфейса командной строки .

1.7.1. Создать корзину AWS S3

Создайте корзину AWS S3 для хранения состояния Terraform и еще одну корзину S3 для хранения отчетов и сводных отчетов. Вы можете использовать предоставленную команду CLI. Замените поле в <> на правильные переменные.

aws s3api create-bucket --bucket <tf_bucket_name> --region us-east-1
aws s3api create-bucket --bucket <report_bucket_name> --region us-east-1

1.7.2. Создать ключ доступа пользователя

Создайте ключи доступа пользователей, используя руководство AWS . Это будет использоваться для вызова конечных точек API createJob и getJob , созданных на AWS.

1.7.3. Разрешения пользователей и групп AWS

Чтобы развернуть службу агрегации на AWS, вам необходимо предоставить определенные разрешения пользователю, используемому для развертывания службы. Для этой лаборатории кода убедитесь, что у пользователя есть доступ администратора, чтобы обеспечить полные разрешения при развертывании.

1.8. Terraform (Служба агрегации)

Эта Codelab использует Terraform для развертывания службы агрегации. Убедитесь, что двоичный файл Terraform установлен в вашей локальной среде.

Загрузите двоичный файл Terraform в свою локальную среду.

После загрузки двоичного файла Terraform извлеките файл и переместите двоичный файл Terraform в /usr/local/bin .

cp <directory>/terraform /usr/local/bin

Убедитесь, что Terraform доступен в пути к классам.

terraform -v

1.9. Почтальон (для службы агрегации AWS)

В этой Codelab используйте Postman для управления запросами.

Создайте рабочую область, перейдя к верхнему элементу навигации « Рабочие области » и выберите « Создать рабочую область ».

Выберите « Пустое рабочее пространство », нажмите «Далее» и назовите его « Песочница конфиденциальности ». Выберите « Личный » и нажмите « Создать ».

Загрузите предварительно настроенную конфигурацию JSON рабочей области и файлы глобальной среды .

Импортируйте файлы JSON в « Мое рабочее пространство » с помощью кнопки « Импорт ».

Это создаст для вас коллекцию Privacy Sandbox вместе с HTTP-запросами createJob и getJob .

Обновите «Ключ доступа» и «Секретный ключ» AWS с помощью « Быстрого просмотра среды ».

Нажмите « Изменить » и обновите «Текущее значение» для « access_key » и « secret_key ». Обратите внимание, что frontend_api_id будет указан в разделе 3.1.4 этого документа. И мы советуем использовать регион us-east-1. Однако если вы хотите выполнить развертывание в другом регионе, обязательно скопируйте выпущенный AMI в свою учетную запись или выполните самостоятельную сборку с использованием предоставленных сценариев .

2. Локальное тестирование Codelab

Вы можете использовать локальный инструмент тестирования на своем компьютере для выполнения агрегирования и создания сводных отчетов с использованием незашифрованных отчетов об отладке.

Шаги кодовой лаборатории

Шаг 2.1. Отчет по триггеру : активируйте отчеты частного агрегирования, чтобы иметь возможность собрать отчет.

Шаг 2.2. Создать сводный отчет об отладке . Преобразуйте собранный отчет JSON в отчет в формате AVRO.
Этот шаг будет аналогичен тому, когда специалисты по рекламе собирают отчеты из конечных точек отчетов API и преобразуют отчеты JSON в отчеты в формате AVRO.

Шаг 2.3. Анализ ключа сегмента из отчета об отладке . Ключи сегмента разработаны специалистами по рекламе. В этой кодовой лаборатории, поскольку сегменты предопределены, извлеките ключи сегментов, как указано.

Шаг 2.4. Создайте выходной домен AVRO . После получения ключей сегмента создайте файл AVRO выходного домена.

Шаг 2.5. Создавайте сводные отчеты с помощью инструмента локального тестирования . Используйте инструмент локального тестирования, чтобы иметь возможность создавать сводные отчеты в локальной среде.

Шаг 2.6. Просмотрите сводный отчет . Просмотрите сводный отчет, созданный с помощью инструмента локального тестирования.

2.1. Триггерный отчет

Перейдите на демонстрационный сайт тестовой среды конфиденциальности . Это запускает частный сводный отчет. Вы можете просмотреть отчет по адресу chrome://private-aggregation-internals .

Если ваш отчет находится в статусе « Ожидание », вы можете выбрать его и нажать « Отправить выбранные отчеты ».

2.2. Создать сводный отчет об отладке

В chrome://private-aggregation-internals скопируйте « Тело отчета », полученное в конечной точке [reporting-origin]/.well-known/private-aggregation/report-shared-storage .

Убедитесь, что в « Тело отчета » aggregation_coordinator_origin содержит https://publickeyservice.msmt.aws.privacysandboxservices.com что означает, что отчет является агрегируемым отчетом AWS.

Поместите JSON « Тело отчета » в файл JSON. В этом примере вы можете использовать vim. Но вы можете использовать любой текстовый редактор, какой захотите.

vim report.json

Вставьте отчет в report.json и сохраните файл.

Получив это, перейдите в папку отчета и используйте aggregatable_report_converter.jar , чтобы создать сводный отчет отладки. В результате в вашем текущем каталоге будет создан сводный отчет с именем report.avro .

java -jar aggregatable_report_converter.jar \
 --request_type convertToAvro \
 --input_file report.json \
 --debug

2.3. Анализ ключа сегмента из отчета об отладке

Службе агрегации требуется два файла при пакетной обработке. Агрегированный отчет и выходной файл домена. Выходной файл домена содержит ключи, которые вы хотите получить из агрегированных отчетов. Чтобы создать файл output_domain.avro , вам потребуются ключи сегмента, которые можно получить из отчетов.

Ключи сегментов разрабатываются вызывающей стороной API, а демо-версия содержит предварительно созданные примеры ключей сегментов. Поскольку в демонстрационной версии включен режим отладки для частного агрегирования, вы можете проанализировать полезную нагрузку открытого текста отладки из « Тела отчета », чтобы получить ключ сегмента. Однако в этом случае демонстрационная версия изолированной программной среды конфиденциальности сайта создает ключи сегмента. Поскольку частное агрегирование для этого сайта находится в режиме отладки, вы можете использовать debug_cleartext_payload из « Тела отчета », чтобы получить ключ сегмента.

Скопируйте debug_cleartext_payload из тела отчета.

Откройте декодер полезных данных Debug для инструмента Private Aggregation , вставьте debug_cleartext_payload в поле « INPUT » и нажмите « Decode ».

Страница возвращает десятичное значение ключа сегмента. Ниже приведен образец ключа ведра.

2.4. Создайте выходной домен AVRO

Теперь, когда у нас есть ключ сегмента, скопируйте десятичное значение ключа сегмента. Перейдите к созданию output_domain.avro , используя ключ ведра. Убедитесь, что вы заменили с ключом от ведра, который вы нашли.

java -jar aggregatable_report_converter.jar \
 --request_type createDomainAvro \
 --bucket_key <bucket key>

Скрипт создает файл output_domain.avro в вашей текущей папке.

2.5. Создание сводных отчетов с помощью инструмента локального тестирования.

Мы будем использовать LocalTestingTool_{version}.jar , загруженный в разделе 1.1, для создания сводных отчетов. Используйте следующую команду. Вам следует заменить LocalTestingTool_{version}.jar версией, загруженной для LocalTestingTool.

Запустите следующую команду, чтобы создать сводный отчет в вашей локальной среде разработки:

java -jar LocalTestingTool_{version}.jar \
--input_data_avro_file report.avro \
--domain_avro_file output_domain.avro \
--output_directory .

После запуска команды вы должны увидеть что-то похожее на следующее изображение. После завершения создается отчет output.avro .

2.6. Просмотрите сводный отчет

Создаваемый сводный отчет имеет формат AVRO. Чтобы прочитать это, вам необходимо преобразовать это из AVRO в формат JSON. В идеале рекламные технологии должны конвертировать отчеты AVRO обратно в JSON.

В нашей Codelab мы будем использовать предоставленный инструмент aggregatable_report_converter.jar для преобразования отчета AVRO обратно в JSON.

java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file output.avro

Возвращается отчет, подобный следующему изображению. Вместе с отчетом в том же каталоге создается output.json .

Откройте файл JSON в любом редакторе по вашему выбору, чтобы просмотреть сводный отчет.

3. Развертывание службы агрегации

Чтобы развернуть службу агрегации, выполните следующие действия:

Шаг 3. Развертывание службы агрегации : разверните службу агрегации на AWS.
Шаг 3.1. Клонировать репозиторий службы агрегации
Шаг 3.2. Загрузите готовые зависимости
Шаг 3.3. Создайте среду разработки
Шаг 3.4. Развертывание службы агрегации

3.1. Клонируйте репозиторий службы агрегации.

В локальной среде клонируйте репозиторий Github Aggregation Service .

git clone https://github.com/privacysandbox/aggregation-service.git

3.2. Загрузите готовые зависимости

После клонирования репозитория Службы агрегации перейдите в папку Terraform репозитория и в соответствующую облачную папку. Если ваш Cloud_provider — AWS, вы можете перейти к /terraform/aws

cd <repository_root>/terraform/aws

В /terraform/aws , выполните download_prebuilt_dependencies.sh .

bash download_prebuilt_dependencies.sh

3.3. Создайте среду разработки

Создайте среду разработки в /terraform/aws/environments . Создайте папку с именем dev .

mkdir dev

Скопируйте содержимое папки demo в папку dev .

cp -R demo/* dev

Перейдите в папку dev .

cd dev

Обновите файл main.tf и нажмите i , чтобы input для редактирования файла.

vim main.tf

Раскомментируйте код в красном поле, удалив # и обновив имена сегментов и ключей.

Для AWS main.tf :

Некомментированный код должен выглядеть следующим образом.

backend "s3" {
  bucket = "<tf_state_bucket_name>"
  key    = "<environment_name>.tfstate"
  region = "us-east-1"
}

После завершения обновления сохраните обновления и закройте редактор, нажав esc -> :wq! . Это сохранит обновления в main.tf

Затем переименуйте example.auto.tfvars в dev.auto.tfvars .

mv example.auto.tfvars dev.auto.tfvars

Обновите dev.auto.tfvars и нажмите i для input для редактирования файла.

vim dev.auto.tfvars

Обновите поля в красном поле на следующем изображении, указав правильные параметры AWS ARN, которые предоставляются во время регистрации службы агрегации, среды и электронного письма с уведомлением.

После завершения обновления нажмите esc -> :wq! . При этом файл dev.auto.tfvars будет сохранен, и он должен выглядеть примерно так, как показано на следующем изображении.

3.4. Развертывание службы агрегации

Чтобы развернуть службу агрегации, в той же папке /terraform/aws/environments/dev инициализируйте Terraform.

terraform init

Это должно вернуть что-то похожее на следующее изображение:

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

terraform plan

Ниже вы можете увидеть сводку « Плана ». Если это новое развертывание, вы должны увидеть количество ресурсов, которые будут добавлены: 0 для изменения и 0 для уничтожения.

Как только вы это сделаете, вы сможете приступить к применению Terraform.

terraform apply

Когда Terraform предложит подтвердить выполнение действий, введите « yes в это значение.

После завершения terraform apply возвращаются следующие конечные точки для createJob и getJob . Также возвращается frontend_api_id , который вам необходимо обновить в Postman в разделе 1.9 .

4. Создание входных данных службы агрегации

Перейдите к созданию отчетов AVRO для пакетной обработки в службе агрегирования.

Шаг 4. Создание входных данных службы агрегации . Создайте отчеты службы агрегации, которые группируются для службы агрегации.
Шаг 4.1. Триггерный отчет
Шаг 4.2. Собирайте агрегированные отчеты
Шаг 4.3. Преобразование отчетов в AVRO
Шаг 4.4. Создайте выходной домен AVRO

4.1. Триггерный отчет

Перейдите на демонстрационный сайт Privacy Sandbox . Это запускает частный сводный отчет. Вы можете просмотреть отчет по адресу chrome://private-aggregation-internals .

Если ваш отчет находится в статусе « Ожидание », вы можете выбрать его и нажать « Отправить выбранные отчеты ».

4.2. Собирайте агрегированные отчеты

Собирайте агрегированные отчеты с .well-known конечных точек соответствующего API.

• Частная агрегация
  [reporting-origin] /.well-known/private-aggregation/report-shared-storage
• Отчеты по атрибуции – сводный отчет
  [reporting-origin] /.well-known/attribution-reporting/report-aggregate-attribution

В этой Codelab вы будете выполнять сбор отчетов вручную. Ожидается, что на производстве специалисты по рекламе будут программно собирать и конвертировать отчеты.

В chrome://private-aggregation-internals скопируйте « Тело отчета », полученное в конечной точке [reporting-origin]/.well-known/private-aggregation/report-shared-storage .

Убедитесь, что в « Тело отчета » aggregation_coordinator_origin содержит https://publickeyservice.msmt.aws.privacysandboxservices.com что означает, что отчет является агрегируемым отчетом AWS.

Поместите JSON « Тело отчета » в файл JSON. В этом примере вы можете использовать vim. Но вы можете использовать любой текстовый редактор, какой захотите.

vim report.json

Вставьте отчет в report.json и сохраните файл.

4.3. Преобразование отчетов в AVRO

Отчеты, полученные от .well-known конечных точек, имеют формат JSON, и их необходимо преобразовать в формат отчетов AVRO. Получив отчет в формате JSON, перейдите в папку отчета и используйте aggregatable_report_converter.jar , чтобы создать сводный отчет отладки. В результате в вашем текущем каталоге будет создан сводный отчет с именем report.avro .

java -jar aggregatable_report_converter.jar \
 --request_type convertToAvro \
 --input_file report.json

4.4. Создайте выходной домен AVRO

Чтобы создать файл output_domain.avro , вам потребуются ключи сегмента, которые можно получить из отчетов.

Ключи от ведра разработаны рекламными технологиями. Однако в этом случае демо-версия Privacy Sandbox сайта создает ключи корзины. Поскольку частное агрегирование для этого сайта находится в режиме отладки, вы можете использовать debug_cleartext_payload из « Тела отчета », чтобы получить ключ сегмента.

Продолжайте и скопируйте debug_cleartext_payload из тела отчета.

Откройте goo.gle/ags-payload-decoder и вставьте свой debug_cleartext_payload в поле « ВВОД » и нажмите « Декодировать ».

Страница возвращает десятичное значение ключа сегмента. Ниже приведен образец ключа ведра.

Теперь, когда у нас есть ключ сегмента, создайте файл output_domain.avro . Убедитесь, что вы заменили с ключом от ведра, который вы нашли.

java -jar aggregatable_report_converter.jar \
 --request_type createDomainAvro \
 --bucket_key <bucket key>

Скрипт создает файл output_domain.avro в вашей текущей папке.

4.5. Перемещение отчетов в корзину AWS

После создания отчетов AVRO (из раздела 3.2.3) и выходного домена (из раздела 3.2.4) приступайте к перемещению отчетов и выходного домена в сегменты отчетов S3.

Если в вашей локальной среде настроен интерфейс командной строки AWS, используйте следующие команды, чтобы скопировать отчеты в соответствующую корзину S3 и папку отчетов.

aws s3 cp report.avro s3://<report_bucket_name>/<report_folder>/
aws s3 cp output_domain.avro s3://<report_bucket_name>/<output_domain_folder>/

5. Использование службы агрегации

Из terraform apply вам возвращаются create_job_endpoint , get_job_endpoint и frontend_api_id . Скопируйте frontend_api_id и поместите его в глобальную переменную postman frontend_api_id , которую вы настроили в разделе обязательных требований 1.9.

Шаг 5. Использование службы агрегации . Используйте API службы агрегации для создания сводных отчетов и просмотра сводных отчетов.
Шаг 5.1. Использование конечной точки createJob для пакетной обработки
Шаг 5.2. Использование конечной точки getJob для получения статуса пакета
Шаг 5.3. Просмотр сводного отчета

5.1. Использование конечной точки createJob для пакетной обработки

В Postman откройте коллекцию « Privacy Sandbox » и выберите « createJob ».

Выберите « Тело » и выберите « сырой », чтобы разместить полезные данные запроса.

Схема полезных данных createJob доступна на github и выглядит примерно так. Замените <> соответствующими полями.

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "input_data_bucket_name": "<bucket_name>",
  "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
  "output_data_bucket_name": "<bucket_name>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<bucket_name>",
    "attribution_report_to": "<reporting origin of report>",
    "reporting_site": "<domain of reporting origin(s) of report>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

Как только вы нажмете « Отправить », будет создано задание с job_request_id . Вы должны получить ответ HTTP 202, как только запрос будет принят службой агрегации. Другой возможный код возврата можно найти в кодах ответов HTTP.

5.2. Использование конечной точки getJob для получения статуса пакета

Чтобы проверить статус запроса на работу, вы можете использовать конечную точку getJob . Выберите « getJob » в коллекции « Privacy Sandbox ».

В « Params » обновите значение job_request_id на job_request_id , отправленное в запросе createJob .

Результат getJob должен возвращать статус вашего запроса задания со статусом HTTP 200. Запрос « Тело » содержит необходимую информацию, такую ​​​​как job_status , return_message и error_messages (если задание выполнено с ошибкой).

Поскольку сайт отчетов созданного демонстрационного отчета отличается от вашего сайта, подключенного к вашему идентификатору AWS, вы можете получить ответ с кодом возврата PRIVACY_BUDGET_AUTHORIZATION_ERROR . Это нормально, поскольку сайт источника отчетов не соответствует сайту отчетов, встроенному для идентификатора AWS.

{
    "job_status": "FINISHED",
    "request_received_at": "2023-12-07T22:50:58.830956Z",
    "request_updated_at": "2023-12-07T22:51:10.526326456Z",
    "job_request_id": "<job_request_id>",
    "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
    "input_data_bucket_name": "<input_bucket_name>",
    "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
    "output_data_bucket_name": "<output_bucket_name>",
    "postback_url": "",
    "result_info": {
        "return_code": "PRIVACY_BUDGET_AUTHORIZATION_ERROR",
        "return_message": "Aggregation job successfully processed",
        "error_summary": {
            "error_counts": [],
            "error_messages": []
        },
        "finished_at": "2023-12-07T22:51:10.517730898Z"
    },
    "job_parameters": {
        "debug_run": "true",
        "output_domain_bucket_name": "<output_domain_bucket_name>",
        "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
        "attribution_report_to": "https://privacy-sandbox-demos-dsp.dev",
        "reporting_site": "<domain of reporting origin(s) of report>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
    },
    "request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}

5.3. Просмотр сводного отчета

Как только вы получите сводный отчет в выходной сегмент S3, вы сможете загрузить его в свою локальную среду. Сводные отчеты имеют формат AVRO и могут быть преобразованы обратно в JSON. Вы можете использовать aggregatable_report_converter.jar для чтения отчета с помощью следующей команды.

java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file <summary_report_avro>

Это возвращает JSON агрегированных значений каждого ключа сегмента, который выглядит примерно так, как показано на следующем изображении.

Если ваш запрос createJob включает в debug_run значение true , вы можете получить сводный отчет в папке отладки, которая находится в output_data_blob_prefix . Отчет имеет формат AVRO и может быть преобразован с помощью предыдущей команды в JSON.

Отчет содержит ключ сегмента, нешумированную метрику и шум, который добавляется к нешумовой метрике для формирования сводного отчета. Отчет похож на следующее изображение.

Аннотации также содержат in_reports и in_domain что означает:

• in_reports — ключ сегмента доступен внутри агрегируемых отчетов.
• in_domain — ключ сегмента доступен внутри файла AVRO выходного_домена.

1. Предварительные условия

Для выполнения этой Codelab требуется несколько предварительных условий. Каждое требование помечается соответствующим образом, требуется ли оно для «Локального тестирования» или «Службы агрегации».

1.1. Загрузите инструмент локального тестирования (локальное тестирование)

Для локального тестирования потребуется загрузить инструмент локального тестирования. Инструмент будет генерировать сводные отчеты на основе незашифрованных отчетов об отладке.

Инструмент локального тестирования доступен для загрузки в архиве Lambda JAR на Github . Он должен называться LocalTestingTool_{version}.jar .

1.2. Убедитесь, что установлена ​​JAVA JRE (служба локального тестирования и агрегирования).

Откройте « Терминал » и используйте java --version , чтобы проверить, установлена ​​ли на вашем компьютере Java или openJDK.

Если он не установлен, его можно скачать и установить с сайта Java или сайта openJDK .

1.3. Скачать конвертер агрегированных отчетов (служба локального тестирования и агрегирования)

Вы можете скачать копию конвертера агрегированных отчетов из репозитория Privacy Sandbox Demos Github .

1.4. Включить API конфиденциальности рекламы (служба локального тестирования и агрегирования)

В браузере перейдите по адресу chrome://settings/adPrivacy и включите все API конфиденциальности рекламы.

Убедитесь, что сторонние файлы cookie включены.

В браузере перейдите на chrome://settings/cookies и выберите « Блокировать сторонние файлы cookie в режиме инкогнито ».

1,5. Регистрация через Интернет и Android (служба агрегирования)

Чтобы использовать API-интерфейсы Privacy Sandbox в производственной среде, убедитесь, что вы завершили регистрацию и аттестацию как для Chrome, так и для Android.

Для локального тестирования регистрацию можно отключить с помощью флага Chrome и переключателя CLI .

Чтобы использовать флаг Chrome для нашей демонстрации, перейдите по адресу chrome://flags/#privacy-sandbox-enrollment-overrides и обновите переопределение на своем сайте. Если вы будете использовать наш демонстрационный сайт, обновление не требуется.

1.6. Подключение службы агрегации (Служба агрегации)

Служба агрегации требует регистрации координаторов, чтобы иметь возможность использовать эту службу. Заполните форму регистрации службы агрегации, указав адрес своего сайта отчетности, идентификатор учетной записи AWS и другую информацию.

1.7. Облачный провайдер (Служба агрегации)

Служба агрегации требует использования доверенной среды выполнения, которая использует облачную среду. Служба агрегации поддерживается в Amazon Web Services (AWS) и Google Cloud (GCP). Эта Codelab будет охватывать только интеграцию с AWS.

AWS предоставляет доверенную среду выполнения под названием Nitro Enclaves. Убедитесь, что у вас есть учетная запись AWS, и следуйте инструкциям по установке и обновлению AWS CLI, чтобы настроить среду AWS CLI.

Если ваш интерфейс командной строки AWS новый, вы можете настроить его с помощью инструкций по настройке интерфейса командной строки .

1.7.1. Создать корзину AWS S3

Создайте корзину AWS S3 для хранения состояния Terraform и еще одну корзину S3 для хранения отчетов и сводных отчетов. Вы можете использовать предоставленную команду CLI. Замените поле в <> на правильные переменные.

aws s3api create-bucket --bucket <tf_bucket_name> --region us-east-1
aws s3api create-bucket --bucket <report_bucket_name> --region us-east-1

1.7.2. Создать ключ доступа пользователя

Создайте ключи доступа пользователей, используя руководство AWS . Это будет использоваться для вызова конечных точек API createJob и getJob , созданных на AWS.

1.7.3. Разрешения пользователей и групп AWS

Чтобы развернуть службу агрегации на AWS, вам необходимо предоставить определенные разрешения пользователю, используемому для развертывания службы. Для этой лаборатории кода убедитесь, что у пользователя есть доступ администратора, чтобы обеспечить полные разрешения при развертывании.

1.8. Terraform (Служба агрегации)

Эта Codelab использует Terraform для развертывания службы агрегации. Убедитесь, что двоичный файл Terraform установлен в вашей локальной среде.

Загрузите двоичный файл Terraform в свою локальную среду.

После загрузки двоичного файла Terraform извлеките файл и переместите двоичный файл Terraform в /usr/local/bin .

cp <directory>/terraform /usr/local/bin

Убедитесь, что Terraform доступен в пути к классам.

terraform -v

1.9. Почтальон (для службы агрегации AWS)

В этой Codelab используйте Postman для управления запросами.

Создайте рабочую область, перейдя к верхнему элементу навигации « Рабочие области » и выберите « Создать рабочую область ».

Выберите « Пустое рабочее пространство », нажмите «Далее» и назовите его « Песочница конфиденциальности ». Выберите « Личный » и нажмите « Создать ».

Загрузите предварительно настроенную конфигурацию JSON рабочей области и файлы глобальной среды .

Импортируйте файлы JSON в « Мое рабочее пространство » с помощью кнопки « Импорт ».

Это создаст для вас коллекцию Privacy Sandbox вместе с HTTP-запросами createJob и getJob .

Обновите «Ключ доступа» и «Секретный ключ» AWS с помощью « Быстрого просмотра среды ».

Нажмите « Изменить » и обновите «Текущее значение» для « access_key » и « secret_key ». Обратите внимание, что frontend_api_id будет указан в разделе 3.1.4 этого документа. И мы советуем использовать регион us-east-1. Однако если вы хотите выполнить развертывание в другом регионе, обязательно скопируйте выпущенный AMI в свою учетную запись или выполните самостоятельную сборку с использованием предоставленных сценариев .

2. Локальное тестирование Codelab

Вы можете использовать локальный инструмент тестирования на своем компьютере для выполнения агрегирования и создания сводных отчетов с использованием незашифрованных отчетов об отладке.

Шаги кодовой лаборатории

Шаг 2.1. Отчет по триггеру : активируйте отчеты частного агрегирования, чтобы иметь возможность собрать отчет.

Шаг 2.2. Создать сводный отчет об отладке . Преобразуйте собранный отчет JSON в отчет в формате AVRO.
Этот шаг будет аналогичен тому, когда специалисты по рекламе собирают отчеты из конечных точек отчетов API и преобразуют отчеты JSON в отчеты в формате AVRO.

Шаг 2.3. Анализ ключа сегмента из отчета об отладке . Ключи сегмента разработаны специалистами по рекламе. В этой кодовой лаборатории, поскольку сегменты предопределены, извлеките ключи сегментов, как указано.

Шаг 2.4. Создайте выходной домен AVRO . После получения ключей сегмента создайте файл AVRO выходного домена.

Шаг 2.5. Создавайте сводные отчеты с помощью инструмента локального тестирования . Используйте инструмент локального тестирования, чтобы иметь возможность создавать сводные отчеты в локальной среде.

Шаг 2.6. Просмотрите сводный отчет . Просмотрите сводный отчет, созданный с помощью инструмента локального тестирования.

2.1. Триггерный отчет

Перейдите на демонстрационный сайт тестовой среды конфиденциальности . Это запускает частный сводный отчет. Вы можете просмотреть отчет по адресу chrome://private-aggregation-internals .

Если ваш отчет находится в статусе « Ожидание », вы можете выбрать его и нажать « Отправить выбранные отчеты ».

2.2. Создать сводный отчет об отладке

В chrome://private-aggregation-internals скопируйте « Тело отчета », полученное в конечной точке [reporting-origin]/.well-known/private-aggregation/report-shared-storage .

Убедитесь, что в « Тело отчета » aggregation_coordinator_origin содержит https://publickeyservice.msmt.aws.privacysandboxservices.com что означает, что отчет является агрегируемым отчетом AWS.

Поместите JSON « Тело отчета » в файл JSON. В этом примере вы можете использовать vim. Но вы можете использовать любой текстовый редактор, какой захотите.

vim report.json

Вставьте отчет в report.json и сохраните файл.

Получив это, перейдите в папку отчета и используйте aggregatable_report_converter.jar , чтобы создать сводный отчет отладки. В результате в вашем текущем каталоге будет создан сводный отчет с именем report.avro .

java -jar aggregatable_report_converter.jar \
 --request_type convertToAvro \
 --input_file report.json \
 --debug

2.3. Анализ ключа сегмента из отчета об отладке

Службе агрегации требуется два файла при пакетной обработке. Агрегированный отчет и выходной файл домена. Выходной файл домена содержит ключи, которые вы хотите получить из агрегированных отчетов. Чтобы создать файл output_domain.avro , вам потребуются ключи сегмента, которые можно получить из отчетов.

Ключи сегментов разрабатываются вызывающей стороной API, а демо-версия содержит предварительно созданные примеры ключей сегментов. Поскольку в демонстрационной версии включен режим отладки для частного агрегирования, вы можете проанализировать полезную нагрузку открытого текста отладки из « Тела отчета », чтобы получить ключ сегмента. Однако в этом случае демонстрационная версия изолированной программной среды конфиденциальности сайта создает ключи сегмента. Поскольку частное агрегирование для этого сайта находится в режиме отладки, вы можете использовать debug_cleartext_payload из « Тела отчета », чтобы получить ключ сегмента.

Скопируйте debug_cleartext_payload из тела отчета.

Откройте декодер полезных данных Debug для инструмента Private Aggregation , вставьте debug_cleartext_payload в поле « INPUT » и нажмите « Decode ».

Страница возвращает десятичное значение ключа сегмента. Ниже приведен образец ключа ведра.

2.4. Создайте выходной домен AVRO

Теперь, когда у нас есть ключ сегмента, скопируйте десятичное значение ключа сегмента. Перейдите к созданию output_domain.avro , используя ключ ведра. Убедитесь, что вы заменили с ключом от ведра, который вы нашли.

java -jar aggregatable_report_converter.jar \
 --request_type createDomainAvro \
 --bucket_key <bucket key>

Скрипт создает файл output_domain.avro в вашей текущей папке.

2.5. Создание сводных отчетов с помощью инструмента локального тестирования.

Мы будем использовать LocalTestingTool_{version}.jar , загруженный в разделе 1.1, для создания сводных отчетов. Используйте следующую команду. Вам следует заменить LocalTestingTool_{version}.jar версией, загруженной для LocalTestingTool.

Запустите следующую команду, чтобы создать сводный отчет в вашей локальной среде разработки:

java -jar LocalTestingTool_{version}.jar \
--input_data_avro_file report.avro \
--domain_avro_file output_domain.avro \
--output_directory .

После запуска команды вы должны увидеть что-то похожее на следующее изображение. После завершения создается отчет output.avro .

2.6. Просмотрите сводный отчет

Создаваемый сводный отчет имеет формат AVRO. Чтобы прочитать это, вам необходимо преобразовать это из AVRO в формат JSON. В идеале рекламные технологии должны конвертировать отчеты AVRO обратно в JSON.

В нашей Codelab мы будем использовать предоставленный инструмент aggregatable_report_converter.jar для преобразования отчета AVRO обратно в JSON.

java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file output.avro

Это вернет отчет, подобный следующему изображению. Вместе с отчетом в том же каталоге создается output.json .

Откройте файл JSON в любом редакторе по вашему выбору, чтобы просмотреть сводный отчет.

3. Развертывание службы агрегации

Чтобы развернуть службу агрегации, выполните следующие действия:

Шаг 3. Развертывание службы агрегации : разверните службу агрегации на AWS.
Шаг 3.1. Клонировать репозиторий службы агрегации
Шаг 3.2. Скачать предварительно построенные зависимости
Шаг 3.3. Создать среду разработки
Шаг 3.4. Развернуть службу агрегации

3.1. Клонировать репозиторий службы агрегации

В вашей местной среде клонируйте репозиторий GitHub Service .

git clone https://github.com/privacysandbox/aggregation-service.git

3.2. Скачать предварительно построенные зависимости

Как только вы клонируете репозиторий службы агрегации, перейдите в папку Terraform репозитория и в соответствующую облачную папку. Если ваш Cloud_Provider - это AWS, вы можете перейти к /terraform/aws

cd <repository_root>/terraform/aws

В /terraform/aws , execute download_prebuilt_dependencies.sh .

bash download_prebuilt_dependencies.sh

3.3. Создать среду разработки

Создать среду разработки в /terraform/aws/environments . Создайте папку с именем dev .

mkdir dev

Скопируйте содержимое demo в папку dev .

cp -R demo/* dev

Перейдите в свою папку dev .

cd dev

Обновите свой файл main.tf и нажмите i для input для редактирования файла.

vim main.tf

Не понаблюдайте код в красном поле, удалив # и обновив имена ведра и ключей.

Для aws main.tf :

Неправильный код должен выглядеть следующим образом.

backend "s3" {
  bucket = "<tf_state_bucket_name>"
  key    = "<environment_name>.tfstate"
  region = "us-east-1"
}

После завершения обновлений сохраните обновления и покините редактор, нажав esc -> :wq! . Это сохраняет обновления на main.tf

Далее, переименовать example.auto.tfvars в dev.auto.tfvars .

mv example.auto.tfvars dev.auto.tfvars

Обновите dev.auto.tfvars и нажмите i для input для редактирования файла.

vim dev.auto.tfvars

Обновите поля в красном поле.

Как только обновления будут сделаны, нажмите esc -> :wq! . Это сохраняет файл dev.auto.tfvars , и он должен выглядеть примерно как следующее изображение.

3.4. Развернуть службу агрегации

Для развертывания службы агрегации, в той же папке /terraform/aws/environments/dev , инициализируйте Terraform.

terraform init

Это должно вернуть что -то похожее на следующее изображение:

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

terraform plan

Вы можете увидеть в следующем резюме « План ». Если это новое развертывание, вы должны увидеть количество ресурсов, которые будут добавлены с 0 для изменения и 0 для уничтожения.

После того, как вы завершите это, вы можете приступить к применению Terraform.

terraform apply

После того, как он будет предложено подтвердить при выполнении действий с помощью Terraform, введите « yes в значение.

После того, как terraform apply , возвращаются следующие конечные точки для createJob и getJob . The frontend_api_id , который вам необходимо обновить в почте, в разделе 1.9 также возвращается.

4. Создание ввода агрегации службы агрегации

Перейдите, чтобы создать отчеты AVRO для пакета в службе агрегации.

Шаг 4. Создание ввода агрегации .
Шаг 4.1. Триггер отчет
Шаг 4.2. Соберите агрегируемые отчеты
Шаг 4.3. Конвертировать отчеты в Avro
Шаг 4.4. Создать выходной домен Avro

4.1. Триггер отчет

Перейдите на демо -сайте Sandbox Crivacy Demo . Это запускает отчет о частном агрегации. Вы можете просмотреть отчет на chrome://private-aggregation-internals .

Если ваш отчет находится в статусе « ожидая », вы можете выбрать отчет и нажать « Отправить выбранные отчеты ».

4.2. Соберите агрегируемые отчеты

Соберите свои обширные отчеты из .well-known конечных точек вашего соответствующего API.

• Частная агрегация
  [reporting-origin] /.well-known/private-aggregation/report-shared-storage
• Отчет о атрибуции - сводный отчет
  [reporting-origin] /.well-known/attribution-reporting/report-aggregate-attribution

Для этого CodeLab вы будете выполнять коллекцию отчетов вручную. В производстве ожидается, что AD -технологии будут программно собирать и преобразовать отчеты.

В chrome://private-aggregation-internals скопируют « тело отчетов », полученное в конечной точке [reporting-origin]/.well-known/private-aggregation/report-shared-storage

Убедитесь, что в « Теле отчетности » aggregation_coordinator_origin содержит https://publickeyservice.msmt.aws.privacysandboxservices.com , что означает, что отчет является агрегируемым отчетом AWS.

Поместите JSON « Body » в файле JSON. В этом примере вы можете использовать Vim. Но вы можете использовать любой текстовый редактор, который вы хотите.

vim report.json

Вставьте отчет в report.json и сохраните свой файл.

4.3. Конвертировать отчеты в Avro

Отчеты, полученные из .well-known конечных точек, находятся в формате JSON и должны быть преобразованы в формат отчета AVRO. После того, как у вас появится отчет JSON, перейдите к папке отчетов и используйте aggregatable_report_converter.jar , чтобы помочь создать агрегатный отчет отладки. Это создает обширный отчет под названием report.avro в вашем текущем каталоге.

java -jar aggregatable_report_converter.jar \
 --request_type convertToAvro \
 --input_file report.json

4.4. Создать выходной домен Avro

Чтобы создать файл output_domain.avro , вам нужны клавиши ведра, которые можно извлечь из отчетов.

Ключи ведра разработаны рекламными технологиями. Однако в этом случае демонстрация песочницей конфиденциальности сайта создает ключи от ведра. Поскольку частная агрегация для этого сайта находится в режиме отладки, вы можете использовать debug_cleartext_payload из « Тела отчета », чтобы получить ключ ковша.

Продолжайте скопировать debug_cleartext_payload из тела отчета.

Откройте goo.gle/ags-payload-decoder и вставьте свой debug_cleartext_payload в поле « Вход » и нажмите « Декод ».

Страница возвращает десятичное значение ключа ведра. Ниже приведен образец ключа ковша.

Теперь, когда у нас есть ключ ведра, продолжайте и создайте output_domain.avro . Убедитесь, что вы замените с ключом, который вы извлекили.

java -jar aggregatable_report_converter.jar \
 --request_type createDomainAvro \
 --bucket_key <bucket key>

Сценарий создает файл output_domain.avro в вашей текущей папке.

4.5. Переместить отчеты в ведро AWS

После того, как AVRO отчеты (из раздела 3.2.3) и выходной домен (из раздела 3.2.4), перейдите к перемещению отчетов и выходной области в ведра S3 отчетов.

Если у вас есть настройка AWS CLI в вашей локальной среде, используйте следующие команды для копирования отчетов в соответствующее папку S3 и папку отчета.

aws s3 cp report.avro s3://<report_bucket_name>/<report_folder>/
aws s3 cp output_domain.avro s3://<report_bucket_name>/<output_domain_folder>/

5. Использование услуг агрегации

Из terraform apply вы возвращаете create_job_endpoint , get_job_endpoint и frontend_api_id . Скопируйте frontend_api_id и поместите это в Postman Global Variable frontend_api_id , который вы настраиваете в обязательном разделе 1.9.

Шаг 5. Использование службы агрегации : Используйте API службы агрегации для создания сводных отчетов и просмотра сводных отчетов.
Шаг 5.1. Использование конечной точки CreateJob для партии
Шаг 5.2. Использование конечной точки GetJob для получения статуса партии
Шаг 5.3. Просмотр сводного отчета

5.1. Использование конечной точки createJob для партии

В почтальстве откройте коллекцию " Sandbox" Crivacy Sandbox "и выберите" CreateJob ".

Выберите « Body » и выберите « Raw », чтобы разместить полезную нагрузку запроса.

Схема полезной нагрузки createJob доступна в GitHub и выглядит похоже на следующее. Замените <> на соответствующие поля.

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "input_data_bucket_name": "<bucket_name>",
  "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
  "output_data_bucket_name": "<bucket_name>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<bucket_name>",
    "attribution_report_to": "<reporting origin of report>",
    "reporting_site": "<domain of reporting origin(s) of report>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

Как только вы нажмете « Отправить », это создает задание с job_request_id . Вы должны получить ответ HTTP 202 после того, как запрос будет принят Службой агрегации. Другой возможный код возврата можно найти в кодах ответов HTTP

5.2. Использование конечной точки GetJob для получения статуса партии

Чтобы проверить статус запроса на работу, вы можете использовать конечную точку getJob . Выберите « getJob » в коллекции « Песоценка конфиденциальности ».

В « Params » обновите значение job_request_id для job_request_id , которое было отправлено в запросе createJob .

Результат getJob должен вернуть статус вашего запроса на задание со статусом HTTP 200. Запрос « тело » содержит необходимую информацию, такую ​​как job_status , return_message и error_messages (если задание ошибочено).

Поскольку сайт отчетности сгенерированного демо -отчета отличается от вашего сайта на борту на вашем идентификаторе AWS, вы можете получить ответ с PRIVACY_BUDGET_AUTHORIZATION_ERROR return_code. Это нормально, поскольку сайт отчетов отчетов Origin не совпадает с сайтом отчетов на борту для идентификатора AWS.

{
    "job_status": "FINISHED",
    "request_received_at": "2023-12-07T22:50:58.830956Z",
    "request_updated_at": "2023-12-07T22:51:10.526326456Z",
    "job_request_id": "<job_request_id>",
    "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
    "input_data_bucket_name": "<input_bucket_name>",
    "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
    "output_data_bucket_name": "<output_bucket_name>",
    "postback_url": "",
    "result_info": {
        "return_code": "PRIVACY_BUDGET_AUTHORIZATION_ERROR",
        "return_message": "Aggregation job successfully processed",
        "error_summary": {
            "error_counts": [],
            "error_messages": []
        },
        "finished_at": "2023-12-07T22:51:10.517730898Z"
    },
    "job_parameters": {
        "debug_run": "true",
        "output_domain_bucket_name": "<output_domain_bucket_name>",
        "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
        "attribution_report_to": "https://privacy-sandbox-demos-dsp.dev",
        "reporting_site": "<domain of reporting origin(s) of report>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
    },
    "request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}

5.3. Просмотр сводного отчета

После того, как вы получите свой сводный отчет в своем Bucket S3, вы можете скачать его в свою местную среду. Сводные отчеты находятся в формате Avro и могут быть преобразованы в JSON. Вы можете использовать aggregatable_report_converter.jar , чтобы прочитать ваш отчет, используя следующую команду.

java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file <summary_report_avro>

Это возвращает JSON агрегированных значений каждого ключа ведра, который выглядит похоже на следующее изображение.

Если ваш запрос createJob включит debug_run как true , то вы можете получить свой сводный отчет в папке отладки, которая находится в output_data_blob_prefix . Отчет находится в формате Avro и может быть преобразован с использованием предыдущей команды в JSON.

В отчете содержится ключ ковша, неиснованная метрика и шум, который добавляется в неиспользованную метрику для формирования сводного отчета. Отчет похож на следующее изображение.

Аннотации также содержат in_reports и in_domain что означает:

• in_reports - Ключ ведра доступен в агрегируемых отчетах.
• in_domain - клавиша ведра доступна в файле output_domain avro.

1. Предварительные условия

Чтобы выполнить этот коделаб, требуется несколько предпосылок. Каждое требование отмечено соответственно, требуется ли оно для «локального тестирования» или «службы агрегации».

1.1. Загрузите локальный инструмент тестирования (локальное тестирование)

Локальное тестирование потребует загрузки локального инструмента тестирования. Инструмент будет генерировать сводные отчеты из незашифрованных отчетов отладки.

Местный инструмент тестирования доступен для загрузки в архивах Lambda Jar в GitHub . Он должен быть назван как LocalTestingTool_{version}.jar .

1.2. Убедитесь, что Java JRE установлена ​​(локальная служба тестирования и агрегации)

Откройте « терминал » и используйте java --version , чтобы проверить, установлен ли на вашей машине Java или OpenJDK.

Если он не установлен, вы можете загрузить и установить с сайта Java или сайта OpenJDK .

1.3. Скачать агрегируемый конвертер отчетов (служба локального тестирования и агрегации)

Вы можете скачать копию агрегируемого преобразователя отчетов из репозитория Demos Demos Demos Confication .

1.4. Включить APIS конфиденциальности AD (служба локального тестирования и агрегации)

В вашем браузере перейдите в chrome://settings/adPrivacy и включите все API -конфиденциальности AD.

Убедитесь, что сторонние файлы cookie включены.

В вашем браузере перейдите в chrome://settings/cookies и выберите « Заблокировать сторонние файлы cookie в режиме инкогнито ».

1,5. Регистрация в Интернете и Android (служба агрегации)

Для использования APIS Sandbox Confication Sandbox в производственной среде убедитесь, что вы завершили зачисление и аттестацию как для Chrome, так и для Android.

Для локального тестирования регистрация может быть отключена с помощью хромового флага и CLI -переключателя .

Чтобы использовать флаг Chrome для нашей демонстрации, перейдите в chrome://flags/#privacy-sandbox-enrollment-overrides и обновите переопределение с вашим сайтом или, если вы будете использовать наш демонстрационный сайт, обновление не требуется.

1.6. Служба агрегации (служба агрегации)

Служба агрегации требует, чтобы координаторы были в состоянии использовать Сервис. Заполните форму службы агрегации , предоставив адрес вашего сайта отчетности, идентификатор учетной записи AWS и другую информацию.

1.7. Облачный провайдер (служба агрегации)

Служба агрегации требует использования доверенной среды выполнения, которая использует облачную среду. Служба агрегации поддерживается на Amazon Web Services (AWS) и Google Cloud (GCP). Этот CodeLab будет охватывать только интеграцию AWS.

AWS предоставляет надежную среду исполнения, называемую нитро -анклавами. Убедитесь, что у вас есть учетная запись AWS, и следуйте установке AWS CLI и обновите инструкции , чтобы настроить вашу среду AWS CLI.

Если ваш AWS CLI новый, вы можете настроить свой CLI AWS, используя инструкции по конфигурации CLI .

1.7.1. Создать ведро AWS S3

Создайте ведро AWS S3 для хранения Terraform State и еще одно ведро S3 для хранения ваших отчетов и сводных отчетов. Вы можете использовать предоставленную команду CLI. Замените поле в <> на правильные переменные.

aws s3api create-bucket --bucket <tf_bucket_name> --region us-east-1
aws s3api create-bucket --bucket <report_bucket_name> --region us-east-1

1.7.2. Создать ключ доступа пользователя

Создайте клавиши доступа пользователя, используя руководство AWS . Это будет использовано для вызова конечных точек API createJob и getJob , созданных на AWS.

1.7.3. Разрешения пользователя и группы AWS

Чтобы развернуть службу агрегации на AWS, вам нужно будет предоставить определенные разрешения пользователю, используемому для развертывания услуги. Для этого CodeLab убедитесь, что пользователь имеет доступ к администратору для обеспечения полных разрешений при развертывании.

1.8. Terraform (служба агрегации)

Этот Codelab использует Terraform для развертывания службы агрегации. Убедитесь, что бинар Terraform был установлен в вашу местную среду.

Загрузите бинар Terraform в местную среду.

После того, как бинар Terraform загрузится, извлеките файл и перенесите бинар Terraform в /usr/local/bin .

cp <directory>/terraform /usr/local/bin

Проверьте, чтобы убедиться, что Terraform доступен на классе.

terraform -v

1.9. Почтальон (для службы агрегации AWS)

Для этого CodeLab используйте почтальона для управления запросами.

Создайте рабочее пространство, перейдя в « Workspaces » Top Item и выберите « Создать рабочее пространство ».

Выберите « Пустое рабочее пространство », нажмите «Далее» и назовите его « Песочница конфиденциальности ». Выберите « Личный » и нажмите « Создать ».

Загрузите предварительно сконфигурированную конфигурацию JSON Workspace и файлы глобальной среды .

Импортируйте файлы JSON в « Мое рабочее пространство », используя кнопку « Импорт ».

Это создаст для вас коллекцию песочниц конфиденциальности, а также запросы createJob и getJob HTTP.

Обновите AWS «Ключ доступа» и «Секретный ключ» с помощью « Краткий вид среды ».

Нажмите « Редактировать » и обновить «текущее значение» как « access_key », так и « secret_key ». Обратите внимание, что frontend_api_id будет предоставлен в разделе 3.1.4 этого документа. И мы советуем использовать регион США-восток-1. Однако, если вы хотите развернуть в другом регионе, убедитесь, что вы скопируете выпущенную AMI в свою учетную запись или выполните самостоятельный строительство, используя предоставленные сценарии .

2. локальное тестирование CodeLab

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

Коделаб шаги

Шаг 2.1. Отчет за триггером : запускает отчеты о частной агрегации, чтобы иметь возможность собрать отчет.

Шаг 2.2. Создать агрегатный отчет отладки : преобразовать собранный отчет JSON в отчет с форматированным AVRO.
Этот шаг будет похож на то, когда AD Techs собирают отчеты из конечных точек отчетности API и конвертируют отчеты JSON в отчеты AVRO.

Шаг 2.3. Распокатайте ключ ведра из отчета отладки : Ключи для ведра разработаны AD Techs. В этом коделабе, поскольку ведра предопределены, извлеките клавиши ведер, как это предусмотрено.

Шаг 2.4. Создайте выходной домен AVRO : Как только клавиши ведра будут извлечены, создайте файл AVRO Output Domain.

Шаг 2.5. Создайте сводные отчеты с использованием локального инструмента тестирования : используйте локальный инструмент тестирования, чтобы иметь возможность создавать сводные отчеты в локальной среде.

Шаг 2.6. Просмотрите сводный отчет : просмотрите сводный отчет, созданный локальным инструментом тестирования.

2.1. Триггер отчет

Перейдите на демо -сайте Sandbox Crivacy Demo . Это запускает отчет о частном агрегации. Вы можете просмотреть отчет на chrome://private-aggregation-internals .

Если ваш отчет находится в статусе « ожидая », вы можете выбрать отчет и нажать « Отправить выбранные отчеты ».

2.2. Создать агрегируемый отчет отладки

В chrome://private-aggregation-internals скопируют « тело отчетов », полученное в конечной точке [reporting-origin]/.well-known/private-aggregation/report-shared-storage

Убедитесь, что в « Теле отчетности » aggregation_coordinator_origin содержит https://publickeyservice.msmt.aws.privacysandboxservices.com , что означает, что отчет является агрегируемым отчетом AWS.

Поместите JSON « Body » в файле JSON. В этом примере вы можете использовать Vim. Но вы можете использовать любой текстовый редактор, который вы хотите.

vim report.json

Вставьте отчет в report.json и сохраните свой файл.

После того, как вы это получите, перейдите к папке отчетов и используйте aggregatable_report_converter.jar , чтобы помочь создать агрегатный отчет отладки. Это создает обширный отчет под названием report.avro в вашем текущем каталоге.

java -jar aggregatable_report_converter.jar \
 --request_type convertToAvro \
 --input_file report.json \
 --debug

2.3. Проанализируйте ключ ведра из отчета отладки

Служба агрегации требует двух файлов при пакете. Агрегируемый отчет и файл домена выходного домена. Файл выходного домена содержит ключи, которые вы хотели бы получить из агрегируемых отчетов. Чтобы создать файл output_domain.avro , вам нужны клавиши ведра, которые можно извлечь из отчетов.

Ключи для ведра разработаны вызывающим абонент API, а демонстрация содержит предварительно скрепленные примеры клавиши ведра. Поскольку демонстрация позволила режим отладки для частной агрегации, вы можете проанализировать полезную нагрузку от DENAG CLEARTEXT из « Тела отчета » для извлечения ключа ведра. Однако в этом случае демонстрация песочницы с конфиденциальностью сайта создает клавиши ведра. Поскольку частная агрегация для этого сайта находится в режиме отладки, вы можете использовать debug_cleartext_payload из « Тела отчета », чтобы получить ключ ковша.

Скопируйте debug_cleartext_payload из тела отчета.

Откройте декодер с полезной нагрузкой отладки для приватного инструмента агрегации и вставьте свой debug_cleartext_payload в поле « Вход » и нажмите « Декод ».

Страница возвращает десятичное значение ключа ведра. Ниже приведен образец ключа ковша.

2.4. Создать выходной домен Avro

Теперь, когда у нас есть ключ ведра, идите дальше и скопируйте десятичное значение ключа ковша. Перейдите, чтобы создать output_domain.avro , используя ключ ковша. Убедитесь, что вы замените с ключом, который вы извлекили.

java -jar aggregatable_report_converter.jar \
 --request_type createDomainAvro \
 --bucket_key <bucket key>

Сценарий создает файл output_domain.avro в вашей текущей папке.

2.5. Создать сводные отчеты с использованием локального инструмента тестирования

Мы будем использовать LocalTestingTool_{version}.jar , который был загружен в разделе 1.1 для создания сводных отчетов. Используйте следующую команду. Вы должны заменить LocalTestingTool_{version}.jar с версией, загруженной для LocalTestingTool.

Запустите следующую команду для создания сводного отчета в вашей местной среде разработки:

java -jar LocalTestingTool_{version}.jar \
--input_data_avro_file report.avro \
--domain_avro_file output_domain.avro \
--output_directory .

Вы должны увидеть что -то похожее на следующее изображение после запуска команды. Отчет output.avro создается после его завершения.

2.6. Просмотрите сводный отчет

Сводной отчет, созданный в формате Avro. Чтобы иметь возможность прочитать это, вам нужно преобразовать это из AVRO в формат JSON. В идеале, рекламная технология должна кодировать для преобразования отчетов AVRO в JSON.

Для нашего CodeLab мы будем использовать предоставленный инструмент aggregatable_report_converter.jar для преобразования отчета AVRO обратно в JSON.

java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file output.avro

Это возвращает отчет, похожий на следующее изображение. Наряду с отчетом output.json созданным в том же каталоге.

Откройте файл JSON в редакторе по вашему выбору, чтобы просмотреть сводный отчет.

3. Развертывание службы агрегации

Для развертывания службы агрегации используйте следующие шаги:

Шаг 3. Развертывание службы агрегации : развертывание службы агрегации на AWS
Шаг 3.1. Клонировать репозиторий службы агрегации
Шаг 3.2. Скачать предварительно построенные зависимости
Шаг 3.3. Создать среду разработки
Шаг 3.4. Развернуть службу агрегации

3.1. Клонировать репозиторий службы агрегации

В вашей местной среде клонируйте репозиторий GitHub Service .

git clone https://github.com/privacysandbox/aggregation-service.git

3.2. Скачать предварительно построенные зависимости

Как только вы клонируете репозиторий службы агрегации, перейдите в папку Terraform репозитория и в соответствующую облачную папку. Если ваш Cloud_Provider - это AWS, вы можете перейти к /terraform/aws

cd <repository_root>/terraform/aws

В /terraform/aws , execute download_prebuilt_dependencies.sh .

bash download_prebuilt_dependencies.sh

3.3. Создать среду разработки

Создать среду разработки в /terraform/aws/environments . Создайте папку с именем dev .

mkdir dev

Скопируйте содержимое demo в папку dev .

cp -R demo/* dev

Перейдите в свою папку dev .

cd dev

Обновите свой файл main.tf и нажмите i для input для редактирования файла.

vim main.tf

Не понаблюдайте код в красном поле, удалив # и обновив имена ведра и ключей.

Для aws main.tf :

Неправильный код должен выглядеть следующим образом.

backend "s3" {
  bucket = "<tf_state_bucket_name>"
  key    = "<environment_name>.tfstate"
  region = "us-east-1"
}

После завершения обновлений сохраните обновления и покините редактор, нажав esc -> :wq! . Это сохраняет обновления на main.tf

Далее, переименовать example.auto.tfvars в dev.auto.tfvars .

mv example.auto.tfvars dev.auto.tfvars

Обновите dev.auto.tfvars и нажмите i для input для редактирования файла.

vim dev.auto.tfvars

Обновите поля в красном поле.

Как только обновления будут сделаны, нажмите esc -> :wq! . Это сохраняет файл dev.auto.tfvars , и он должен выглядеть примерно как следующее изображение.

3.4. Развернуть службу агрегации

Для развертывания службы агрегации, в той же папке /terraform/aws/environments/dev , инициализируйте Terraform.

terraform init

Это должно вернуть что -то похожее на следующее изображение:

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

terraform plan

Вы можете увидеть в следующем резюме « План ». Если это новое развертывание, вы должны увидеть количество ресурсов, которые будут добавлены с 0 для изменения и 0 для уничтожения.

После того, как вы завершите это, вы можете приступить к применению Terraform.

terraform apply

После того, как он будет предложено подтвердить при выполнении действий с помощью Terraform, введите « yes в значение.

После того, как terraform apply , возвращаются следующие конечные точки для createJob и getJob . The frontend_api_id , который вам необходимо обновить в почте, в разделе 1.9 также возвращается.

4. Создание ввода агрегации службы агрегации

Перейдите, чтобы создать отчеты AVRO для пакета в службе агрегации.

Шаг 4. Создание ввода агрегации .
Шаг 4.1. Триггер отчет
Шаг 4.2. Соберите агрегируемые отчеты
Шаг 4.3. Конвертировать отчеты в Avro
Шаг 4.4. Создать выходной домен Avro

4.1. Триггер отчет

Перейдите на демо -сайте Sandbox Crivacy Demo . Это запускает отчет о частном агрегации. Вы можете просмотреть отчет на chrome://private-aggregation-internals .

Если ваш отчет находится в статусе « ожидая », вы можете выбрать отчет и нажать « Отправить выбранные отчеты ».

4.2. Соберите агрегируемые отчеты

Соберите свои обширные отчеты из .well-known конечных точек вашего соответствующего API.

• Частная агрегация
  [reporting-origin] /.well-known/private-aggregation/report-shared-storage
• Отчет о атрибуции - сводный отчет
  [reporting-origin] /.well-known/attribution-reporting/report-aggregate-attribution

Для этого CodeLab вы будете выполнять коллекцию отчетов вручную. В производстве ожидается, что AD -технологии будут программно собирать и преобразовать отчеты.

В chrome://private-aggregation-internals скопируют « тело отчетов », полученное в конечной точке [reporting-origin]/.well-known/private-aggregation/report-shared-storage

Убедитесь, что в « Теле отчетности » aggregation_coordinator_origin содержит https://publickeyservice.msmt.aws.privacysandboxservices.com , что означает, что отчет является агрегируемым отчетом AWS.

Поместите JSON « Body » в файле JSON. В этом примере вы можете использовать Vim. Но вы можете использовать любой текстовый редактор, который вы хотите.

vim report.json

Вставьте отчет в report.json и сохраните свой файл.

4.3. Конвертировать отчеты в Avro

Отчеты, полученные из .well-known конечных точек, находятся в формате JSON и должны быть преобразованы в формат отчета AVRO. После того, как у вас появится отчет JSON, перейдите к папке отчетов и используйте aggregatable_report_converter.jar , чтобы помочь создать агрегатный отчет отладки. Это создает обширный отчет под названием report.avro в вашем текущем каталоге.

java -jar aggregatable_report_converter.jar \
 --request_type convertToAvro \
 --input_file report.json

4.4. Создать выходной домен Avro

Чтобы создать файл output_domain.avro , вам нужны клавиши ведра, которые можно извлечь из отчетов.

Ключи ведра разработаны рекламными технологиями. Однако в этом случае демонстрация песочницей конфиденциальности сайта создает ключи от ведра. Поскольку частная агрегация для этого сайта находится в режиме отладки, вы можете использовать debug_cleartext_payload из « Тела отчета », чтобы получить ключ ковша.

Продолжайте скопировать debug_cleartext_payload из тела отчета.

Откройте goo.gle/ags-payload-decoder и вставьте свой debug_cleartext_payload в поле « Вход » и нажмите « Декод ».

Страница возвращает десятичное значение ключа ведра. Ниже приведен образец ключа ковша.

Теперь, когда у нас есть ключ ведра, продолжайте и создайте output_domain.avro . Убедитесь, что вы замените с ключом, который вы извлекили.

java -jar aggregatable_report_converter.jar \
 --request_type createDomainAvro \
 --bucket_key <bucket key>

Сценарий создает файл output_domain.avro в вашей текущей папке.

4.5. Переместить отчеты в ведро AWS

После того, как AVRO отчеты (из раздела 3.2.3) и выходной домен (из раздела 3.2.4), перейдите к перемещению отчетов и выходной области в ведра S3 отчетов.

Если у вас есть настройка AWS CLI в вашей локальной среде, используйте следующие команды для копирования отчетов в соответствующее папку S3 и папку отчета.

aws s3 cp report.avro s3://<report_bucket_name>/<report_folder>/
aws s3 cp output_domain.avro s3://<report_bucket_name>/<output_domain_folder>/

5. Использование услуг агрегации

Из terraform apply вы возвращаете create_job_endpoint , get_job_endpoint и frontend_api_id . Скопируйте frontend_api_id и поместите это в Postman Global Variable frontend_api_id , который вы настраиваете в обязательном разделе 1.9.

Шаг 5. Использование службы агрегации : Используйте API службы агрегации для создания сводных отчетов и просмотра сводных отчетов.
Шаг 5.1. Использование конечной точки CreateJob для партии
Шаг 5.2. Использование конечной точки GetJob для получения статуса партии
Шаг 5.3. Просмотр сводного отчета

5.1. Использование конечной точки createJob для партии

В почтальстве откройте коллекцию " Sandbox" Crivacy Sandbox "и выберите" CreateJob ".

Выберите « Body » и выберите « Raw », чтобы разместить полезную нагрузку запроса.

Схема полезной нагрузки createJob доступна в GitHub и выглядит похоже на следующее. Замените <> на соответствующие поля.

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "input_data_bucket_name": "<bucket_name>",
  "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
  "output_data_bucket_name": "<bucket_name>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<bucket_name>",
    "attribution_report_to": "<reporting origin of report>",
    "reporting_site": "<domain of reporting origin(s) of report>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

Как только вы нажмете « Отправить », это создает задание с job_request_id . Вы должны получить ответ HTTP 202 после того, как запрос будет принят Службой агрегации. Другой возможный код возврата можно найти в кодах ответов HTTP

5.2. Использование конечной точки GetJob для получения статуса партии

Чтобы проверить статус запроса на работу, вы можете использовать конечную точку getJob . Выберите « getJob » в коллекции « Песоценка конфиденциальности ».

В « Params » обновите значение job_request_id для job_request_id , которое было отправлено в запросе createJob .

Результат getJob должен вернуть статус вашего запроса на задание со статусом HTTP 200. Запрос « тело » содержит необходимую информацию, такую ​​как job_status , return_message и error_messages (если задание ошибочено).

Поскольку сайт отчетности сгенерированного демо -отчета отличается от вашего сайта на борту на вашем идентификаторе AWS, вы можете получить ответ с PRIVACY_BUDGET_AUTHORIZATION_ERROR return_code. Это нормально, поскольку сайт отчетов отчетов Origin не совпадает с сайтом отчетов на борту для идентификатора AWS.

{
    "job_status": "FINISHED",
    "request_received_at": "2023-12-07T22:50:58.830956Z",
    "request_updated_at": "2023-12-07T22:51:10.526326456Z",
    "job_request_id": "<job_request_id>",
    "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
    "input_data_bucket_name": "<input_bucket_name>",
    "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
    "output_data_bucket_name": "<output_bucket_name>",
    "postback_url": "",
    "result_info": {
        "return_code": "PRIVACY_BUDGET_AUTHORIZATION_ERROR",
        "return_message": "Aggregation job successfully processed",
        "error_summary": {
            "error_counts": [],
            "error_messages": []
        },
        "finished_at": "2023-12-07T22:51:10.517730898Z"
    },
    "job_parameters": {
        "debug_run": "true",
        "output_domain_bucket_name": "<output_domain_bucket_name>",
        "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
        "attribution_report_to": "https://privacy-sandbox-demos-dsp.dev",
        "reporting_site": "<domain of reporting origin(s) of report>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
    },
    "request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}

5.3. Просмотр сводного отчета

После того, как вы получите свой сводный отчет в своем Bucket S3, вы можете скачать его в свою местную среду. Сводные отчеты находятся в формате Avro и могут быть преобразованы в JSON. Вы можете использовать aggregatable_report_converter.jar , чтобы прочитать ваш отчет, используя следующую команду.

java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file <summary_report_avro>

Это возвращает JSON агрегированных значений каждого ключа ведра, который выглядит похоже на следующее изображение.

Если ваш запрос createJob включит debug_run как true , то вы можете получить свой сводный отчет в папке отладки, которая находится в output_data_blob_prefix . Отчет находится в формате Avro и может быть преобразован с использованием предыдущей команды в JSON.

В отчете содержится ключ ковша, неиснованная метрика и шум, который добавляется в неиспользованную метрику для формирования сводного отчета. Отчет похож на следующее изображение.

Аннотации также содержат in_reports и in_domain что означает:

• in_reports - Ключ ведра доступен в агрегируемых отчетах.
• in_domain - клавиша ведра доступна в файле output_domain avro.