Yeni Search Ads 360 Reporting API kullanıma sunuldu. Yaklaşan geliştirmeler ve sürümlerden haberdar olmak için searchads-api-announcements Google grubuna katılın.

Bu sayfa, Cloud Translation API ile çevrilmiştir.

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

Search Ads 360 Reporting API'de arama raporlarını nasıl oluşturacağınızı öğrenmek 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, SearchStream ve Search olmak üzere iki arama yöntemi sunan birleşik bir nesne alma ve raporlama hizmetidir. Aramalar, Search Ads 360 Sorgu Dili'nde yazılmış bir sorgu dizesinde iletilir. Sorguları şu amaçlarla tanımlayabilirsiniz:

Nesnelerin belirli özelliklerini alma.
Tarih aralığına göre nesnelerin performans metriklerini alma
Nesneleri özelliklerine göre sıralama
Hangi nesnelerin döndürüleceğini belirten koşulları kullanarak sonuçlarınızı filtreleyin
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 nesnesini ve clicks alanı ayarlanmış bir metrics nesnesini içeren bir SearchAds360Row 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, sonucun tamamı bir veri arabelleğine önbelleğe alınarak hemen indirilmeye başlar.
Kodunuz, aktarımın tamamının bitmesini beklemek zorunda kalmadan arabelleğe alınan verileri okumaya başlayabilir.

Search

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

SearchStream, bağımsız sayfaları istemek için gereken ağ gidiş dönüş 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 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: Tek bir sorgu veya rapor, sonuçların sayfaya ayrılmış veya akış şeklinde sunulup sunulmadığına bakılmaksızın bir işlem olarak sayılır.

Örnek arama sorgusu

Bu örnek sorgu, bir hesabın son 30 gün içindeki performans verilerini kampanyaya göre, cihaza göre segmentlere ayrılmış olarak 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 gönderilen bir HTTP POST'den 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, bir HTTP POST isteğine searchStream eklenmesi gereken 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ıtları 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 yan tümcesinde istenen alanlara göre doldurulan bir özellik grubundan oluşur. SELECT yan tümcesine 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 (ör. 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. Bazıları ise tamamen uyumludur ve birbirini tamamlar. Her kaynak sayfasında aşağıdaki bilgiler (mevcutsa ve uygunsa) ve daha fazlası yer alır:

İlişkilendirilen kaynaklar

Bazı kaynaklarda, FROM yan tümcenizdeki kaynağın alanlarıyla birlikte ilgili kaynakların alanlarını seçerek ilgili kaynakları 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 yan tümcesinde ad_group kullanırken sorgunuza campaign.id ve campaign.bidding_strategy_type gibi alanları dahil edebileceğiniz anlamına gelir.

Özellik atanmış kaynaklar bölümünde, mevcut özellik atanmış kaynaklar listelenir. Tüm kaynaklar ilişkilendirilmiş kaynaklara sahip değildir.

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çıklama, kategori, veri türü, tür URL'si, filtrelenebilir, seçilebilir, sıralanabilir ve yinelenen ayar) bağlantı verir.

Segmentler sütunu

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

Segmentler sütununda, kaynaktaki alanlarla aynı SELECT yan tümcesinde kullanabileceğiniz segments alanları listelenir. Her alan, açıklaması, kategorisi, veri türü, tür URL'si ve filtrelenebilir, seçilebilir, sıralanabilir ve yinelenen ayarı dahil olmak üzere alanla ilgili tüm ayrıntılara bağlantı verir. Kaynağı FROM yan tümcenizde kullanıyorsanız kullanılamayan segmentleri filtrelemek için Evet/Hayır açılır menüsünü kullanabilirsiniz.

Metrikler sütunu

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

Metrikler sütununda, kaynaktaki alanlarla aynı SELECT yan tümcesinde kullanabileceğiniz metrics alanları listelenir. Her alan, açıklaması, kategorisi, veri türü, tür URL'si ve filtrelenebilir, seçilebilir, sıralanabilir ve yinelenen ayarı dahil olmak üzere alanla ilgili tüm ayrıntılara bağlantı verir. Kaynağı FROM yan tümcenizde kullanıyorsanız kullanılamayan metrikleri filtrelemek için Evet/Hayır açılır menüsünü kullanın.

Kaynakları segmentlere ayırma

Bazı kaynaklarda, kaynak FROM yan tümcenizdeyken seçebileceğiniz segmentlere ayırma kaynak alanları bulunur. Örneğin, campaign.name gibi bir campaign kaynak alanı seçerseniz FROM ifadenizde campaign_budget kullanıldığında campaign, campaign_budget'nin segmentlere ayırma kaynağı olduğundan campaign.resource_name otomatik olarak döndürülür ve segmentlere ayrılır.

Segmentasyon kaynakları bölümünde, kullanılabilir segmentasyon kaynakları listelenir. Tüm kaynaklarda segmentasyon kaynakları yoktur.

Şunlarla seçilebilir:

Bazı segments alanları diğer kaynaklar, segmentler ve metriklerle uyumlu değildir.

segments sayfasında, her segments alanı için SELECT yan tümceğinize dahil edebileceğiniz tüm uyumlu kaynak alanları, metrics alanları ve diğer segments alanlarını listeleyen bir Şu alanlarla kullanılabilir genişletilebilir alanı bulunur.

Segmentasyon

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

Örneğin, aşağıdaki sorguda segments.device, FROM yan tümcesinde belirtilen kaynak için her cihazın impressions değerinin yer aldığı bir rapor oluşturur.

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

SearchAds360Service.SearchStream tarafından döndürülen sonuçlar aşağıdaki 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 yan tümcesinde birden fazla segment belirtebilirsiniz. Yanıt, FROM yan tümcesinde belirtilen ana kaynağın örnek değerinin her kombinasyonu için bir SearchAds360Row nesnesi ve seçilen her segment alanının değerini 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 alanların değerlerine göre değil, ana kaynağın her örneğine göre dolaylı olarak segmentlere ayrıldığını unutmayın.

Aşağıdaki örnek sorgu, campaign.status alanının her farklı değeri için bir satır değil, kampanya başına bir satır döndürü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, 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 dolaylı 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 tarih segmentleri

Bir tarih veya dönem belirtmek için WHERE ifadenizde 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ün için clicks kampanya 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 segmenti alanları, alanı SELECT yan tümceğinize de eklemediğiniz sürece WHERE yan tümceğinizde bir segment alanı kullanamayacağınız genel kuralın istisnalarıdır. Daha fazla bilgi için Yasaklanmış filtreleme başlıklı makaleyi inceleyin.

Temel tarih segmenti kuralları:

Temel bir tarih alanını SELECT yan tümceğinize dahil etmeden WHERE yan tümceğinizde kullanabilirsiniz. İsterseniz alanı her iki yan tümceyle de ilişkilendirebilirsiniz.

Bu örnek sorgu, tarih aralığında kampanya adına göre clicks metriklerini döndürür. segments.date değerinin SELECT koşuluna dahil edilmediğini unutmayın.
```
SELECT
    campaign.name,
    metrics.clicks
FROM campaign
WHERE segments.date > '2022-02-01'
  AND segments.date < '2022-03-01'
```
SELECT yan tümceğinize temel bir tarih alanı eklersanız WHERE yan tümceğinize 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 kampanya adına göre ay bazında segmentlere ayrılmış clicks metriklerini 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 gerektiren temel tarih segmentleri (segments.week, segments.month, segments.quarter) 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`	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`	Mevcut 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 ile mevcut gün arasındaki dönem.
`THIS_WEEK_MON_TODAY`	Önceki pazartesi ile mevcut gün arasındaki dönem.
`LAST_WEEK_SUN_SAT`	Önceki pazar gününden itibaren 7 günlük dönem.
`LAST_WEEK_MON_SUN`	Önceki pazartesiden itibaren 7 günlük dönem.

Örnek:

WHERE segments.date DURING LAST_30_DAYS

Sıfır metrikler

Bir sorgu yürüttüğünüzde bazı öğeler için sıfır değerine sahip metriklerle karşılaşabilirsiniz. Sorgularınızda sıfır metrikleri nasıl işleyeceğiniz hakkında bilgi edinin.

UNKNOWN enum 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 diğer arayüzler üzerinden oluşturulmuş olabilir. Örneğin, Search Ads 360 kullanıcı arayüzünde yeni bir kampanya veya reklam kullanıma sunulur ancak sorgu yaptığınız API sürümünde henüz desteklenmemektedir.

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

UNKNOWN türüne sahip bir kaynak daha sonra desteklenebilir ancak süresiz olarak UNKNOWN olarak kalabilir.
UNKNOWN türüne sahip yeni nesneler herhangi bir zamanda görünebilir. Numaralandırma değeri zaten mevcut olduğundan bu nesneler geriye dönük uyumludur. Hesabınızın doğru bir görünümüne sahip olmanız için bu değişiklikle birlikte, kullanıma sunulduğunda kaynakları tanıtıyoruz. UNKNOWN kaynağı, hesabınızda diğer arayüzler üzerinden yapılan yeni işlemler veya bir kaynağın artık resmi olarak desteklenmemesi nedeniyle görünebilir.
UNKNOWN kaynaklarına sorgulayabileceğiniz ayrıntılı metrikler eklenebilir.
UNKNOWN kaynakları genellikle Search Ads 360 kullanıcı arayüzünde tamamen görünür.