DAI reklam arası API'sini kullanma

Google Dinamik Reklam Ekleme (DAI) Reklam Arası API'si, canlı yayınlarınızdaki reklam aralarının zamanlamasını ve reklam hedefleme verilerini oluşturup yönetmenize olanak tanır.

Bu kılavuzda, Google DAI canlı yayın etkinliği için reklam arası oluşturmak, güncellemek ve silmek üzere DAI Reklam Arası API'sinin nasıl kullanılacağı açıklanmaktadır.

Ön koşullar

DAI reklam arası API'sini 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 içeren 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 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'sini 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 başlığı 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 Reklam Arası API 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. Manifest, kapsül segmenti isteği 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 öğesi 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 öğe oluşturmak için bekleyen AdBreak öğesini 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'da (UTC) 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 şeklindedir.

Bir AdBreak varlığını 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"
}

Bir AdBreak öğesini 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 Reklam Arası API'sinin aşağıdaki özelliklerini keşfedin: