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.

Arama hizmeti

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 sunan birleşik bir nesne alma ve raporlama hizmetidir. Aramalar, Search Ads 360 sorgu dilinde 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ıralayın.
  • 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 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

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ı veri arabelleğinde önbelleğe alınmış şekilde hemen indirilmeye başlar.
  • Kodunuz, aktarımın tamamının tamamlanmasını 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, tek tek sayfaları istemek için gereken gidiş dönüş ağ süresini ortadan kaldırdığı için 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ırdan az) için kullanılan 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ış halinde olup olmadığı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 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 nesnelere 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 bir yapıyı doğru şekilde kullanmak için ihtiyaç duyduğunuz 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 uyumsuz olup birlikte kullanılamaz. Bazıları ise tamamen uyumlu olup birbirini tamamlar. Her kaynak sayfasında aşağıdaki bilgiler (mevcutsa ve uygunsa) ve daha fazlası yer alır:

İlişkilendirilmiş kaynaklar

Bazı kaynaklar için ilgili kaynakları FROM ifadenizdeki kaynak alanlarıyla birlikte seçerek ilgili kaynakları dolaylı olarak birleştirebilirsiniz. Örneğin, campaign kaynağı, ad_group kaynağının ilişkilendirilmiş bir kaynağıdır. Diğer bir deyişle, FROM ifadenizde ad_group kullanırken sorgunuza campaign.id ve campaign.bidding_strategy_type gibi alanlar ekleyebilirsiniz.

Ö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 kaynakla tüm segment alanları seçilemez.

Segmentler sütununda, kaynağın alanlarıyla 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ı da 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.

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

Şununla 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 ifadesine 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 örneğinin her 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, ana kaynağın her örneğine göre dolaylı 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 farklı değeri başına 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, ad_group.resource_name değerini otomatik olarak döndürür ve ad_group düzeyindeki metrikleri segmentlere ayırmak için ad_group.resource_name değerini dolaylı olarak 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.

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ı, SELECT ifadenize bu alanı dahil etmediğiniz sürece WHERE ifadenizde segmentler alanı kullanamayacağınız genel kuralın istisnası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ığı boyunca 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 (segments.week, segments.month, segments.quarter) gerektiren temel tarih segmentleri için = operatörünü dönemin ilk günüyle 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 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 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 türün API sürümünde tam olarak desteklenmediği anlamına gelir. Bu kaynaklar başka arayüzler üzerinden oluşturulmuş olabilir. Örneğin, Search Ads 360 kullanıcı arayüzünde yeni bir kampanya veya reklam tanıtılır, ancak sorguladığınız API sürümünde henüz desteklenmemektedir.

UNKNOWN türünde bir kaynak olduğunda yine de metrik seçebilirsiniz 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.