DAI reklam arası API'sini kullanma

DAI Ad Break API, canlı yayınlarınızdaki reklam aralarının zamanlamasını ve reklam hedefleme verilerini oluşturmanıza ve yönetmenize olanak tanır.

Bu kılavuzda, Google Dinamik Reklam Ekleme (DAI) canlı yayın etkinliği için reklam arası oluşturmak, güncellemek ve silmek üzere DAI Ad Break API'nin kullanılması ele alınmaktadır.

Ön koşullar

DAI Ad Break API'yi kullanmak için aşağıdakilere ihtiyacınız vardır:

  • admanagervideo.googleapis.com hizmetinin etkin olduğu bir Google Cloud projesi. Daha fazla bilgi için Cloud projesi oluşturma başlıklı makaleyi inceleyin.
  • Google DAI canlı yayın etkinliği olan bir Google Ad Manager ağı. Daha fazla bilgi için DAI için canlı yayın oluşturma başlıklı makaleyi inceleyin.

API erişimini ayarlama

API'yi etkinleştirmek için aşağıdaki adımları tamamlayın:

  1. Hizmet hesabı oluşturun. Daha fazla bilgi için Hizmet hesabı oluşturma başlıklı makaleyi inceleyin.
  2. Hizmet hesabını Google Ad Manager ağınıza ekleyin. Daha fazla bilgi için API erişimi için bir hizmet hesabı kullanıcısı ekleme başlıklı makaleyi inceleyin.
  3. Hizmet hesabı e-posta adresini ve Google Ad Manager ağ kodunuzu Google Hesap Yöneticinize iletin.
  4. Google Cloud projenizde Google Ad Manager Video API'yi etkinleştirin. Daha fazla bilgi için Uygulamanızda "API'ler ve Hizmetler"i etkinleştirme başlıklı makaleyi inceleyin.

OAuth2 ile kimlik doğrulama

API isteklerinizi yetkilendirmek için aşağıdaki adımları uygulayın:

  1. https://www.googleapis.com/auth/video-ads kapsamıyla erişim jetonunu oluşturun.
  2. Her isteğe, API'ye erişim jetonunu Authorization HTTP üstbilgisi Bearer değeri olarak ekleyin. Daha fazla bilgi için Google API'lerini çağırma başlıklı makaleyi inceleyin.

Aşağıdaki örnekte, DAI Ad Break API'nin kapsamıyla bir OAuth jetonu oluşturulmaktadır:

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

Başarılı olursa aşağıdaki erişim jetonunu görürsünüz:

ya29.c.c0ASRK0GYUYU0...

İlk isteği gönderme

Bir canlı yayın etkinliğinin reklam aralarını almak için etkinliğin sistem tarafından oluşturulan öğe anahtarına veya özel öğe anahtarınıza göre tüm GET öğelerini listelemek için AdBreak yöntemini kullanın.

DAI Reklam Arası API'si yalnızca API aracılığıyla oluşturulan AdBreak öğelerini döndürür. Manifestten, kapsül segmenti isteğinden veya kapsül manifesti isteğinden oluşturulan reklam araları hariçtir.

Aşağıdaki örnek istekte, AdBreak öğeleri assetKey değerine göre listelenmektedir:

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"

İşlem başarılı olursa aşağıdaki JSON yanıtını görürsünüz:

{
 "adBreaks": []
}

API aracılığıyla ek AdBreak öğeleri oluşturup listeyi istediğinizde aşağıdaki JSON yanıtını görürsünüz:

{
 "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 varlığı oluşturma

Google DAI'yi canlı yayın etkinliğindeki yaklaşan reklam arası hakkında bilgilendirmek için POST yöntemini kullanın.

  • Yeni bir AdBreak öğesi oluşturmak için önceki öğenin BREAK_STATE_COMPLETE durumuna geçmesini beklemeniz gerekir.
  • Alternatif olarak, yeni bir AdBreak öğesi oluşturmak için bekleyen öğeyi silebilirsiniz.
  • Tek bir canlı yayın etkinliği için birden fazla AdBreak öğesi oluşturmak istiyorsanız gelişmiş yapılandırma için hesap yöneticinizle iletişime geçin.

Aşağıdaki örnek istek, 3 Haziran 2025'te saat 15:00:00 UTC'de başlaması beklenen bir reklam arası oluşturur:

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"
  }'

İşlem başarılı olursa aşağıdaki JSON yanıtını görürsünüz:

{
  "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",
}

Sonuç, reklam arasını almak, değiştirmek veya silmek için gereken reklam arası kimliğini içerir. Örnek yanıtta, oluşturulan reklam arası kimliği bcc402a6-9880-4b8b-8e4a-a8cd3688f854'dır.

AdBreak öğesini alma

Reklam arası durumu ve zamanlama meta verileri de dahil olmak üzere belirli bir AdBreak öğesinin ayrıntılarını almak için GET yöntemini kullanın.

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'

İşlem başarılı olursa aşağıdaki JSON yanıtını görürsünüz:

{
  "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 varlığını güncelleme

Yaklaşan bir reklam arasını reklam kararı başlamadan önce değiştirmek için PATCH yöntemini kullanın:

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"}'

İşlem başarılı olursa aşağıdaki JSON yanıtını görürsünüz:

{
  "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 öğesini silme

Reklam arası yayınlanmaya başlamadan önce API aracılığıyla oluşturulan bir reklam arası için reklam kararını iptal etmek üzere DELETE yöntemini kullanın.

Aşağıdaki örnek istek, bir reklam arasını siler:

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

Başarılı olursa HTTP/1.1 200 OK yanıtını görürsünüz.

Gelişmiş reklam arası özellikleri hakkında bilgi

Reklam araları oluşturup yönetme işleminden sonra DAI Ad Break API'nin aşağıdaki özelliklerini keşfedin: