Используйте API DAI для рекламных пауз

API DAI Ad Break позволяет создавать и управлять временем показа и данными о целевой рекламе в рекламных паузах ваших прямых трансляций.

В этом руководстве описано использование API DAI Ad Break для создания, обновления и удаления рекламной паузы для прямой трансляции Google Dynamic Ads Insertion (DAI).

Предварительные требования

Для использования API DAI Ad Break вам потребуется следующее:

Настройка доступа к API

Для активации API выполните следующие шаги:

  1. Создайте учетную запись службы. Дополнительную информацию см. в разделе «Создание учетной записи службы» .
  2. Добавьте сервисный аккаунт в свою рекламную сеть Google Ad Manager. Дополнительную информацию см. в разделе «Добавление пользователя сервисного аккаунта для доступа к API» .
  3. Предоставьте своему менеджеру аккаунта Google адрес электронной почты сервисного аккаунта и код вашей рекламной сети Google Ad Manager.
  4. Включите API Google Ad Manager Video в своем проекте Google Cloud. Для получения дополнительной информации см. раздел «Включение API и сервисов» для вашего приложения .

Аутентификация с помощью OAuth2

Для авторизации запросов к API выполните следующие действия:

  1. Сгенерируйте токен доступа с областью действия https://www.googleapis.com/auth/video-ads .
  2. В каждом запросе указывайте токен доступа к API в качестве значения Bearer в заголовке HTTP Authorization . Дополнительную информацию см. в разделе «Вызов API Google» .

В следующем примере генерируется токен OAuth с областью действия API DAI Ad Break:

gcloud auth print-access-token --scopes='https://www.googleapis.com/auth/video-ads'

В случае успеха вы увидите следующий токен доступа:

ya29.c.c0ASRK0GYUYU0...

Сделайте первый запрос

Чтобы получить список рекламных пауз для прямой трансляции, используйте метод GET для вывода списка всех объектов AdBreak по сгенерированному системой ключу ресурса события или по вашему собственному ключу ресурса .

API DAI Ad Break возвращает только сущности AdBreak , созданные через API, за исключением рекламных пауз, созданных на основе манифеста, запроса сегмента пода или запроса манифеста пода.

В следующем примере запроса отображается список объектов AdBreak по значению assetKey :

curl -X GET "https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OAUTH_TOKEN"

В случае успеха вы увидите следующий JSON-ответ:

{
 "adBreaks": []
}

При создании дополнительных объектов AdBreak через API и запросе списка вы увидите следующий JSON-ответ:

{
 "adBreaks": [
    {
      "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
      "expectedDuration": "30s",
      "expectedStartTime": "2025-06-03T15:00:00Z",
      "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
      "customParams": "param1=value1&param2=value2",
      "podTemplateName": "podtemplate"
      "breakState": "BREAK_STATE_SCHEDULED",
    },
    {
      "name": "networks/.../assets/.../adBreaks/cc68b0df-0257-46e7-8193-254060b6256c",
      "breakSequence": "1",
      "expectedDuration": "30s",
      "expectedStartTime": "2025-06-03T14:30:00Z",
      "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
      "customParams": "param1=value1&param2=value2",
      "podTemplateName": "podtemplate"
      "breakState": "BREAK_STATE_COMPLETE",
    },
    …
  ],
  "nextPageToken": "ChAIARIMCNDn97IGEJbhhYUC"
}

Создайте сущность AdBreak

Чтобы сообщить Google DAI о предстоящей рекламной паузе во время прямой трансляции, используйте метод POST .

  • Для создания нового объекта AdBreak необходимо дождаться, пока предыдущий перейдет в состояние BREAK_STATE_COMPLETE .
  • В качестве альтернативы вы можете удалить ожидающий выполнения объект AdBreak , чтобы создать новый.
  • Чтобы создать более одного объекта AdBreak для одного прямого эфира, обратитесь к своему менеджеру по работе с клиентами за расширенными настройками.

Приведенный ниже пример запроса создает рекламную паузу, которая, как ожидается, начнется 3 июня 2025 года в 15:00:00 UTC:

curl -X POST "https://admanagervideo.googleapis.com/v1/adBreak/networks/{NETWORK_CODE}/assets/ASSET_KEY/adBreaks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OAUTH_TOKEN" \
  -d '{
    "expectedDuration": "30s",
    "expectedStartTime": "2025-06-03T15:00:00Z",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
  }'

В случае успеха вы увидите следующий JSON-ответ:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",  "expectedStartTime": "2025-06-03T15:00:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
  "breakState": "BREAK_STATE_SCHEDULED",
}

В результате отображается идентификатор рекламной паузы, необходимый для получения, изменения или удаления рекламной паузы. В примере ответа созданный идентификатор рекламной паузы — bcc402a6-9880-4b8b-8e4a-a8cd3688f854 .

Получить объект AdBreak

Используйте метод GET для получения подробной информации о конкретном объекте AdBreak , включая состояние и временные метаданные рекламной паузы.

curl -X GET \
'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer OAUTH_TOKEN'

В случае успеха вы увидите следующий JSON-ответ:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",
  "expectedStartTime": "2025-06-03T15:10:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
  "breakState": "BREAK_STATE_SCHEDULED",
}

Обновить объект AdBreak

Чтобы изменить предстоящий рекламный блок до начала принятия решения о показе рекламы, используйте метод PATCH : 

curl -X PATCH 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer OAUTH_TOKEN' \
  -d '{"expectedStartTime": "2025-06-03T15:10:00Z"}'

В случае успеха вы увидите следующий JSON-ответ: 

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",
  "expectedStartTime": "2025-06-03T15:10:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
  "breakState": "BREAK_STATE_SCHEDULED",
}

Удалить объект AdBreak

Используйте метод DELETE , чтобы отменить решение о показе рекламы для рекламной паузы, созданной через API, до начала показа этой рекламной паузы.

Следующий пример запроса удаляет рекламную вставку: 

curl -X DELETE 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Authorization: Bearer OAUTH_TOKEN'

В случае успеха вы увидите ответ HTTP/1.1 200 OK .

Узнайте о расширенных функциях рекламных пауз.

После создания и управления рекламными паузами ознакомьтесь с следующими возможностями API DAI для создания рекламных пауз: