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

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

После успешного развертывания службы агрегации вы можете использовать конечные точки createJob и getJob для взаимодействия со службой. На следующей схеме показано визуальное представление архитектуры развертывания для этих двух конечных точек.

**Рисунок 1.** Обзор API службы агрегации

Подробнее о конечных точках createJob и getJob можно прочитать в документации API Aggregation Service .

Создать работу

Чтобы создать задание, отправьте запрос 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`	Нить	Это путь ведра. Для отдельных файлов вы можете использовать путь. Для нескольких файлов вы можете использовать префикс в пути. Пример: папка/файл собирает все отчеты из папки/файл1.avro, папки/файла/файл1.avro и папки/файл1/test/file2.avro.
`input_data_bucket_name`	Нить	Это сегмент хранения входных данных или агрегированных отчетов. Это в облачном хранилище рекламной технологии.
`output_data_blob_prefix`	Нить	Это путь вывода в сегменте. Поддерживается один выходной файл.
`output_data_bucket_name`	Нить	Это сегмент хранилища, куда отправляются `output_data` . Он существует в облачном хранилище рекламной технологии.
`job_parameters`	Словарь	Обязательное поле. Это поле содержит различные поля, такие как: `output_domain_blob_prefix` `output_domain_bucket_name` `attribution_report_to` `reporting_site` `debug_privacy_epsilon` `report_error_threshold_percentage`
`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`	Плавающая точка, Двойной	Необязательное поле. Если значение не передано, значение по умолчанию — 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`	Плавающая точка, двойной	Необязательное поле. Если значение не передано, используется значение по умолчанию 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».)