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
ifadenizdead_group
kullanırken sorgunuzacampaign.id
vecampaign.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ğinizsegments
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ğinizmetrics
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 bircampaign
kaynak alanı seçersenizFROM
ibarenizdecampaign_budget
kullandığınızdacampaign.resource_name
otomatik olarak döndürülür ve segmentlere ayrılır. Bunun nedenicampaign
,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 birsegments
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ğersegments
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ümcesinesegments.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ı eklersenizWHERE
ibarenizde sonlu bir tarih veya tarih aralığı belirtmeniz gerekir.SELECT
veWHERE
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 olarakUNKNOWN
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.