LiveBroadcasts: cuepoint

Canlı yayına işaret noktası ekler. İşaret noktası bir reklam arasını tetikleyebilir.

Not: Bu yöntem, isteklerin YouTube İçerik Sahibi ile ilişkili bir hesap tarafından yetkilendirilmesini gerektiren liveCuepoints.insert yönteminin yerini alır. Bu yöntem aynı yetkilendirme şartına sahip değildir.

İstek

HTTP isteği

POST https://www.googleapis.com/youtube/v3/liveBroadcasts/cuepoint

Yetkilendirme

Bu istek, aşağıdaki kapsamlardan en az biriyle yetkilendirme gerektirir (kimlik doğrulama ve yetkilendirme hakkında daha fazla bilgi).

Kapsam
https://www.googleapis.com/auth/youtube
https://www.googleapis.com/auth/youtube.force-ssl
https://www.googleapis.com/auth/youtubepartner

Parametreler

Aşağıdaki tabloda, bu sorgunun desteklediği parametreler listelenmiştir. Listelenen parametrelerin tümü sorgu parametreleridir.

Parametreler
Gerekli parametreler
id string
id parametresi, işaret noktasının eklendiği yayını tanımlar. İşaret noktası eklenirken yayın etkin bir şekilde oynatılmalıdır.
İsteğe bağlı parametreler
onBehalfOfContentOwner string
Bu parametre yalnızca düzgün bir yetkili istekte kullanılabilir.
Not: Bu parametre yalnızca birçok farklı YouTube kanalının sahibi ve yöneticisi olan YouTube içerik iş ortakları için tasarlanmıştır. İçerik sahiplerinin, her bir bağımsız kanal için farklı kimlik doğrulama bilgileri sağlamak zorunda kalmadan, bir kez kimlik doğrulaması yapmasını ve parametre değerinde belirtilen kanal adına işlem gerçekleştirmesini sağlar. Kullanıcının kimlik doğrulaması yaptığı hesap, belirtilen YouTube içerik sahibine bağlanmalıdır.
onBehalfOfContentOwner parametresi, isteğin yetkilendirme kimlik bilgilerinin, parametre değerinde belirtilen YouTube İçerik Sahibi adına hareket eden bir YouTube kullanıcısını tanımladığını gösterir. Bu parametre, birçok farklı YouTube kanalına sahip ve bunları yöneten YouTube içerik iş ortakları için tasarlanmıştır.
onBehalfOfContentOwnerChannel string
Bu parametre yalnızca düzgün bir yetkili istekte kullanılabilir.
Not: Bu parametre yalnızca birçok farklı YouTube kanalının sahibi ve yöneticisi olan YouTube içerik iş ortakları için tasarlanmıştır. Bu sayede içerik sahipleri, bağımsız her kanal için kimlik doğrulama bilgileri sağlamak zorunda kalmadan, parametre değerinde belirtilen kanal adına bir kez kimlik doğrulaması yapabilir ve işlem gerçekleştirebilir.
onBehalfOfContentOwnerChannel parametresi, işaret noktasının eklendiği yayınla ilişkili kanalın YouTube kanal kimliğini belirtir. Bu parametre, bir istek onBehalfOfContentOwner parametresi için bir değer belirttiğinde gereklidir ve yalnızca bu parametreyle birlikte kullanılabilir. Aşağıdaki şartlar da geçerlidir:
  • İstek, onBehalfOfContentOwner parametresinin belirttiği içerik sahibine bağlı kullanıcı hesabıyla yetkilendirilmelidir.
  • onBehalfOfContentOwnerChannel parametre değerinin belirttiği kanal, onBehalfOfContentOwner parametresinin belirttiği içerik sahibine bağlanmalıdır.

İstek metni

İstek gövdesinde bir cuepoint kaynağı sağlayın. Aşağıdaki JSON yapısı, bir cuepoint kaynağının biçimini gösterir:

{
    "id": string,
    "insertionOffsetTimeMs": long,
    "walltimeMs": datetime,
    "durationSecs": unsigned integer,
    "cueType": string
  }
İstek gövdesinde cueType alanı zorunludur ve cueTypeAd olarak ayarlanmalıdır. Ayrıca, bu özellikler için değerleri de ayarlayabilirsiniz:
  • durationSecs
  • insertionOffsetTimeMs (walltimeMs ayarlanmışsa ayarlanmalıdır)
  • walltimeMs (insertionOffsetTimeMs ayarlanmışsa ayarlanmalıdır)

Özellikler

Aşağıdaki tabloda, bu kaynakta görünen özellikler tanımlanmaktadır:

Özellikler
id string
YouTube'un işaret noktasını benzersiz şekilde tanımlamak için atadığı değer. Bu değerin, yayını tanımlayan gerekli id parametresinden farklı olduğunu unutmayın. İşaret noktası ekleme isteği gönderirken bu değer atlanabilir. Değer, API yanıtında doldurulur.
insertionOffsetTimeMs long
Özellik değeri, işaret noktasının eklenmesi gereken süreyi milisaniye cinsinden tanımlar. Değer, izleme akışının başından ölçülür ve varsayılan değeri olan 0, işaret noktasının mümkün olan en kısa sürede eklenmesi gerektiğini gösterir. Yayınınızın izleme akışı yoksa bu parametre için bir değer belirtmemelisiniz.

milisaniye cinsinden ölçülen değer aslında yaklaşık bir değerdir ve YouTube, işaret noktasını bu zamana mümkün olduğunca yakın yerleştirir.

Bu alan için sıfır olmayan değerler yalnızca yayın akışının gecikmesi varsa desteklenir. Yayın yayınınız gecikmezse geçerli tek değer 0 olur. Daha fazla bilgi için Başlangıç kılavuzuna bakın.

Not: Yayınınızın bir test aşaması varsa ofset, test aşamasının başladığı andan itibaren ölçülür.

İstek, bu özellik ve walltimeMs özelliği için bir değer belirten işaret noktası eklemeye çalışırsa API bir hata döndürür.
walltimeMs integer
Özellik değeri, işaret noktasının eklenmesi gereken duvar saati saatini belirtir. Değer, bir zaman damgasını (milisaniye cinsinden) temsil eden bir tam sayıdır.

Bir istek, bu özellik ve insertionOffsetTimeMs özelliği için bir değer belirten bir işaret noktası eklemeye çalışırsa hata döndürür.
durationSecs unsigned integer
İşaret noktasının saniye cinsinden süresi. Değer pozitif bir tam sayı olmalıdır. Varsayılan değer: 30.
cueType string
İşaret noktasının türü. Özellik değeri cueTypeAd olarak ayarlanmalıdır.

Yanıt

Başarılı olursa bu yöntem, yanıt gövdesine eklenen cuepoint kaynağını döndürür.

Hatalar

Aşağıdaki tabloda, API'nin bu yönteme yapılan bir çağrıya yanıt olarak döndürdüğü hata mesajları tanımlanmaktadır. Hata mesajı dokümanları, Live Streaming API'nin döndürebileceği tüm hataları tanımlar.

Hata türü Hata ayrıntısı Açıklama
insufficientPermissions (403) insufficientLivePermissions Bu isteğin, canlı yayına işaret noktası ekleme yetkisi yok.
insufficientPermissions (403) liveStreamingNotEnabled İsteği yetkilendiren kullanıcı, YouTube'da canlı video akışı gerçekleştiremez. Kullanıcı, https://support.google.com/youtube/answer/2474026 ve https://www.youtube.com/features adresinden daha fazla bilgi edinebilir.
rateLimitExceeded (403) userRequestsExceedRateLimit Kullanıcı, belirli bir zaman diliminde çok fazla istek gönderdi.
required (400) idRequired Gerekli id parametresi, işaret noktası eklemek istediğiniz yayını tanımlamalıdır.
required (400) cueTypeRequired API alanının gövdesinde zorunlu cueType alanı belirtilmelidir.
notFound (404) liveBroadcastNotFound id parametresi tarafından belirtilen yayın mevcut değil.
invalidValue (400) conflictingTimeFields Yalnızca bir insertionOffsetTimeMs ve walltimeMs belirtilebilir. Her iki değerin de ayarlanması hataya neden olur. İki değeri de ayarlamazsanız YouTube, varsayılan insertionOffsetTimeMs zamanını (0) kullanır. Böylece, işaret noktası en kısa sürede eklenir.
invalidValue (400) invalidInsertionOffsetTimeMs cuepoint kaynağı, insertionOffsetTimeMs özelliği için geçersiz bir değer belirtti. Değer 0 veya pozitif bir tam sayı olmalıdır.
invalidValue (400) invalidWalltimeMs cuepoint kaynağı, walltimeMs özelliği için geçersiz bir değer belirtti. Değer, dönem zaman damgasını (milisaniye cinsinden) temsil eden bir tam sayı olmalıdır.
backendError (5xx) serviceUnavailable Hizmet kullanılamıyor. Birkaç dakika sonra isteğinizi tekrar deneyin.

Deneyin.

Bu API'yi çağırmak ve API isteği ile yanıtını görmek için APIs Explorer kullanın.