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 Endpoint для пакетной обработки
Шаг 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 выходного_домена.