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

Search Ads 360 Reporting API'de arama raporlarının nasıl oluşturulacağını öğrenmek için aşağıdaki bölümleri okuyun.

Hizmet ara

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

SearchAds360Service, SearchStream ve Search olmak üzere iki arama yöntemi sağlayan bir birleşik nesne alma ve raporlama hizmetidir. Aramalar, Search Ads 360 Sorgu Dili ile yazılmış bir sorgu dizesinde geçirilir. Sorguları şu amaçlarla tanımlayabilirsiniz:

  • Nesnelerin belirli özelliklerini alın.
  • Bir tarih aralığına göre nesnelere ilişkin performans metriklerini alın.
  • Nesneleri özelliklerine göre sıralayın.
  • Hangi nesnelerin döndürüleceğini belirten koşulları kullanarak sonuçlarınızı filtreleyin
  • Döndürülen nesnelerin 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 aldığınızda API, id ve name alanları ayarlanmış bir kampanya nesnesi ve clicks alanı ayarlanmış bir metrics nesnesi içeren SearchAds360Row döndürür.

Arama yöntemleri

SearchStream

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

  • Veri paketleri, sonucun tamamı bir veri arabelleğinde önbelleğe alınarak hemen indirilmeye başlar.
  • Kodunuz, akışın tamamının tamamlanmasını beklemek zorunda kalmadan arabelleğe alınan verileri okumaya başlayabilir.
Search

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

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

Kullandığınız yöntem, API kota ve sınırlarınızı etkilemez: Tek bir sorgu veya rapor, sonuçların sayfalanmasına veya akışa alınmasından bağımsız olarak tek işlem olarak sayılır.

Örnek arama sorgusu

Bu örnek sorgu, kampanyaya göre bir hesabın son 30 güne ait performans verilerini, cihaza 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 yayınlamak için SearchAds360Service.SearchStream veya SearchAds360Service.Search arayüzüne bir customer_id ve query dizesi iletmeniz gerekir.

İstek, aşağıdaki URL'lerden herhangi birinde Search Ads 360 Reporting API sunucusuna bir HTTP POST yönlendirmesinden oluşur:

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

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

searchStream rapor tanımının bir HTTP POST isteği içinde yer aldığı tam örneği burada bulabilirsiniz:

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ıtları işleme

SearchAds360Service, SearchAds360Row nesne listesini döndürür.

Her SearchAds360Row, sorgu tarafından döndürülen bir nesneyi temsil eder. Her nesne, sorgunun SELECT yan tümcesinde istenen alanlara göre doldurulan bir dizi özellikten oluşur. SELECT yan tümcesinde yer almayan ö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ü, her bir yapıyı doğru şekilde kullanmak için ihtiyaç duyduğunuz tüm bilgileri içerir. Her kaynak için bir sayfa vardır, örneğin ad_group ve campaign. segments ve metrics sayfalarında, kullanılabilir tüm segmentler ve metrik alanları listelenir.

Bazı kaynaklar, segmentler ve metrikler uyumsuz olup bir arada kullanılamaz. Bazıları ise tamamen uyumludur ve birbirini tamamlar. Her kaynak sayfası, aşağıdaki bilgileri (varsa ve uygunsa) ve daha fazlasını içerir:

İlişkilendirilen kaynaklar

Bazı kaynaklarda, FROM ifadenizdeki kaynağın alanlarıyla birlikte ilgili kaynakları seçerek dolaylı olarak birleştirme seçeneğiniz olabilir. Örneğin, campaign kaynağı, ad_group kaynağının ilişkilendirilmiş bir kaynağıdır. Bu, FROM ifadenizde ad_group kullanırken sorgunuza campaign.id ve campaign.bidding_strategy_type gibi alanları ekleyebileceğiniz anlamına gelir.

İlişkilendirilmiş kaynaklar bölümünde, ilişkilendirilen kullanılabilir kaynaklar listelenir. Tüm kaynaklar ilişkilendirilmez.

Kaynak alanları sütunu

Kaynağın tüm alanları Kaynak alanları sütununa eklenir. Her kaynak 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 daha fazla ayrıntıya bağlantı verir.

Segmentler sütunu

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

Segmentler sütununda, kaynağın alanlarıyla aynı SELECT yantümcesinde kullanabileceğiniz segments alanları listelenir. Her alan; açıklama, kategori, veri türü, tür URL ve filtrelenebilir, seçilebilir, sıralanabilir ve tekrarlanan ayar dahil olmak üzere alanla ilgili tüm ayrıntılara bağlantı verir. FROM ifadenizdeki kaynağı kullanıyorsanız mevcut olmayan segmentleri filtrelemek için Evet/Hayır açılır listesini kullanabilirsiniz.

Metrikler sütunu

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

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

Kaynakları segmentlere ayırma

Bazı kaynaklarda, kaynak FROM ifadenizde yer aldığında seçebileceğiniz segmentlere ayırma kaynak alanları bulunur. Örneğin, campaign.name gibi bir campaign kaynak alanı seçerseniz FROM ibarenizde campaign_budget kullandığınızda campaign.resource_name otomatik olarak döndürülür ve segmentlere ayrılır. Bunun nedeni campaign, campaign_budget'ün segmentlere ayırma kaynağı olmasıdır.

Kaynakları segmentlere ayırma bölümünde, kullanılabilir segmentlere ayırma kaynakları listelenir. Tüm kaynaklarda segment oluşturma kaynakları bulunmaz.

Birlikte seçilebilir

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

segments sayfasında, her bir segments alanı için genişletilebilir bir Selectable with (genişletilebilir) bulunur. Bu alan, SELECT ibarenize ekleyebileceğiniz tüm uyumlu kaynak alanlarını, metrics alanlarını ve diğer segments alanlarını listeler.

Segmentasyon

Sorgunuzun SELECT yan tümcesine segments.FIELD_NAME alanı ekleyerek arama sonuçlarınızı segmentlere ayırabilirsiniz.

Örneğin, aşağıdaki sorguda bulunan segments.device komutu, FROM yan tümcesinde belirtilen kaynak için her cihazın impressions satırı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 mevcut segment alanlarının listesi için segments bölümüne bakın.

Birden çok segment

Sorgunuzun SELECT ifadesinde birden çok segment belirtebilirsiniz. Yanıt, FROM yan tümcesinde belirtilen ana kaynağın örneğini her bir kombinasyonu ve seçilen her segment alanının değeri için bir SearchAds360Row nesnesi içerir.

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

SELECT
  segments.ad_network_type
  segments.date
FROM campaign

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

Aşağıdaki örnek sorgu, campaign.status alanının her bir değeri için bir satır değil, 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

Her rapor başlangıçta FROM yan tümcesinde 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, otomatik olarak ad_group.resource_name değerini döndürür ve metrikleri dolaylı olarak ad_group düzeyinde segmentlere ayırmak için kullanır.

SELECT metrics.impressions
FROM ad_group

Döndürülen JSON dizesi şuna benzer:

{
  "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 tarih segmentleri

Bir tarih veya dönem belirtmek için WHERE ifadenizde temel tarih segmentlerini kullanabilirsiniz.

Şu 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ı, SELECT ifadenize alanı da eklemediğiniz sürece WHERE ifadenizde segmentler alanını kullanamayacağınız genel kurala istisnadır. Daha fazla bilgi edinmek için Yasaklanmış filtreleme bölümüne bakın.

Temel tarih segmenti kuralları:

  • WHERE ibarenizde temel tarih alanını, SELECT ibarenize dahil etmeden kullanabilirsiniz. Dilerseniz bu alanı her iki ifadeye de ekleyebilirsiniz.

    Bu örnek sorgu, tarih aralığı sırasında kampanya adına göre clicks metrikleri döndürür. SELECT yan tümcesine segments.date eklenmemesi gerektiğini unutmayın.

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

  • SELECT ibarenize temel tarih alanı eklerseniz WHERE ibarenizde sonlu bir tarih veya tarih aralığı belirtmeniz gerekir. SELECT ve WHERE yan tümcelerinde 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ış kampanya adına göre clicks metrikleri 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'

Dönem (segments.week, segments.month, segments.quarter) gerektiren temel tarih segmentleri için = operatörünü dönemin ilk günüyle birlikte kullanabilirsiniz. Örneğin:

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

Önceden tanımlanmış tarihler

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

Önceden tanımlanmış tarihler
TODAY Bugüne özel.
YESTERDAY Yalnızca dün.
LAST_7_DAYS Önceki 7 gün (bugün hariç).
LAST_BUSINESS_WEEK Önceki 5 günlük iş haftası (Pazartesi-Cuma).
THIS_MONTH Geçerli ayın tüm günleri.
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 günü 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şlayarak 7 günlük dönem.
LAST_WEEK_MON_SUN Önceki Pazartesi gününden başlayarak 7 günlük dönem.

Örnek:

WHERE segments.date DURING LAST_30_DAYS

Sıfır metrik

Bir sorgu yürütürken bazı varlıklar için sıfır değerine sahip metriklerle karşılaşabilirsiniz. Sorgularınızdaki sıfır metrikleri nasıl ele alacağınızı öğrenin.

BİLİNMEYEN enum türleri

Bir kaynak, UNKNOWN numaralandırma 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, yeni bir kampanya veya reklam Search Ads 360 kullanıcı arayüzünde tanıtılır, ancak sorguladığınız API sürümünde henüz desteklenmemektedir.

Bir kaynak UNKNOWN türünde olduğunda da metrik seçebilirsiniz ancak şunları aklınızda bulundurmanız gerekir:

  • UNKNOWN türündeki bir kaynak daha sonra desteklenebilir ancak süresiz olarak UNKNOWN olarak kalabilir.
  • Her zaman UNKNOWN türünde yeni nesneler görünebilir. Enum değeri zaten mevcut olduğundan bu nesneler geriye dönük olarak uyumludur. Hesabınızı doğru şekilde görebilmeniz için, bu değişiklikle birlikte kaynakları kullanıma sunduk. UNKNOWN kaynağı, hesabınızda diğer arayüzler üzerinden gerçekleşen yeni etkinlik veya bir kaynağın artık resmi olarak desteklenmemesi nedeniyle görünebilir.
  • UNKNOWN kaynaklarında sorgulayabileceğiniz ayrıntılı metrikler bulunabilir.
  • UNKNOWN kaynakları genellikle Search Ads 360 kullanıcı arayüzünde tamamen görünür.