Эта страница переведена с помощью Cloud Translation API.

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

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

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

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

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

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

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

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

$проверка версии Java JRE с помощью java\n--version$

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

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

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

1.4. Включить API-интерфейсы Privacy Sandbox (служба локального тестирования и агрегирования)

В браузере перейдите по chrome://flags/#privacy-sandbox-ads-apis и включите API Privacy Sandbox.

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

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

настройка Chrome сторонних файлов 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 в « Мое рабочее пространство » с помощью кнопки « Импорт ».

импортировать 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 .

Chrome Private AggregationInternals

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

отправить частный отчет по агрегированию

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 и сохраните файл.

отчет в формате 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 .

Сводный отчет о локальном тестировании avrofile

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 .

сводный файл avro, преобразованный в tojson

Откройте файл 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 :

Основной tf-файл AWS

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

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, которые предоставляются во время регистрации службы агрегации, среды и электронного уведомления.

редактировать файл dev auto tfvars

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

обновлен файл 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 .

Chrome Private AggregationInternals

отправить частный отчет по агрегированию

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

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

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

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

частный отчет по агрегированию

vim report.json

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

отчет в формате 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 requestbody

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

{
  "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>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<output_domain_bucket_name>",
    "attribution_report_to": "<reporting origin of report>",
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

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

Почтальон createJob requeststatus

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

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

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

почтальон getJobrequest

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

Почтальон getJob requeststatus

Поскольку сайт отчетов созданного демонстрационного отчета отличается от сайта, подключенного к вашему идентификатору 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-news.dev"
    },
    "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 выходного_домена.