После успешного развертывания службы агрегации вы можете использовать конечные точки createJob и getJob для взаимодействия со службой. На следующей диаграмме представлено визуальное отображение архитектуры развертывания для этих двух конечных точек:
Более подробную информацию о конечных точках createJob и getJob можно найти в документации по API сервиса агрегации .
Создать вакансию
Для создания задания отправьте POST-запрос на конечную точку createJob . Пример тела запроса для createJob : bash POST https://<api-gateway>/stage/v1alpha/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 | Нить | Это путь к хранилищу. Для отдельных файлов можно использовать этот путь. Для файлов, содержащих несколько файлов, можно использовать префикс в пути. Пример: Папка/файл собирает все отчеты из папок/файл1.avro,/файл/файл1.avro и/файл/файл1/test/файл2.avro. |
input_data_bucket_name | Нить | Это хранилище для входных данных или сводных отчетов. Оно находится в облачном хранилище рекламной компании. |
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. Для нескольких файлов можно использовать префикс в пути. После завершения обработки пакета службой агрегации создается сводный отчет, который помещается в выходной сегмент output_data_bucket_name с именем output_data_blob_prefix . |
job_parameters.output_domain_bucket_name | Нить | Это хранилище для вашего AVRO-файла выходного домена. Оно находится в облачном хранилище рекламной компании. |
job_parameters.attribution_report_to | Нить | Это значение исключает значение `reporting_site`. Это URL-адрес или источник отчета, откуда был получен отчет. Источник сайта регистрируется в процессе подключения к службе агрегации. |
job_parameters.reporting_site | Нить | Параметр attribution_report_to взаимоисключающий. Это имя хоста URL-адреса или источника отчета, откуда был получен отчет. Источник регистрации сайта указан в процессе подключения к службе агрегации. Примечание: Вы можете отправить несколько отчетов с разными источниками в рамках одного запроса при условии, что все источники принадлежат одному и тому же сайту, указанному в этом параметре. |
job_parameters.debug_privacy_epsilon | Число с плавающей запятой, Double | Необязательное поле. Если значение не указано, используется значение по умолчанию 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 | Нить | Это хранилище входных данных рекламного технологического подразделения, где хранятся сводные отчеты. Это поле задается при createJob . |
output_data_blob_prefix | Нить | Это префикс выходных данных, заданный при createJob . |
output_data_bucket_name | Нить | Это хранилище выходных данных рекламного технологического подразделения, где хранятся сгенерированные сводные отчеты. Это поле задается при 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 | Нить | В результате выполнения задания было получено либо сообщение об успехе, либо сообщение о неудаче. Эта информация также необходима для устранения неполадок в работе службы агрегации. |
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-адрес для отправки отчета или источник, откуда был получен отчет. Источник — это часть сайта, зарегистрированного в процессе подключения к сервису агрегации. Это указывается в запросе createJob . |
job_parameters.reporting_site | Нить | Параметр attribution_report_to взаимоисключающий. Это имя хоста URL-адреса отчета или источник, откуда был получен отчет. Источник является частью сайта, зарегистрированного в процессе подключения к службе агрегации. Обратите внимание, что вы можете отправлять отчеты с несколькими источниками в одном запросе, если все источники принадлежат одному и тому же сайту, указанному в этом параметре. Это указывается в запросе createJob . Кроме того, убедитесь, что в корзине содержатся только те отчеты, которые вы хотите агрегировать на момент создания задания. Любые отчеты, добавленные во входную корзину данных с источниками, соответствующими сайту, указанному в параметре задания, будут обработаны. Служба агрегации учитывает только те отчеты в корзине данных, которые соответствуют зарегистрированному источнику для задания. Например, если зарегистрированный источник — https://exampleabc.com, то включаются только отчеты с https://exampleabc.com, даже если в хранилище содержатся отчеты с поддоменов ( https://1.exampleabc.com и т. д.) или совершенно других доменов ( https://3.examplexyz.com ). |
job_parameters.debug_privacy_epsilon | Число с плавающей запятой, Double | Необязательное поле. Если значение не указано, используется значение по умолчанию 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".) |