Język zapytań Google Ads

Kluczowe terminy

Zasób: Element w Google Ads, np. campaign lub ad_group.
Segment: Wymiar używany do grupowania danych, np. segments.date lub segments.device. Jeśli w klauzuli SELECT uwzględniono segmenty wraz z danymi, dane są dzielone według segmentów.
Dane: Miara skuteczności, np. metrics.impressions lub metrics.clicks.
Przypisany zasób: Zasób, który jest niejawnie połączony z zasobem głównym w klauzuli FROM, umożliwiający wybieranie jego atrybutów wraz z atrybutami zasobu głównego.

Wykonywanie zapytań o informacje o zasobach lub metadanych

Język zapytań Google Ads może wysyłać do interfejsu Google Ads API zapytania o te typy informacji:

Zasoby i powiązane z nimi atrybuty, segmenty i dane za pomocą metod GoogleAdsService Search lub SearchStream:GoogleAdsRow wynik zapytania do usługi Google Ads to lista instancji GoogleAdsRow, z których każda reprezentuje zasób.

Jeśli zażądano jakichkolwiek atrybutów lub danych, wiersz zawiera też te pola. Jeśli zażądano jakichkolwiek segmentów, w odpowiedzi pojawi się też dodatkowy wiersz dla każdej krotki segment-zasób.
Metadane dotyczące dostępnych pól i zasobów w usłudze GoogleAdsFieldService: Ta usługa udostępnia katalog pól, o które można wysyłać zapytania, wraz ze szczegółowymi informacjami o ich zgodności i typie.

Wynikiem zapytania GoogleAdsFieldService jest lista instancji GoogleAdsField, z których każda GoogleAdsField zawiera szczegółowe informacje o wybranym polu.

Więcej informacji o strukturze zapytań znajdziesz w sekcjach Struktura zapytań i Gramatyka języka zapytań Google Ads.

Zapytanie o atrybuty zasobu

Oto przykład podstawowego zapytania o atrybuty zasobu kampanii, które pokazuje, jak zwrócić identyfikator, nazwę i stan kampanii:

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

To zapytanie sortuje dane według identyfikatora kampanii. Każdy wynikowy element GoogleAdsRow reprezentuje obiekt campaign wypełniony wybranymi polami, w tym polem resource_name kampanii.

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

Wysyłanie zapytań o dane

Oprócz wybranych atrybutów 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 kampanie, które mają stan PAUSED i uzyskały ponad 1000 wyświetleń, a następnie porządkuje je według identyfikatora kampanii. Każdy uzyskany GoogleAdsRow będzie miał pole metrics wypełnione wybranymi danymi.

Listę danych, o które można wysyłać zapytania, znajdziesz w Metricsdokumentacji.

Wykonywanie zapytań o segmenty

Oprócz wybranych atrybutów danego zasobu możesz też wysyłać zapytania o 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, które mają stan PAUSED i uzyskały ponad 1000 wyświetleń. To zapytanie segmentuje jednak dane według daty. W rezultacie każda z nich będzie reprezentować GoogleAdsRowkrotkę składającą się z kampanii i datySegment. Segmentowanie dzieli wybrane dane, grupując je według każdego segmentu w klauzuli SELECT.

Listę segmentów, które można uwzględnić w zapytaniu, znajdziesz w Segmentsdokumentacji.

W zapytaniu dotyczącym danego zasobu możesz w razie potrzeby połączyć go z innymi powiązanymi zasobami. Te powiązane zasoby są nazywane „zasobami z atrybucją”. Możesz łączyć się z zasobami z atrybucją w sposób niejawny, 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 z każdej wybranej kampanii. Każdy wynikowy element GoogleAdsRow reprezentuje obiekt campaign wypełniony wybranymi atrybutami kampanii oraz wybranym atrybutem strategii ustalania stawek bidding_strategy.name.

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

Sprawdzone metody

Aby uniknąć długiego czasu odpowiedzi i przekroczenia limitu czasu, wybierz tylko potrzebne pola.
Podczas tworzenia i testowania używaj LIMIT, aby uniknąć przetwarzania dużych zbiorów wyników.
Aby zminimalizować transfer danych i rozmiar odpowiedzi, zastosuj filtry w klauzuli WHERE.
Używaj GoogleAdsFieldService, aby przed utworzeniem złożonych zapytań sprawdzić zgodność pól i typów danych.
Pamiętaj, że niektóre pola, zwłaszcza te, które zawierają duże ilości danych lub wymagają złożonych obliczeń, mogą zwiększyć koszt zapytania.

Zmiana na podstawie wyników zapytania

Podczas wysyłania zapytań dotyczących danego zasobu możesz od razu traktować zwrócone wyniki jako obiekty, modyfikować je i wysyłać z powrotem do metody mutate w usłudze tego zasobu. Oto przykładowy przepływ pracy: 1. Wykonaj zapytanie dotyczące wszystkich kampanii, które są obecnie PAUSED i mają ponad 1000 wyświetleń. 1. Pobierz obiekt Campaign z pola campaign każdego elementu GoogleAdsRow w odpowiedzi. 1. Zmień stan każdej kampanii z PAUSED na ENABLED. 1. Wywołaj funkcję CampaignService.MutateCampaigns z zmodyfikowanymi kampaniami, aby je zaktualizować.

Metadane pola

Zapytania wysyłane do GoogleAdsFieldService służą do pobierania metadanych pól. Te informacje pomogą Ci zrozumieć, jak można używać pól razem w zapytaniu. Dane są dostępne w interfejsie API, który udostępnia niezbędne metadane do weryfikacji lub tworzenia zapytania, co umożliwia programistom wykonywanie tych czynności automatycznie. Oto typowe zapytanie o metadane:

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

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

Listę pól, które można uwzględnić w zapytaniu, znajdziesz w GoogleAdsFielddokumentacji.

Przykłady kodu

W bibliotekach klientów znajdziesz przykłady użycia języka zapytań Google Ads w GoogleAdsService. W folderze basic operations znajdziesz przykłady takie jak GetCampaigns, GetKeywords i SearchForGoogleAdsFields.

Dalej

Gramatyka zapytania