Rapor Verilerini Sorgulama

reportData.query yöntemi, rapor verilerini almak için senkron bir yol sağlar. Dosya tabanlı raporlar (CSV veya Excel) oluşturan standart Reports hizmetinin aksine, bu yöntem yapılandırılmış JSON verilerini doğrudan yanıtta döndürür. Report kaynağını önceden tanımlama, oluşturma ve kaydetme ihtiyacını ortadan kaldırarak gerçek zamanlı veri alma ve keşfetme için idealdir.

Genel Bakış

Campaign Manager 360 raporlama verilerinizi sorgulamak için bu uç noktayı kullanma hakkında bilgi edinmek üzere bu kılavuzu inceleyin.

İsteği hazırlama

Boyutları, metrikleri, tarih aralığını, filtreleri ve sıralama ölçütlerini belirten bir ReportDataQueryRequest oluşturun.

REST

{
  "body": {
    "dateRange": "LAST_7_DAYS",
    "dimensionNames": [
      "advertiser",
      "campaign"
    ],
    "metricNames": [
      "impressions",
      "clicks"
    ],
    "sortBys": [
      {
        "name": "clicks",
        "sortOrder": "DESCENDING"
      }
    ],
    "maxResults": 100
  }
}
dateRange
Sorgu için zaman aralığını belirten bir DateRange nesnesi. Bu, özel bir tarih aralığı veya göreceli bir tarih aralığı olabilir.
dimensionNames
Gruplandırılacak standart boyut adlarının listesi.
metricNames
Zorunlu. Eklenecek standart metrik adlarının listesi.
dimensionFilters
Rapor verilerini filtrelemek için kullanılan DimensionValue nesnelerinin listesi. Bunu, sorgu sonuçlarını bir boyutun belirli değerleriyle kısıtlamak için kullanın.
sortBys
Boyutlar veya metrikler için sıralama yapılandırmaları. Her yapılandırma, alan adını ve bir sıralama düzenini içerir.
maxResults
Sayfa başına döndürülecek maksimum satır sayısı (varsayılan: 100, maksimum: 1000).

Sayfalara ayırma

maxResults alanı, tek bir yanıtta döndürülen sonuç sayısını kontrol eder. Örneğin, maxResults değerini 10 olarak ayarlarsanız API en fazla 10 sonuç döndürür. İsteğinizle eşleşen 10'dan az sonuç varsa API'nin 10'dan az sonuç döndürmesi mümkündür.

Ek sonuçlar varsa yanıtta nextPageToken yer alır. Sonraki sonuç sayfasını almak için aynı isteği pageToken alanı bu jetona ayarlanmış şekilde tekrar gönderin. Diğer tüm istek parametrelerini aynı tutun.

İsteği gönderin

reportdata/query uç noktasına bir HTTP POST isteği gönderin:

POST https://dfareporting.googleapis.com/dfareporting/v5/userprofiles/{profileId}/reportdata/query

İsteğinizin standart OAuth 2.0 kimlik bilgileri ve gerekli kapsamlarla kimliğinin doğrulandığından emin olun. Daha fazla bilgi için İstekleri Yetkilendirme başlıklı makaleyi inceleyin.

Başarılı yanıt

Başarılı bir sorgu, 200 OK, rows ve totalRow içeren bir JSON yüküyle HTTP 200 OK yanıtı döndürür.columnHeaders

{
  "columnHeaders": [
    { "name": "advertiser", "type": "DIMENSION" },
    { "name": "campaign", "type": "DIMENSION" },
    { "name": "impressions", "type": "METRIC" },
    { "name": "clicks", "type": "METRIC" }
  ],
  "rows": [
    {
      "values": [ "Test Advertiser", "Summer Campaign", "148672", "420" ]
    },
    {
      "values": [ "Test Advertiser", "Fall Campaign", "2159", "2" ]
    }
  ],
  "totalRow": {
    "values": [ "", "", "150831", "422" ]
  },
  "nextPageToken": "1234567890"
}
columnHeaders
Döndürülen alanların adı ve türleri (DIMENSION veya METRIC).
rows
Sorgu sonuçlarını içeren ReportDataRow nesnelerinin listesi. Her satırdaki dize değerleri, columnHeaders ile konuma göre hizalanır.
totalRow
Eşleşen tüm metriklerin toplamını temsil eden tek bir toplu satır. Toplanamayan boyut alanları ve metrikler (örneğin, uniqueReachTotalReach gibi erişim metrikleri) bu satırda boştur ("").
nextPageToken
Ek satırlar varsa bir sonraki sayfayı almak için sonraki bir istekte kullanılan jeton.

Gecikme ve zaman aşımları

Bu eşzamanlı bir uç nokta olduğundan sorgular hemen yürütülür ve veriler doğrudan yanıtta döndürülür (maxResults sayfalama sınırına kadar). Sorguların maksimum yürütme süresi 60 saniyedir. Bir sorgu bu sınırı aşarsa API işlemi sonlandırır ve HTTP 503 Service Unavailable hatası döndürür.

Bu hatayla karşılaşırsanız tarih aralığını daraltmayı, filtreleri daraltmayı (ör. belirli reklamverenlere veya kampanyalara göre filtreleme) ya da istenen boyut ve metrik sayısını azaltmayı deneyin. Alternatif olarak, indirilebilir bir rapor dosyası oluşturmak için reports.run kullanarak Report çalıştırın.

Sorgu sınırları ve kısıtlamaları

reportdata.query uç noktası, güvenilir yanıtlar sağlamak için çeşitli sınırlar uygular. Bu kısıtlamaları ihlal eden istekler HTTP 400 Bad Request yanıtıyla reddedilir.

Tarih aralığı sınırları

  • Özel tarih aralıklarında startDate, istenen rapor veri türü için verilerin kullanılabilir olduğu dönem içinde olmalıdır. Ayrıntılar için Veri kullanılabilirliği başlıklı makaleyi inceleyin.

Metrik ve boyut kısıtlamaları

  • metricNames içinde en az bir metrik sağlanmalıdır.
  • metricNames ve dimensionNames listelerindeki metrikler ve boyutlar benzersiz olmalıdır.
  • Yalnızca indirilebilir olarak etiketlenen metrikler ve boyutlar bu sorgularda kullanılamaz.

Kota sınırları

Bu uç noktaya yapılan istekler aşağıdaki kotaları kullanır:

  • Kullanıcı hız sınırı: Kullanıcı başına dakikada 120 istek (2 QPS)
  • Proje başına günlük sınır: Proje başına günlük 10.000 istek

Bu sınırları aşan istekler HTTP 429 Too Many Requests hatasıyla başarısız olur. Sonuçlar arasında sayfalandırma yaparsanız yeni bir sayfa için yapılan her istek (pageToken parametresi kullanılarak) ayrı bir sorgu olarak sayılır ve bu kotadan düşülür.