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

Arama Ağı Reklamlarında arama raporlarının nasıl oluşturulacağını öğrenmek için aşağıdaki bölümleri okuyun 360 Raporlama API'si.

Hizmet arayın

Search Ads 360 Reporting API, raporlama ve veri işleme konularında raporlama.

SearchAds360Service, birleştirilmiş nesne alma ve raporlama hizmetidir iki arama yöntemi sunar: SearchStream ve Search. Aramalar Search Ads 360 Sorgu Dili'nde yazılmış bir sorgu dizesinde geçirilir. Sorguları şu amaçlarla tanımlayabilirsiniz:

• Nesnelerin belirli özelliklerini alın.
• Tarih aralığına göre nesneler için performans metriklerini alın.
• Nesneleri özelliklerine göre sıralayın.
• Döndürülecek nesneleri 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 bulunuyorsa API bir id ve name alanlarıyla bir kampanya nesnesi içeren SearchAds360Row ve clicks alanının ayarlandığı bir metrics nesnesi olarak ayarlayın.

Arama yöntemleri

SearchStream

Tek bir istek gönderir ve kalıcı bağlantı başlatır Search Ads 360 Reporting API ile raporlamanızı sağlar.

• Veri paketleri, sonucun tamamı ile birlikte hemen indirilmeye başlar veri arabelleğinde önbelleğe alınır.
• Kodunuz, arabelleğe alınan verileri devam ettirin.

Search

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

SearchStream genellikle daha iyi performans sunar çünkü tek tek sayfa isteğinde bulunmak için gereken gidiş dönüş ağ süresi. Önerilerimiz 10.000'den fazla satır içeren tüm raporlar için SearchStream. Önemli bir daha küçük raporlar (10.000'den az satır) için yöntemler arasındaki performans farkını gösterir.

Kullandığınız yöntem, API kotalarınızı ve sınırlarınızı etkilemez. Tek bir sorgu veya rapor sonuçların sayfayla veya akışla alınmış olmasına bakılmaksızın tek bir işlem olarak sayılır.

Örnek arama sorgusu

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

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

Not: Search Ads 360 Sorgu Dili, ayrıntılı bilgiler sağlar. Arama sorgusunun her bir maddesinin nasıl kullanılacağı hakkında daha fazla bilgi edinin.

İstekte bulunun

İstekte bulunmak için bir customer_id ve query dizesi iletmeniz gerekir SearchAds360Service.SearchStream veya SearchAds360Service.Search kullanır.

Not: Aşağıdaki örneklerde temel HTTP/JSON isteği gösterilmektedir. Bu, göstermektir. Kendi uygulamanızda istek göndermek için gRPC'yi temel alan istemci kitaplıklarımızı kullanmanızı öneririz.

İstek, Search Ads 360 Reporting API'ye yönelik bir HTTP POST içeriyor sunucuyu eklemeniz gerekir:

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 tam bir örneğini aşağıda bulabilirsiniz: HTTP POST isteği:

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 bir listesini döndürür.

Her SearchAds360Row, sorgu tarafından döndürülen bir nesneyi temsil eder. Her bir nesne istenen alanlara göre doldurulan bir dizi özellikten oluşur (ör. sorgunun SELECT yan tümcesinde) SELECT kapsamında olmayan özellikler yan tümcesi yanıttaki nesneler için doldurulmaz.

Örneğin, aşağıdaki sorgu her SearchAds360Row nesnesini yalnızca campaign.id, campaign.name ve campaign.status. Örneğin, campaign.engine_id veya campaign.bidding_strategy_type 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 ihtiyacınız olan tüm bilgileri içerir. Her biri 100'den az gösterim alan her kaynak için bir sayfa (ör. ad_group ve campaign. segments ve metrics sayfaları Tüm kullanılabilir segmentleri ve metrik alanlarını listeleyin.

Bazı kaynaklar, segmentler ve metrikler uyumsuz ve kullanılamıyor Birbiriyle uyumlu ve birbirini tamamlayan içerik üreticilerle tanışın. Her biri kaynak sayfası aşağıdaki bilgileri (varsa) içerir uygun) ve daha fazlası:

İlişkilendirilmiş kaynaklar

Bazı kaynaklar için, ilgili diğer kaynaklar için seçerek kendi alanlarını kaynak alanlarından seçebilir ve FROM ifadeniz. Örneğin, campaign kaynağı ad_group kaynağının ilişkilendirilen kaynağı. Bu da size campaign.id ve campaign.bidding_strategy_type gibi alanları sorgusu için FROM ifadenizde ad_group ifadesini kullanın.

İlişkilendirilmiş kaynaklar bölümünde, ilişkilendirilmiş mevcut kaynaklar listelenir. Değil tüm kaynaklarda ilişkilendirilmiş kaynaklar var.

Kaynak alanları sütunu

Kaynağın tüm alanları, Kaynak alanları sütununa eklenir. Her kaynak alanı, aşağıdakileri de içeren, alanla ilgili daha fazla ayrıntıya bağlantı verir açıklama, kategori, veri türü, URL türü ve filtrelenebilir, seçilebilir, sıralanabilir ve tekrarlanan bir ayardır.

Segmentler sütunu

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

Segmentler sütununda, kullanabileceğiniz segments alanları kaynağın alanlarıyla aynı SELECT yan tümcesini kullanın. Her alan tam bir alanla ilgili ayrıntılar (açıklama, kategori, veri türü, tür dahil) URL ile filtrelenebilir, seçilebilir, sıralanabilir ve tekrarlanan ayar. Şu durumda: FROM ifadenizdeki kaynağı kullanarak Evet/Hayır açılır listesini kullanabilirsiniz. kullanılabilir olmayan segmentleri çıkarabilirsiniz.

Metrikler sütunu

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

Metrikler sütunu, şurada kullanabileceğiniz metrics alanlarını listeler: kaynağın alanlarıyla aynı SELECT yan tümcesini kullanın. Her alan tam bir alanla ilgili ayrıntılar (açıklama, kategori, veri türü, tür dahil) URL ile filtrelenebilir, seçilebilir, sıralanabilir ve tekrarlanan ayar. Şu durumda: FROM ifadenizdeki kaynağı kullanarak Evet/Hayır açılır listesini kullanarak Kullanılamayan metrikleri filtreleyebilirsiniz.

ziyaret edin.

'nı inceleyin.

Not: Belirli bir metrik için para birimiyle ilgili metrikleri (ör. maliyet_mikrofonları) alırken bir tarih veya tarih aralığı kullanıyorsanız SELECT yan tümcesine segments.date ifadesini eklediğinizden emin olun.

Kaynakları segmentlere ayırma

Bazı kaynaklarda, kaynak, FROM ifadenizde yer alıyor. Örneğin, şunun gibi bir campaign kaynak alanı seçerseniz: campaign.name, şu durumlarda: FROM ifadenizde campaign_budget kullanılarak, campaign.resource_name döndürülecek ve segmentlere ayrılacaktır, çünkü campaign bir campaign_budget öğesinin segmentasyon kaynağı.

Kaynakları segmentlere ayırma bölümünde, kullanılabilir segmentasyon kaynakları listelenir. Değil tüm kaynaklarda segmentasyon kaynakları bulunur.

Şununla seçilebilir:

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

segments sayfası Şu boyuta sahip her segments alanı için genişletilebilir bir Seçilebilir seçeneği içerir tüm uyumlu kaynak alanlarını, metrics alanlarını ve diğer segments alanlarını listeler alanları SELECT ifadenize ekleyebilirsiniz.

ziyaret edin.

'nı inceleyin.

Not: Her bir ifadeyi nasıl kullanacağınızı öğrenmek için Search Ads 360 Sorgu Dili bölümüne bakın anlamına gelir.

Segmentasyon

Arama sonuçlarınızı segmentlere ayırmak için segments.FIELD_NAME alanını sorgunuzun SELECT deyimine ekleyin.

Örneğin, segments.device aşağıdaki sorguyla her birinin impressions değeri için satır içeren bir rapor ortaya çıkar FROM yan tümcesinde belirtilen kaynak için cihaz oluşturun.

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

SearchAds360Service.SearchStream tarafından döndürülen sonuçlar bir şeye benziyor şu JSON dizesi gibidir:

{
  "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"
      }
    },
    ...
  ]
}

Ayrıntılı bilgi için segments adresini ziyaret edin. segment alanları listesi oluşturun.

Birden fazla segment

Dikkat: Satır sayısı, eklenen her satır için katlanarak artabilir segments alanını kullanın.

Sorgunuzun SELECT yan tümcesinde birden fazla segment belirtebilirsiniz. İlgili içeriği oluşturmak için kullanılan yanıt, şu öğenin her bir kombinasyonu için bir SearchAds360Row nesnesi içerir: FROM ifadesinde belirtilen ana kaynağın örneği ve value (değeri). Seçilen her segment alanının değeri.

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

SELECT
  segments.ad_network_type
  segments.date
FROM campaign

Sonuçların, ana sayfanızın her örneğine göre dolaylı olarak segmentlere ayrıldığını yalnızca seçilen alanların değerlerine göre değil.

Aşağıdaki örnek sorgu, her kampanya için bir satır değil, her kampanya için bir satırla sonuçlanır campaign.status alanına ayrı bir değer girin.

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

Dolaylı segmentasyon

Her rapor başlangıçta FROM sütununda belirtilen kaynağa göre segmentlere ayrılır. ifadesini ekleyin. Metrikler, bu kaynağın resource_name alanına göre segmentlere ayrılır.

Not: FROM yan tümcesindeki kaynağın resource_name alanı her zaman (SELECT yan tümcesinde belirtilmediğinde bile) döndürülür. Görüntüleyin Daha fazla bilgi için resource_name alanı tıklayın.

Bu örnek sorgu, otomatik olarak ad_group.resource_name değerini ve dolaylı bunu, metrikleri 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

Tarih belirtmek için WHERE ifadenizde temel tarih segmentlerini kullanabilirsiniz veya zaman aralığı.

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 clicks kampanyası 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ı, önceden belirlediğiniz genel kuralın istisnasıdır. bir segment alanı, WHERE alanına SELECT ifadesini ekleyin. Daha fazla bilgi için Yasaklanmış filtreleme konusuna bakın ekleyebilirsiniz.

Temel tarih segmenti kuralları:

• Temel tarih alanını WHERE deyiminize dahil etmeden kullanabilirsiniz. SELECT ifadesi. İsterseniz bu alanı her iki ifadeye de ekleyebilirsiniz.

  Bu örnek sorgu, ilgili tarih boyunca kampanya adına göre clicks metrikleri döndürür. aralığı. segments.date ifadesinin SELECT ifadesine 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 ifadenize temel tarih alanı eklerseniz WHERE ifadenizde sonlu tarih veya tarih aralığı. SELECT ve WHERE ifadelerinin eşleşmesi gerekmez.

  Bu örnek sorgu, şuna göre segmentlere ayrılmış kampanya adına göre clicks metriklerini döndürür: ay.

  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) = operatörünü dönemin ilk günü, örneğin:

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

Not: Âdetin ilk günü olmayan bir tarih belirtirseniz MISALIGNED_DATE_FOR_FILTER hatası alıyor.

Ö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 için.
YESTERDAY	Yalnızca dün için geçerlidir.
LAST_7_DAYS	Önceki 7 gün, bugün dahil değil.
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	Bir önceki Pazar günü ile geçerli gün arasındaki dönem.
THIS_WEEK_MON_TODAY	Bir önceki pazartesi günü ile geçerli 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	Bir önceki Pazartesi gününden itibaren 7 günlük dönem.

Örnek:

WHERE segments.date DURING LAST_30_DAYS

Sıfır metrik

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

UNKNOWN sıralama türleri

Bir kaynak UNKNOWN sıralama veri türüyle döndürülürse bu durum şu anlama gelir: tür, API sürümünde tam olarak desteklenmiyor. Bu kaynaklarda diğer arayüzlerle oluşturulmuştur. Örneğin, yeni bir kampanya veya reklam Search Ads 360 kullanıcı arayüzünde kullanıma sunuldu, ancak henüz API sürümünde desteklenmiyor size yardımcı olabilir.

UNKNOWN türünde bir kaynak olduğunda metrik seçebilirsiniz ancak şunları unutmayın:

• UNKNOWN türündeki bir kaynak daha sonra desteklenebilir ancak kalabilir Süresiz olarak UNKNOWN.
• Herhangi bir zamanda UNKNOWN türünde yeni nesneler görünebilir. Bu nesneler enum değeri zaten mevcut olduğundan geriye dönük uyumludur. Google'da mümkün olan en iyi sonucu alabilmeniz için bir görünümünü elde edersiniz. UNKNOWN kaynağı, yeni veya diğer arayüzler üzerinden gelen veya belirli bir kaynağın artık resmi olarak desteklenmez.
• UNKNOWN kaynağa, bulabileceğiniz ayrıntılı metrikler eklenmiş olabilir emin olun.
• UNKNOWN kaynakları genellikle Search Ads 360 kullanıcı arayüzünde tamamen görünür durumdadır.