Как использовать API рекламных пауз DAI

Google Dynamic Ad Insertion (DAI) Ad Break API позволяет создавать и управлять данными о времени и таргетинге рекламных пауз в прямых трансляциях.

В этом руководстве рассказывается, как использовать DAI Ad Break API для создания, изменения и удаления рекламной паузы в трансляции с динамической вставкой объявлений.

Требования

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

Как настроить доступ к API

Чтобы включить API, выполните следующие действия:

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

Как выполнить аутентификацию с помощью OAuth2

Чтобы авторизовать запросы к API, выполните следующие действия:

  1. Создайте токен доступа с областью действия https://www.googleapis.com/auth/video-ads.
  2. В каждый запрос к API включайте токен доступа в качестве значения HTTP-заголовка AuthorizationBearer. Подробнее о том, как вызывать API Google…

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

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

Если все пройдет успешно, вы увидите следующий токен доступа:

ya29.c.c0ASRK0GYUYU0...

Как отправить первый запрос

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

API для рекламных пауз при динамической вставке объявлений возвращает только объекты 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"
}

Как создать объект рекламной паузы

Чтобы сообщить 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"
}

Как изменить объект рекламной паузы

Чтобы изменить предстоящую рекламную паузу до начала принятия решения об объявлении, используйте метод 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.

Расширенные функции рекламных пауз

После создания рекламных пауз и управления ими изучите следующие функции DAI Ad Break API: