Język zapytań Google Ads

Język zapytań Google Ads może wysyłać do interfejsu Google Ads API zapytania dotyczące

zasobów oraz powiązanych z nimi atrybutów, segmentów i danych za pomocą
GoogleAdsService Szukaj lub SearchStream
Wynik zapytania w GoogleAdsService to lista instancji GoogleAdsRow, z których każde GoogleAdsRow reprezentuje zasób. Jeśli wymagane są jakieś atrybuty lub dane, wiersz zawiera też te pola. Jeśli zażądasz segmentów, w odpowiedzi wyświetli się też dodatkowy wiersz dla każdej kropki zasobu segmentu.
Metadane dotyczące dostępnych pól i zasobów w
GoogleAdsFieldService

Ta usługa udostępnia katalog pól, na które można wykonywać zapytania, ze szczegółowymi informacjami na temat ich zgodności i typu.

Wynik zapytania GoogleAdsFieldService to lista instancji GoogleAdsField, z których każda GoogleAdsField zawiera szczegóły dotyczące żądanego pola.

Zapytanie o atrybuty zasobu

Poniżej znajdziesz podstawowe zapytanie o atrybuty zasobu kampanii, które ilustruje sposób zwracania identyfikatora, nazwy i stanu kampanii:

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign
ORDER BY campaign.id

To zapytanie obejmuje zamówienia według identyfikatora kampanii. Każdy wynik GoogleAdsRow reprezentowałby obiekt campaign wypełniony wybranymi polami (w tym resource_name danej kampanii).

Aby dowiedzieć się, jakie inne pola są dostępne w przypadku zapytań dotyczących kampanii, zapoznaj się z dokumentacją Campaign.

Zapytanie o wskaźniki

Oprócz wybranych atrybutów dla danego zasobu możesz też wysyłać zapytania o powiązane dane:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id

To zapytanie filtruje tylko te kampanie, które mają stan PAUSED i uzyskały ponad 1000 wyświetleń, a przy tym są sortowane według identyfikatora kampanii. Każdy wynik GoogleAdsRow będzie zawierał pole metrics z wybranymi danymi.

Listę wskaźników, o których można tworzyć zapytania, znajdziesz w dokumentacji usługi Metrics.

Zapytania dotyczące segmentów

Oprócz wybranych atrybutów dla danego zasobu możesz też wyszukiwać powiązane segmenty:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  segments.date,
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
  AND segments.date during LAST_30_DAYS
ORDER BY campaign.id

Podobnie jak w przypadku zapytań o dane, to zapytanie filtruje tylko kampanie o stanie PAUSED i uzyskały ponad 1000 wyświetleń. Zapytanie to jednak dzieli dane na segmenty według daty. W efekcie każde wynik GoogleAdsRow reprezentuje kropkę kampanii z datą Segment. Pamiętaj, że podział na segmenty powoduje podział wybranych danych i grupowanie danych według każdego segmentu w klauzuli SELECT.

Listę segmentów, o których można wykonywać zapytania, znajdziesz w dokumentacji usługi Segments.

W zapytaniu dotyczącym danego zasobu możesz dołączyć do innych powiązanych zasobów, jeśli są dostępne. Są to tzw. „przypisane zasoby”. Możesz łączyć się z zasobami przypisanymi domyślnie, wybierając atrybut w zapytaniu.

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  bidding_strategy.name
FROM campaign
ORDER BY campaign.id

To zapytanie nie tylko wybiera atrybuty kampanii, ale też pobiera powiązane atrybuty ze wszystkich wybranych kampanii. Każdy wynikowy GoogleAdsRow odpowiada obiektowi campaign z wybranymi atrybutami kampanii oraz wybranym atrybutem strategii ustalania stawek bidding_strategy.name.

Aby dowiedzieć się, jakie przypisane zasoby są dostępne w przypadku zapytań dotyczących kampanii, zapoznaj się z dokumentacją referencyjną Campaign.

Mutacja na podstawie wyników zapytania

Gdy wysyłasz zapytanie dotyczące danego zasobu, możesz natychmiast przyjąć zwrócone wyniki jako obiekty, zmodyfikować je i odesłać z powrotem do metody mutacji w usłudze tego zasobu. Oto przykładowy przepływ pracy:

  1. Wykonaj zapytanie w przypadku wszystkich kampanii, które obecnie mają stan PAUSED i które mają wyświetlenia więcej niż 1000.
  2. Pobierz obiekt Campaign z pola campaign każdego GoogleAdsRow w odpowiedzi.
  3. Zmień stan każdej kampanii z PAUSED na ENABLED.
  4. Wywołaj CampaignService.MutateCampaigns ze zmodyfikowanymi kampaniami, aby je zaktualizować.

Metadane pola

Zapytania wysyłane do GoogleAdsFieldService służą do pobierania metadanych pól. Informacje te pozwalają zrozumieć, jak te pola można wykorzystać razem w zapytaniu. Ponieważ dane są dostępne z poziomu interfejsu API i dostarczają metadane niezbędne do weryfikacji lub utworzenia zapytania, deweloperzy mogą to robić w sposób zautomatyzowany. Oto typowe zapytanie o metadane:

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

Możesz zastąpić w tym zapytaniu <INSERT_RESOURCE_OR_FIELD> zasobem (np. customer lub campaign) albo polem (takim jak campaign.id, metrics.impressions lub ad_group.id).

Listę pól, o których można wykonywać zapytania, znajdziesz w dokumentacji usługi GoogleAdsField.

Przykłady kodu

Biblioteki klienta zawierają przykłady użycia języka zapytań Google Ads w języku GoogleAdsService. Folder Operacje podstawowe zawiera przykłady, takie jak GetCampaigns, GetKeywords i SearchForGoogleAdsFields. Folder reporting zawiera przykład GetKeywordStats.