Search Ads 360 Reporting API'de arama raporları oluşturma

Search Ads 360 Reporting API'de arama raporları oluşturma hakkında bilgi edinmek için aşağıdaki bölümleri okuyun.

Arama hizmeti

Search Ads 360 Reporting API, arama ve raporlama için özel bir hizmet sunar.

SearchAds360Service iki arama yöntemi sağlayan birleşik bir nesne alma ve raporlama hizmetidir: SearchStream ve Search. Aramalar, Search Ads 360 sorgu dilinde yazılmış bir sorgu dizesiyle iletilir. Şu amaçlarla sorgular tanımlayabilirsiniz:

  • Nesnelerin belirli özelliklerini alma
  • Nesneler için tarih aralığına göre performans metriklerini alma.
  • Nesneleri özelliklerine göre sıralama
  • Hangi nesnelerin döndürüleceğini belirten koşulları kullanarak sonuçlarınızı filtreleme
  • Döndürülen nesne sayısını sınırlayın.

Her iki arama yöntemi de sorgunuzla eşleşen tüm satırları döndürür. Örneğin, campaign.id, campaign.name ve metrics.clicks değerlerini aldığınızda API, id ve name alanları ayarlanmış bir kampanya nesnesi içeren SearchAds360Row ve clicks alanı ayarlanmış bir metrics nesnesi döndürür.

Arama yöntemleri

SearchStream

Tek bir istek gönderir ve rapor boyutundan bağımsız olarak Search Ads 360 Reporting API ile kalıcı bir bağlantı başlatır.

  • Veri paketleri, sonuçların tamamı bir veri arabelleğinde önbelleğe alınarak hemen indirilmeye başlar.
  • Kodunuz, akışın tamamlanmasını beklemeden arabelleğe alınmış verileri okumaya başlayabilir.
Search

Raporun tamamını indirmek için birden fazla sayfalara ayrılmış istek gönderir.

SearchStream genellikle daha iyi performans sunar. Bunun nedeni, tek tek sayfaların istenmesi için gereken gidiş-dönüş ağ süresini ortadan kaldırmasıdır. 10.000'den fazla satır içeren tüm raporlar için SearchStream kullanmanızı öneririz. Daha küçük raporlar (<10.000 satır) için yöntemler arasında önemli bir performans farkı yoktur.

Kullandığınız yöntem, API kotalarınızı ve sınırlarınızı etkilemez: Sonuçların sayfalandırılmış veya aktarılmış olmasından bağımsız olarak tek bir sorgu ya da rapor tek bir işlem olarak sayılır.

Örnek arama sorgusu

Bu örnek sorgu, son 30 gün boyunca bir hesabın kampanyaya göre performans verilerini cihazlara göre segmentlere ayrılmış şekilde döndürür:

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

İstekte bulunun

İstek göndermek için SearchAds360Service.SearchStream veya SearchAds360Service.Search arayüzüne bir customer_id ve bir query dizesi iletmeniz gerekir.

İstek, aşağıdaki URL'lerden birinde Search Ads 360 Reporting API sunucusuna yapılan bir HTTP POST işleminden oluşur:

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream
 
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search

Aşağıda, HTTP POST isteğine eklenmiş searchStream rapor tanımının eksiksiz bir örneği verilmiştir:

POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1
Host: searchads360.googleapis.com
User-Agent: curl
Content-Type: application/json
Accept: application/json
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]

Parameters:
{
  "query" : "SELECT campaign.name, campaign.status, segments.device,
                    metrics.impressions, metrics.clicks, metrics.ctr,
                    metrics.average_cpc, metrics.cost_micros
            FROM campaign
            WHERE segments.date DURING LAST_30_DAYS"
}

Yanıt işleme

SearchAds360Service SearchAds360Row nesnelerinin listesini döndürür.

Her SearchAds360Row, sorgu tarafından döndürülen bir nesneyi temsil eder. Her nesne, sorgunun SELECT ifadesinde istenen alanlara göre doldurulan bir dizi özellikten oluşur. SELECT maddesine dahil edilmeyen özellikler, yanıttaki nesnelerde doldurulmaz.

Örneğin, aşağıdaki sorgu her SearchAds360Row nesnesini yalnızca campaign.id, campaign.name ve campaign.status ile doldurur. campaign.engine_id veya campaign.bidding_strategy_type gibi diğer özellikler atlanır.

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign

Referans belgeleri

Referans bölümünde, her yapıyı doğru şekilde kullanmak için ihtiyacınız olan tüm bilgiler yer alır. Her kaynak için bir sayfa vardır. Örneğin, ad_group ve campaign. segments ve metrics sayfalarında, mevcut tüm segmentler ve metrik alanları listelenir.

Bazı kaynaklar, segmentler ve metrikler uyumsuzdur ve birlikte kullanılamaz. Diğerleri ise tamamen uyumludur ve birbirini tamamlar. Her kaynak sayfasında aşağıdaki bilgiler (varsa ve uygunsa) ve daha fazlası yer alır:

İlişkilendirilen kaynaklar

Bazı kaynaklar için, alanlarını FROM ifadesindeki kaynak alanlarıyla birlikte seçerek ilgili kaynaklara örtülü olarak katılma seçeneğiniz olabilir. Örneğin, campaign kaynağı, ad_group kaynağının ilişkilendirilmiş bir kaynağıdır. Bu, FROM yan tümcenizde ad_group kullanırken sorgunuza campaign.id ve campaign.bidding_strategy_type gibi alanları ekleyebileceğiniz anlamına gelir.

Atfedilen kaynaklar bölümünde, kullanılabilir atfedilen kaynaklar listelenir. Tüm kaynakların ilişkilendirilmiş kaynakları yoktur.

Kaynak alanları sütunu

Kaynağın tüm alanları Kaynak alanları sütununa dahil edilir. Her kaynak alanı, alanla ilgili daha fazla ayrıntıya (açıklaması, kategorisi, veri türü, tür URL'si ve filtrelenebilir, seçilebilir, sıralanabilir ve tekrarlanan ayarı dahil) bağlanır.

Segmentler sütunu

Belirli bir kaynakla tüm segment alanları seçilemez.

Segmentler sütununda, kaynak alanlarıyla aynı SELECT ifadesinde kullanabileceğiniz segments alanları listelenir. Her alan, açıklama, kategori, veri türü, tür URL'si ve filtrelenebilir, seçilebilir, sıralanabilir ve tekrarlanan ayarı dahil olmak üzere alanla ilgili tüm ayrıntılara bağlanır. Kaynağı FROM maddenizde kullanıyorsanız kullanılamayan segmentleri filtrelemek için Evet/Hayır açılır listesini kullanabilirsiniz.

Metrik sütunu

Belirli bir kaynakla tüm metrik alanları seçilemez.

Metrikler sütununda, kaynağın alanlarıyla aynı SELECT ifadesinde kullanabileceğiniz metrics alanları listelenir. Her alan, açıklama, kategori, veri türü, tür URL'si ve filtrelenebilir, seçilebilir, sıralanabilir ve tekrarlanan ayarı dahil olmak üzere alanla ilgili tüm ayrıntılara bağlanır. FROM ifadesinde kaynağı kullanıyorsanız kullanılamayan metrikleri filtrelemek için Evet/Hayır açılır listesini kullanın.

Kaynakları segmentlere ayırma

Bazı kaynaklarda, kaynak FROM ifadesindeyken seçebileceğiniz segmentlere ayırma kaynak alanları bulunur. Örneğin, FROM ifadesinde campaign_budget kullanırken campaign gibi bir kaynak alanı (ör. campaign.name) seçerseniz campaign, campaign_budget öğesinin bir segmentleme kaynağı olduğundan campaign.resource_name otomatik olarak döndürülür ve segmentlere ayrılır.

Kaynakları segmentlere ayırma bölümünde, kullanılabilir kaynakları segmentlere ayırma araçları listelenir. Tüm kaynaklarda segmentasyon kaynakları bulunmaz.

Şununla seçilebilir:

Bazı segments alanları diğer kaynaklar, segmentler ve metriklerle uyumsuzdur.

segments sayfasında, SELECT koşulunuza ekleyebileceğiniz tüm uyumlu kaynak alanlarını, metrics alanlarını ve diğer segments alanlarını listeleyen her segments alanı için Şununla seçilebilir genişletilebilir alanı bulunur.

Segmentasyon

Sorgunuzun SELECT ifadesine bir segments.FIELD_NAME alanı ekleyerek arama sonuçlarınızı segmentlere ayırabilirsiniz.

Örneğin, aşağıdaki sorgudaki segments.device, FROM ifadesinde belirtilen kaynak için her cihazın impressions'ünü içeren bir raporla sonuçlanır.

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions
FROM campaign

SearchAds360Service.SearchStream tarafından döndürülen sonuçlar şu JSON dizesine benzer:

{
  "results":[
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"10922"
      },
      "segments":{
        "device":"MOBILE"
      }
    },
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"28297"
      },
      "segments":{
        "device":"DESKTOP"
      }
    },
    ...
  ]
}

Kullanabileceğiniz segment alanlarının listesi için segments başlıklı makaleyi inceleyin.

Birden çok segment

Sorgunuzun SELECT ifadesinde birden fazla segment belirtebilirsiniz. Yanıt, FROM ifadesinde belirtilen ana kaynağın örneğinin ve seçilen her segment alanının değerinin her kombinasyonu için bir SearchAds360Row nesnesi içerir.

Örneğin, aşağıdaki sorgu campaign, segments.ad_network_type ve segments.date kombinasyonlarının her biri için bir satır döndürür.

SELECT
  segments.ad_network_type
  segments.date
FROM campaign

Sonuçların, ana kaynağın her bir örneğine göre örtülü olarak segmentlere ayrıldığını ancak tek tek seçilen alanların değerlerine göre segmentlere ayrılmadığını unutmayın.

Aşağıdaki örnek sorgu, campaign.status alanının her bir farklı değeri için bir satır yerine kampanya başına bir satırla sonuçlanır.

SELECT
  campaign.status,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

Örtülü segmentasyon

Başlangıçta her rapor, FROM clause'da belirtilen kaynağa göre segmentlere ayrılır. Metrikler, bu kaynağın resource_name alanına göre segmentlere ayrılır.

Bu örnek sorgu, ad_group.resource_name değerini otomatik olarak döndürür ve ad_group düzeyindeki metrikleri segmentlere ayırmak için bu değeri örtülü olarak kullanır.

SELECT metrics.impressions
FROM ad_group

Döndürülen JSON dizesi aşağıdaki gibi görünür:

{
  "results":[
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/2222222222"
      },
      "metrics":{
        "impressions":"237"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/33333333333"
      },
      "metrics":{
        "impressions":"15"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/44444444444"
      },
      "metrics":{
        "impressions":"0"
      }
    }
  ]
}

Temel veri segmentleri

Bir tarih veya zaman aralığı belirtmek için WHERE ifadesinde temel tarih segmentlerini kullanabilirsiniz.

Aşağıdaki segment alanları temel tarih segmentleri olarak bilinir: segments.date, segments.week, segments.month, segments.quarter ve segments.year.

Bu örnek sorgu, son 30 güne ait kampanya clicks metriklerini döndürür.

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Temel tarih segmentleri alanları, WHERE ifadesine alanı da dahil etmediğiniz sürece SELECT ifadesinde bir segment alanı kullanamayacağınız şeklindeki genel kuralın istisnasıdır. Daha fazla bilgi için Yasaklanan filtreleme başlıklı makaleyi inceleyin.

Temel veri segmenti kuralları:

  • WHERE ifadesinde bir temel tarih alanı kullanabilirsiniz ancak bu alanı SELECT ifadesine dahil etmeniz gerekmez. İsterseniz alanı her iki maddede de kullanabilirsiniz.

    Bu örnek sorgu, tarih aralığı boyunca kampanya adına göre clicks metriklerini döndürür. segments.date öğesinin SELECT koşuluna dahil olmadığını unutmayın.

    SELECT
    campaign.name,
    metrics.clicks
FROM campaign
WHERE segments.date > '2022-02-01'
  AND segments.date < '2022-03-01'

  • SELECT ifadesine temel bir tarih alanı eklerseniz WHERE ifadesinde sonlu bir tarih veya tarih aralığı belirtmeniz gerekir. SELECT ve WHERE maddelerinde belirtilen alanların eşleşmesi gerekmez.

    Bu örnek sorgu, tarih aralığındaki tüm günler için aya göre segmentlere ayrılmış clicks metriklerini kampanya adına göre döndürür.

    SELECT
  campaign.name,
  metrics.clicks,
  segments.month
FROM campaign
WHERE segments.date > '2022-02-01'
  AND segments.date < '2022-03-01'

ISO 8601 tarihleri

Tarihleri ve tarih aralıklarını belirtmek için YYYY-MM-DD (ISO 8601) biçimini kullanabilirsiniz. Örneğin:

WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'

WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'

Bir zaman aralığı gerektiren temel tarih segmentleri (segments.week, segments.month, segments.quarter) için = operatörünü zaman aralığının ilk günüyle birlikte kullanabilirsiniz. Örneğin:

WHERE segments.month = '2022-06-01'

Önceden tanımlanmış tarihler

Ayrıca, aşağıdaki önceden tanımlanmış tarihleri ve tarih aralıklarını da kullanabilirsiniz:

Önceden tanımlanmış tarihler
TODAY Yalnızca bugün.
YESTERDAY Yalnızca dün.
LAST_7_DAYS Bugün hariç önceki 7 gün.
LAST_BUSINESS_WEEK Önceki 5 günlük iş haftası (Pazartesi-Cuma)
THIS_MONTH Geçerli aydaki tüm günler.
LAST_MONTH Önceki ayın tüm günleri.
LAST_14_DAYS Bugün hariç önceki 14 gün.
LAST_30_DAYS Bugün hariç önceki 30 gün.
THIS_WEEK_SUN_TODAY Önceki pazar ile geçerli gün arasındaki dönem.
THIS_WEEK_MON_TODAY Önceki pazartesi ile geçerli gün arasındaki dönem.
LAST_WEEK_SUN_SAT Önceki pazar gününden başlayan 7 günlük dönem.
LAST_WEEK_MON_SUN Önceki Pazartesi gününden başlayan 7 günlük dönem.

Örnek:

WHERE segments.date DURING LAST_30_DAYS

Sıfır metrik

Bir sorgu yürüttüğünüzde bazı öğeler için değeri sıfır olan metriklerle karşılaşabilirsiniz. Sorgularınızda sıfır metrikleri nasıl işleyeceğinizi öğrenin.

UNKNOWN sıralama türleri

Bir kaynak UNKNOWN enum veri türüyle döndürülürse bu, türün API sürümünde tam olarak desteklenmediği anlamına gelir. Bu kaynaklar başka arayüzler aracılığıyla oluşturulmuş olabilir. Örneğin, Search Ads 360 kullanıcı arayüzünde yeni bir kampanya veya reklam kullanıma sunulur ancak henüz sorguladığınız API sürümünde desteklenmez.

Bir kaynak UNKNOWN türüne sahip olduğunda metrik seçmeye devam edebilirsiniz ancak aşağıdakileri göz önünde bulundurmanız gerekir:

  • UNKNOWN türündeki bir kaynak daha sonra desteklenebilir ancak süresiz olarak UNKNOWN kalabilir.

  • UNKNOWN türündeki yeni nesneler herhangi bir zamanda görünebilir. Numaralandırma değeri zaten mevcut olduğundan bu nesneler geriye dönük olarak uyumludur. Hesabınızla ilgili doğru bir görünüm elde edebilmeniz için bu değişiklikle birlikte kullanıma sunulan kaynakları ekliyoruz. UNKNOWN kaynağı, hesabınızda diğer arayüzler üzerinden yapılan yeni etkinlikler nedeniyle veya bir kaynak artık resmi olarak desteklenmediği için görünebilir.

  • UNKNOWN kaynaklarına, sorgulayabileceğiniz ayrıntılı metrikler eklenmiş olabilir.

  • UNKNOWN kaynakları genellikle Search Ads 360 kullanıcı arayüzünde tamamen görünür.