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 segmentu.

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: wynik zapytania do GoogleAdsService to lista instancji GoogleAdsRow, przy czym każda instancja GoogleAdsRow 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 żądanym 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 z nim 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 wynikowy 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żdy element GoogleAdsRow będzie reprezentować krotkę składającą się z kampanii i daty Segment. 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.

Zapytanie o atrybuty powiązanego zasobu

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

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

Sprawdzone metody

• Wybieraj tylko potrzebne pola, aby uniknąć długiego czasu odpowiedzi i przekroczenia limitu czasu.
• Podczas tworzenia i testowania używaj LIMIT, aby uniknąć przetwarzania dużych zbiorów wyników.
• Zastosuj filtry w klauzuli WHERE, aby zminimalizować transfer danych i rozmiar odpowiedzi.
• Używaj GoogleAdsFieldService, aby przed utworzeniem złożonych zapytań sprawdzić zgodność pól i typy danych.
• Pamiętaj, że niektóre pola, zwłaszcza te, które obejmują duże ilości danych lub złożone obliczenia, 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 ze 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 w zapytaniu. Dane są dostępne w interfejsie API, który udostępnia niezbędne metadane do weryfikacji lub tworzenia zapytań, 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, w których można wyszukiwać, 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.