Język zapytań Google Ads

Kluczowa terminologia

Zasób
Jednostka w Google Ads, np. campaign lub ad_group.
Segment
Wymiar używany do grupowania danych, np. segments.date lub segments.device. Gdy segmenty są uwzględnione w klauzuli SELECT z danymi, dane są dzielone według segmentu.
Dane
Miara skuteczności, np. metrics.impressions lub metrics.clicks.
Zasób przypisany
Zasób, który jest niejawnie połączony z zasobem głównym w klauzuli FROM, co umożliwia wybranie jego atrybutów wraz z atrybutami zasobu głównego.

Zapytanie o zasób lub metadane

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

  • Zasoby i powiązane z nimi atrybuty, segmenty i dane za pomocą GoogleAdsService Search lub SearchStream: Wynikiem zapytania GoogleAdsService jest lista GoogleAdsRow instancji, z których każda GoogleAdsRow reprezentuje zasób.

    Jeśli zażądano jakichkolwiek atrybutów lub danych, w wierszu znajdują się 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 o dostępnych polach i zasobach w GoogleAdsFieldService: Ta usługa zawiera 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 artykule Struktura zapytań i gramatyka języka zapytań Google Ads Google Ads.

Zapytanie o atrybuty zasobu

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

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

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

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

Zapytanie 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 jednocześnie sortuje wyniki według identyfikatora kampanii. Każdy wynikowy element GoogleAdsRow będzie zawierać pole metrics wypełnione wybranymi danymi.

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

Zapytanie 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. Dzięki temu każdy wynikowy element GoogleAdsRow reprezentuje krotkę kampanii i daty Segment. Segmentowanie dzieli wybrane dane, grupując je według każdego segmentu w klauzuli SELECT.

Listę segmentów, o które można wysyłać zapytania, znajdziesz w dokumentacji Segments.

W zapytaniu o dany zasób możesz połączyć się z innymi powiązanymi zasobami, jeśli są dostępne. Te powiązane zasoby są nazywane „zasobami przypisanymi”. Możesz połączyć się z zasobami przypisanymi niejawnie, 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 przypisane są dostępne w przypadku zapytań o kampanie, zapoznaj się z dokumentacją referencyjną Campaign.

Sprawdzone metody

  • Wybieraj tylko te pola, których potrzebujesz, aby uniknąć długich czasów odpowiedzi i przekroczenia limitu czasu.
  • Podczas tworzenia i testowania aplikacji używaj klauzuli LIMIT, aby uniknąć przetwarzania dużych zbiorów wyników.
  • Stosuj filtry w klauzuli WHERE, aby zminimalizować transfer danych i rozmiar odpowiedzi.
  • Przed utworzeniem złożonych zapytań użyj GoogleAdsFieldService, aby 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.

Wprowadzanie zmian na podstawie wyników zapytania

Gdy wysyłasz zapytanie o dany zasób, 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 proces: 1. Wykonaj zapytanie o wszystkie kampanie, 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 CampaignService.MutateCampaigns ze zmodyfikowanymi kampaniami, aby je zaktualizować.

Metadane pola

Zapytania wysyłane do GoogleAdsFieldService służą do pobierania metadanych pola. Te informacje mogą pomóc w zrozumieniu, jak można używać pól razem w zapytaniu. Ponieważ dane są dostępne w interfejsie API i zawierają metadane niezbędne do zweryfikowania lub utworzenia zapytania, deweloperzy mogą to zrobić programowo. 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, o które można wysyłać zapytania, znajdziesz w GoogleAdsField dokumentacji.

Przykłady kodu

W bibliotekach klienta znajdziesz przykłady użycia języka zapytań Google Ads w GoogleAdsService. W folderze basic operations (podstawowe działania) znajdziesz przykłady takie jak GetCampaigns, GetKeywords i SearchForGoogleAdsFields.

Dalej
Gramatyka zapytania