После успешного развертывания Aggregation Service вы можете использовать конечные точки createJob и getJob для взаимодействия со службой. Следующая диаграмма наглядно представляет архитектуру развертывания для этих двух конечных точек:
Дополнительную информацию о конечных точках createJob и getJob можно найти в документации API службы агрегации .
Создать работу
Чтобы создать задание, отправьте запрос POST на конечную точку createJob . bash POST https://<api-gateway>/stage/v1alpha/createJob -+ Пример тела запроса для createJob :
{
"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>",
"reporting_site": "<host name of reporting origin>"
}
}
Успешное создание задания приводит к получению HTTP-кода статуса 202.
Обратите внимание, что reporting_site и attribution_report_to являются взаимоисключающими , и требуется только один из них.
Вы также можете запросить задание отладки, добавив debug_run в job_parameters . Для получения дополнительной информации о режиме отладки ознакомьтесь с нашей документацией по агрегации отладочного запуска .
{
"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>"
"debug_run": "true"
}
}
Запросить поля
| Параметр | Тип | Описание |
|---|---|---|
job_request_id | Нить | Это уникальный идентификатор, сгенерированный рекламной технологией, который должен состоять из букв ASCII с 128 символами или меньше. Он идентифицирует запрос пакетного задания и берет все агрегируемые отчеты AVRO, указанные в `input_data_blob_prefix`, из входного контейнера, указанного в `input_data_bucket_name`, который размещен в облачном хранилище рекламной технологии. Символы: `az, AZ, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~ |
input_data_blob_prefix | Нить | Это путь к контейнеру. Для отдельных файлов можно использовать путь. Для нескольких файлов можно использовать префикс в пути. Пример: папка/файл собирает все отчеты из folder/file1.avro, folder/file/file1.avro и folder/file1/test/file2.avro. |
input_data_bucket_name | Нить | Это хранилище для входных данных или агрегируемых отчетов. Это находится в облачном хранилище ad tech. |
output_data_blob_prefix | Нить | Это выходной путь в контейнере. Поддерживается один выходной файл. |
output_data_bucket_name | Нить | Это контейнер хранения, куда отправляются output_data . Он существует в облачном хранилище рекламного технологического сервиса. |
job_parameters | Словарь | Обязательное поле. Это поле содержит различные поля, такие как:
|
job_parameters.output_domain_blob_prefix | Нить | Подобно input_data_blob_prefix , это путь в output_domain_bucket_name , где находится ваш выходной домен AVRO. Для нескольких файлов можно использовать префикс в пути. После того, как Aggregation Service завершит пакет, будет создан сводный отчет, который будет помещен в выходной контейнер output_data_bucket_name с именем output_data_blob_prefix . |
job_parameters.output_domain_bucket_name | Нить | Это контейнер для хранения вашего выходного домена AVRO файла. Это в облачном хранилище ad tech. |
job_parameters.attribution_report_to | Нить | Это значение является взаимоисключающим для `reporting_site`. Это URL-адрес отчета или источник отчета, где был получен отчет. Источник сайта зарегистрирован в Aggregation Service Onboarding. |
job_parameters.reporting_site | Нить | Взаимоисключающее с attribution_report_to . Это имя хоста URL-адреса отчета или источника отчета, где был получен отчет. Источник сайта зарегистрирован в Aggregation Service Onboarding. Примечание: Вы можете отправить несколько отчетов с разными источниками в одном запросе, при условии, что все источники принадлежат одному и тому же сайту отчета, указанному в этом параметре. |
job_parameters.debug_privacy_epsilon | С плавающей точкой, Двойной | Необязательное поле. Если значение не передано, значение по умолчанию — 10. Можно использовать значение от 0 до 64. |
job_parameters.report_error_threshold_percentage | Двойной | Необязательное поле. Это максимальный процент невыполненных отчетов, разрешенный до того, как задание будет признано невыполненным. Если оставить пустым, значение по умолчанию составит 10%. |
job_parameters.input_report_count | длинное значение | Необязательное поле. Общее количество отчетов, предоставленных в качестве входных данных для задания. Это значение в сочетании с report_error_threshold_percentage позволяет выполнить ранний сбой задания, когда отчеты исключаются из-за ошибок. |
job_parameters.filtering_ids | Нить | Необязательное поле. Список неподписанных идентификаторов фильтрации, разделенных запятой. Все вклады, кроме соответствующего идентификатора фильтрации, отфильтровываются. (например, "filtering_ids": "12345,34455,12" ). Значение по умолчанию — 0. |
job_parameters.debug_run | Булев | Необязательное поле. При выполнении отладочного прогона добавляются зашумленные и незашумленные сводные отчеты отладки и аннотации, указывающие, какие ключи присутствуют во входных данных домена и/или отчетах. Кроме того, дубликаты между пакетами также не применяются. Обратите внимание, что отладочный прогон учитывает только отчеты с флагом "debug_mode": "enabled" . Начиная с версии 2.10.0, отладочные прогоны >не расходуют бюджет конфиденциальности. |
Получить работу
Когда рекламный техник хочет узнать статус запрошенного пакета, он может вызвать конечную точку getJob . Конечная точка getJob вызывается с помощью HTTPS-запроса GET вместе с параметром job_request_id .
GET https://<api-gateway>/stage/v1alpha/getJob?job_request_id=<job_request_id>
Вы должны получить ответ, который возвращает статус задания вместе со всеми сообщениями об ошибках:
{
"job_status": "FINISHED",
"request_received_at": "2023-07-17T19:15:13.926530Z",
"request_updated_at": "2023-07-17T19:15:28.614942839Z",
"job_request_id": "PSD_0003",
"input_data_blob_prefix": "reports/output_reports_2023-07-17T19:11:27.315Z.avro",
"input_data_bucket_name": "ags-report-bucket",
"output_data_blob_prefix": "summary/summary.avro",
"output_data_bucket_name": "ags-report-bucket",
"postback_URL": "",
"result_info": {
"return_code": "SUCCESS",
"return_message": "Aggregation job successfully processed",
"error_summary": {
"error_counts": [],
"error_messages": []
},
"finished_at": "2023-07-17T19:15:28.607802354Z"
},
"job_parameters": {
"debug_run": "true",
"output_domain_bucket_name": "ags-report-bucket",
"output_domain_blob_prefix": "output_domain/output_domain.avro",
"attribution_report_to": "https://privacy-sandcastle-dev-dsp.web.app"
},
"request_processing_started_at": "2023-07-17T19:15:21.583759622Z"
}
Поля ответа
| Параметр | Тип | Описание |
|---|---|---|
job_request_id | Нить | Это уникальный идентификатор задания/пакета, указанный в запросе createJob . |
job_status | Нить | Это статус запроса на работу. |
request_received_at | Нить | Время получения запроса. |
request_updated_at | Нить | Время последнего обновления вакансии. |
input_data_blob_prefix | Нить | Это префикс входных данных, который был установлен в createJob . |
input_data_bucket_name | Нить | Это вставка входных данных рекламного tech, где хранятся агрегируемые отчеты. Это поле устанавливается в createJob . |
output_data_blob_prefix | Нить | Это префикс выходных данных, который был установлен в createJob . |
output_data_bucket_name | Нить | Это контейнер выходных данных рекламного tech, где хранятся сгенерированные сводные отчеты. Это поле задается в createJob . |
request_processing_started_at | Нить | Время начала последней попытки обработки. Это исключает время ожидания в очереди заданий. (Общее время обработки = request_updated_at - request_processing_started_at ) |
result_info | Словарь | Это результат запроса createJob , который состоит из всей доступной информации. Здесь показаны значения return_code , return_message , finished_at и error_summary . |
result_info.return_code | Нить | Код возврата результата задания. Эта информация необходима для устранения неполадок, если в службе агрегации возникли неполадки. |
result_info.return_message | Нить | Сообщение об успешном или неудачном выполнении, возвращенное в результате задания. Эта информация также необходима для устранения неполадок Aggregation Service. |
result_info.error_summary | Словарь | Ошибки, возвращаемые заданием. Содержит количество отчетов вместе с типом обнаруженных ошибок. |
result_info.finished_at | Временная метка | Временная метка, указывающая на завершение работы. |
result_info.error_summary.error_counts | Список | Это возвращает список сообщений об ошибках вместе с количеством отчетов, которые не были выполнены с тем же сообщением об ошибке. Каждое количество ошибок содержит категорию, error_count и description . |
result_info.error_summary.error_messages | Список | Возвращает список сообщений об ошибках из отчетов, которые не удалось обработать. |
job_parameters | Словарь | Это содержит параметры задания, предоставленные в запросе createJob . Соответствующие свойства, такие как `output_domain_blob_prefix` и `output_domain_bucket_name`. |
job_parameters.attribution_report_to | Нить | Взаимоисключающие для reporting_site . Это URL-адрес отчета или источник, откуда был получен отчет. Источник — это часть сайта, зарегистрированная в Aggregation Service Onboarding. Это указано в запросе createJob . |
job_parameters.reporting_site | Нить | Взаимоисключающее с attribution_report_to . Это имя хоста URL-адреса отчета или источник, откуда был получен отчет. Источник является частью сайта, зарегистрированного в Aggregation Service Onboarding. Обратите внимание, что вы можете отправлять отчеты с несколькими источниками отчетов в одном запросе, если все источники отчетов принадлежат одному и тому же сайту, указанному в этом параметре. Это указано в запросе createJob . Кроме того, проверьте, что контейнер содержит только те отчеты, которые вы хотите агрегировать во время создания задания. Обрабатываются любые отчеты, добавленные в контейнер входных данных с источниками отчетов, соответствующими сайту отчетов, указанному в параметре задания. Служба агрегации рассматривает только те отчеты в контейнере данных, которые соответствуют зарегистрированному источнику отчетов задания. Например, если зарегистрированным источником является https://exampleabc.com, будут включены только отчеты с https://exampleabc.com, даже если в контейнере содержатся отчеты с поддоменов ( https://1.exampleabc.com и т. д.) или совершенно других доменов ( https://3.examplexyz.com ). |
job_parameters.debug_privacy_epsilon | С плавающей точкой, Двойной | Необязательное поле. Если значение не передано, используется значение по умолчанию 10. Значения могут быть от 0 до 64. Это значение указывается в запросе createJob . |
job_parameters.report_error_threshold_percentage | Двойной | Необязательное поле. Это пороговый процент отчетов, которые могут быть невыполнены до сбоя задания. Если значение не назначено, используется значение по умолчанию 10%. Это указывается в запросе createJob . |
job_parameters.input_report_count | Длинное значение | Необязательное поле. Общее количество отчетов, предоставленных в качестве входных данных для этого задания. `report_error_threshold_percentage` в сочетании с этим значением вызывает ранний сбой задания, если значительное количество отчетов исключено из-за ошибок. Этот параметр указывается в запросе `createJob`. |
job_parameters.filtering_ids | Нить | Необязательное поле. Список неподписанных идентификаторов фильтрации, разделенных запятой. Все вклады, кроме соответствующего идентификатора фильтрации, отфильтровываются. Это указано в запросе createJob . (например, "filtering_ids":"12345,34455,12" . Значение по умолчанию — "0".) |