YouTube Reporting API - System-Managed Reports

YouTube, İçerik Stüdyosu'nda ilgili raporlara erişimi olan içerik sahipleri için otomatik olarak bir dizi sistem tarafından yönetilen reklam geliri raporu oluşturur. Bu raporlar, YouTube İçerik Stüdyosu'nun Raporlar menüsünde erişilebilen manuel olarak indirilebilir raporlarda da bulunan verilere programatik erişim sağlamak için tasarlanmıştır.

Not: API, İçerik Stüdyosu'ndan farklı bir rapor grubuna erişim sağlar ancak benzer veriler içerir. API raporları farklı alanlara sahip olabilir ve ayrıca İçerik Stüdyosu raporlarından farklı alan adları kullanabilir.

YouTube sistem tarafından yönetilen raporları otomatik olarak oluşturduğundan bu raporları alma işlemi, API ile kullanılabilen YouTube Analytics toplu veri raporlarından farklıdır.

Raporlar alınıyor

Aşağıdaki adımlarda, sistem tarafından yönetilen raporların API üzerinden nasıl alınacağı açıklanmaktadır.

1. Adım: Yetkilendirme kimlik bilgilerini alın

Tüm YouTube Reporting API istekleri yetkilendirilmelidir. Yetkilendirme kılavuzu'nda, yetkilendirme jetonlarını almak için OAuth 2.0 protokolünün nasıl kullanılacağı açıklanmaktadır.

YouTube Reporting API istekleri aşağıdaki yetkilendirme kapsamlarını kullanır:

Kapsamlar
https://www.googleapis.com/auth/yt-analytics.readonly YouTube içeriğinize ilişkin YouTube Analytics raporlarını görüntüleyin. Bu kapsam, görüntüleme sayısı ve puan sayısı gibi kullanıcı etkinliği metriklerine erişim sağlar.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly YouTube içeriğinize ilişkin YouTube Analytics mali raporlarını görüntüleyin. Bu kapsam, kullanıcı etkinliği metriklerinin yanı sıra tahmini gelir ve reklam performansı metriklerine erişim sağlar.

2. Adım: İstenen rapor için iş kimliğini alın

Sistem tarafından yönetilen işlerin listesini almak için jobs.list yöntemini çağırın. includeSystemManaged parametresini true olarak ayarlayın.

Döndürülen her bir Job kaynağındaki reportTypeId özelliği, söz konusu işle ilişkilendirilmiş, sistem tarafından yönetilen raporun türünü tanımlar. Uygulamanız, aşağıdaki adımda aynı kaynaktan id özellik değerine sahip olmalıdır.

Raporlar dokümanında; kullanılabilir raporlar, bunların rapor türü kimlikleri ve içerdikleri alanlar listelenir. Desteklenen rapor türlerinin listesini almak için reportTypes.list yöntemini de kullanabilirsiniz.

3. Adım: Raporun indirme URL'sini alın

İş için oluşturulan raporların listesini almak üzere jobs.reports.list yöntemini çağırın. İstekte, jobId parametresini almak istediğiniz raporun iş kimliğine ayarlayın.

Rapor listesini aşağıdaki parametrelerin herhangi birini veya tümünü kullanarak filtreleyebilirsiniz:

  • API'nin yalnızca belirli bir süre sonra oluşturulan raporları döndürmesi gerektiğini belirtmek için createdAfter parametresini kullanın. Bu parametre, API'nin yalnızca henüz işlemediğiniz raporları döndürmesini sağlamak için kullanılabilir.

  • API yanıtının yalnızca rapordaki en erken veriler belirtilen tarihten önce olması durumunda rapor içermesi gerektiğini belirtmek için startTimeBefore parametresini kullanın. createdAfter parametresi raporun oluşturulduğu saatle, bu tarih ise rapordaki verilerle ilgilidir.

  • API yanıtının yalnızca rapordaki en erken veriler belirtilen tarihte veya daha sonra olduğunda rapor içermesi gerektiğini belirtmek için startTimeAtOrAfter parametresini kullanın. startTimeBefore parametresinde olduğu gibi bu parametre değeri de raporun oluşturulduğu zamana değil, rapordaki verilere karşılık gelir.

API yanıtında bu iş için Report kaynağın listesi yer alır. Her kaynak, benzersiz bir döneme ait verileri içeren bir raporu ifade eder.

  • Kaynağın startTime ve endTime özellikleri, rapor verilerinin kapsadığı dönemi tanımlar.
  • Kaynağın downloadUrl özelliği, raporun getirilebileceği URL'yi tanımlar.

  • Kaynağın createTime özelliği, raporun oluşturulduğu tarih ve saati belirtir. Uygulamanız bu değeri depolamalı ve daha önce indirilen raporların değişip değişmediğini belirlemek için kullanmalıdır.

4. Adım: Raporu indirin

Raporu almak için 4. adımda elde edilen downloadUrl adresine bir HTTP GET isteği gönderin.

Raporları işleme

En iyi uygulamalar

YouTube Reporting API'yi kullanan uygulamalar her zaman aşağıdaki uygulamalara uymalıdır:

  • Rapordaki sütunların sıralamasını belirlemek için raporun başlık satırını kullanın. Örneğin, görüntülemelerin, yalnızca rapor açıklamasında listelenen ilk metrik olduğu için bir raporda döndürülen ilk metrik olacağını varsaymayın. Bunun yerine, hangi sütunun bu verileri içerdiğini belirlemek için raporun başlık satırını kullanın.

  • Aynı raporun tekrar tekrar işlenmesini önlemek için indirdiğiniz raporların kaydını tutun. Aşağıdaki listede bunu yapmanın birkaç yolu önerilmiştir.

    • reports.list yöntemini çağırırken, yalnızca belirli bir tarihten sonra oluşturulan raporları almak için createdAfter parametresini kullanın. (Raporları ilk kez alırken createdAfter parametresini atlayın.)

      Raporları alıp başarılı bir şekilde işlediğinizde, bu raporların en yenisinin oluşturulduğu tarih ve saate karşılık gelen zaman damgasını saklayın. Ardından, API'yi her çağırdığınızda reports.list yöntemine yapılan her bir ardışık çağrıda createdAfter parametre değerini güncelleyerek yalnızca yeni raporları (ör. dolgulu verilere sahip yeni raporlar dahil) aldığınızdan emin olun.

      Bir raporu almadan önce, bir önlem olarak rapor kimliğinin veritabanınızda listelenip listelenmediğini de kontrol edin.

    • İndirdiğiniz ve işlediğiniz her rapor için ID değerini depolayın. Ayrıca, her raporun oluşturulduğu tarih ve saat veya raporun veri içerdiği dönemi tanımlayan startTime ve endTime gibi ek bilgileri de saklayabilirsiniz. Her bir rapor 24 saatlik bir süreye ait verileri içerdiğinden, YouTube Analytics için toplu veriler alan raporlarda büyük olasılıkla çok sayıda rapor olacaktır. Daha uzun dönemleri kapsayan, sistem tarafından yönetilen işler daha az rapora sahip olur.

      Hâlâ indirmeniz ve içe aktarmanız gereken raporları tanımlamak için rapor kimliğini kullanın. Bununla birlikte, iki yeni rapor aynı startTime ve endTime mülk değerlerine sahipse raporu yalnızca daha yeni olan createTime değeriyle içe aktarın.

Rapor özellikleri

API raporları, aşağıdaki özelliklere sahip .csv (virgülle ayrılmış değerler) dosyalarıdır:

  • Her rapor, raporun başlangıç tarihinde Pasifik saatiyle 00:00'dan raporun bitiş tarihinde Pasifik saatine göre 23:59'a kadar süren benzersiz bir döneme ait verileri içerir.

  • Rapor verileri sıralanmadı.