Język zapytań Google Ads

Wskazówka: do tworzenia i weryfikowania zapytań GAQL używaj interaktywnego kreatora zapytań.

Kluczowa terminologia

Zasób

Element 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 segmentów.

Wskaźnik

Miara skuteczności, np. metrics.impressions lub metrics.clicks.

Przypisany zasób

Zasób, który jest niejawnie dołączony do zasobu głównego w klauzuli FROM, co umożliwia wybieranie jego atrybutów wraz z atrybutami zasobu głównego.

Wysyłanie zapytań o informacje o zasobach lub metadanych

Za pomocą języka zapytań Google Ads możesz wysyłać do interfejsu Google Ads API zapytania o te typy informacji:

• Zasoby i powiązane z nimi atrybuty, segmenty i dane za pomocą GoogleAdsService Search lub SearchStream: wynik zapytania GoogleAdsService to lista instancji GoogleAdsRow, gdzie każda instancja GoogleAdsRow reprezentuje zasób.

  Jeśli żądanie dotyczy jakichkolwiek atrybutów lub danych, wiersz zawiera również te pola. Jeśli żądane są jakieś segmenty, odpowiedź zawiera też dodatkowy wiersz dla każdej krotki segment-zasób.

• Metadane dotyczące dostępnych pól i zasobów w GoogleAdsFieldService: ta usługa udostępnia katalog pól, które można wyszukiwać, 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 artykułach Struktura zapytań i Gramatyka języka Google Ads Query Language.

Zapytanie o atrybuty zasobów

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 obiekt 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 dokumentacją referencyjną Campaign.

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 odfiltrowuje 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 obiekt GoogleAdsRow będzie miał pole metrics wypełnione wybranymi danymi.

Listę danych, które można wyszukiwać, znajdziesz w dokumentacji Metrics.

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 zapytania o dane, to zapytanie filtruje tylko kampanie, które mają stan PAUSED i uzyskały ponad 1000 wyświetleń. To zapytanie dzieli jednak dane według daty. W efekcie każdy obiekt GoogleAdsRow reprezentuje krotkę kampanii i segmentu daty. Segmentacja dzieli wybrane dane, grupując je według każdego segmentu w klauzuli SELECT.

Listę segmentów, które można uwzględniać w zapytaniach, znajdziesz w dokumentacji Segments.

Zapytanie o atrybuty przydatnych materiałów

W zapytaniu dotyczącym danego zasobu możesz dołączyć inne powiązane zasoby, jeśli są dostępne. Te przydatne materiały są nazywane „zasobami przypisanymi”. Możesz dołączyć zasoby z atrybutami 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 obiekt 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 dokumentacją Campaign.

Sprawdzone metody

• Wybierz tylko te pola, których potrzebujesz, aby uniknąć długiego czasu odpowiedzi i przekroczenia limitu czasu.
• Podczas programowania i testowania używaj LIMIT, aby uniknąć przetwarzania dużych zbiorów wyników.
• Zastosuj filtry w klauzuli WHERE, aby zminimalizować przesyłanie danych i rozmiar odpowiedzi.
• Zanim utworzysz złożone zapytania, użyj GoogleAdsFieldService, aby sprawdzić zgodność pól i typy danych.
• Pamiętaj, że niektóre pola, zwłaszcza te, które zawierają duże ilości danych lub złożone obliczenia, mogą zwiększyć koszt zapytania.

Mutowanie na podstawie wyników zapytania

Podczas wysyłania zapytania o dany zasób możesz od razu pobrać zwrócone wyniki jako obiekty, zmodyfikować je i odesłać do metody mutate w usłudze tego zasobu. Oto przykładowy proces:

1. Wykonaj zapytanie dotyczące wszystkich kampanii PAUSED, które mają ponad 1000 wyświetleń.
2. Pobierz obiekt Campaign z pola campaign każdego elementu GoogleAdsRow w odpowiedzi.
3. Zmień stan każdej kampanii z PAUSED na ENABLED.
4. Wywołaj metodę CampaignService.MutateCampaigns ze zmienionymi kampaniami i odpowiednim parametrem FieldMask, aby je zaktualizować.

Uwaga: podczas aktualizowania zasobów pobranych z zapytania określ FieldMask (lub użyj wbudowanego w bibliotekę klienta narzędzia do maskowania pól), aby aktualizowane były tylko zmodyfikowane pola. Pozwoli to uniknąć błędów READ_ONLY_FIELD lub IMMUTABLE_FIELD oraz niezamierzonego zastąpienia innych atrybutów.

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 dostarcza metadane niezbędne do weryfikacji lub utworzenia zapytania, dzięki czemu deweloperzy mogą to robić 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).

Kluczowa kwestia: zwróć uwagę, że w tym zapytaniu nie ma klauzuli FROM.

Listę pól, które można uwzględniać w zapytaniach, znajdziesz w dokumentacji GoogleAdsField.

Różnice między wersjami

Składnia, klauzule i operatory języka zapytań Google Ads są identyczne we wszystkich obsługiwanych wersjach interfejsu Google Ads API (v23, v24, v25 i v26), ale katalog zasobów, segmentów, danych i zachowań raportowania, które można wyszukiwać, różni się w zależności od wersji głównej. Wyślij zapytanie do GoogleAdsFieldService w punkcie końcowym docelowej wersji interfejsu API, aby sprawdzić pola i reguły zgodności dla tej wersji:

• Widok komponentów z rozwinięciem końcowego adresu URL:
  • Obsługa kampanii produktowych (wersja 26 i nowsze): final_url_expansion_asset_view obsługuje kampanie produktowe (campaign.advertising_channel_type = 'SHOPPING') oprócz kampanii Performance Max i kampanii w sieci wyszukiwania. W przypadku kampanii produktowych możesz wybierać i filtrować pola ad_group, ale nie możesz wybierać pól asset_group.
  • Dane do wyboru (wersja 25 i nowsze): zapytanie final_url_expansion_asset_view zwraca wszystkie dane do wyboru w widoku. W wersji 24 i starszych odpowiedzi zawierają tylko metrics.conversions i metrics.conversions_value w przypadku kampanii Performance Max oraz metrics.impressions w przypadku kampanii w sieci wyszukiwania.
• Zasoby dotyczące celów związanych z cyklem życia: w wersji 25 i nowszych wszystkie cele związane z cyklem życia (pozyskiwanie nowych klientów, utrzymanie klientów i utrzymanie lojalności) są wyszukiwane w ujednoliconych zasobach goal i campaign_goal_config, które zastępują zasoby customer_lifecycle_goal i campaign_lifecycle_goal (używane w przypadku celów dotyczących pozyskiwania nowych klientów w wersji 24 i starszych, obok zasobów goal i campaign_goal_config w przypadku celów dotyczących utrzymania klientów).
• Raporty na temat produktów w kampaniach promujących aplikacje: w wersji 24 i nowszych zasób shopping_product zwraca wiersze produktów w kampaniach promujących aplikacje, a także w kampaniach produktowych, kampaniach Performance Max, kampaniach generujących popyt i kampaniach wideo (w wersji 23 kampanie promujące aplikacje są wykluczone z wyników shopping_product).
• Zasoby, segmenty i dane zależne od wersji:
  • Wersja 26 i nowsze: obejmuje zasób search_lift_keyword_bundle, campaign.lift_measurement_config, local_services_lead.campaign, segments.search_lift_keyword_bundle, segments.search_property oraz dane dotyczące wzrostu liczby wyszukiwań (takie jak metrics.relative_search_lift, metrics.normalized_incremental_searches, metrics.search_lift_cost_micros i metrics.search_lift_impressions).
  • Wersja 25 i nowsze: obejmuje zasoby pomiaru wzrostu (takie jak lift_measurement_config), segmenty takie jak segments.ad_sub_format_type i segments.loyalty_membership oraz wskaźniki zaangażowania na YouTube (metrics.youtube_likes, metrics.youtube_comments i metrics.youtube_shares). Usuwa local_services_lead.contact_details.email (który można wybrać w wersji 24 i starszych).
  • Wersja 24 i nowsze: obejmuje zasób cart_data_sales_view, segments.conversion_attribution_event_type w shopping_performance_view, segments.mobile_device_platform i segments.ad_network_type w performance_max_placement_view. Usuwa campaign.video_brand_safety_suitability (zastąpione przez customer.video_brand_safety_suitability), segments.ad_sub_network_type w campaign_budget oraz segments.click_type w ad_group_asset, campaign_asset i customer_asset (które można wybrać tylko w wersji 23).
• Kod błędu dotyczący okresu ważności szczegółowych danych: zapytania, które segmentują według segments.date, segments.week lub segments.hour (lub filtrują według zakresu dat krótszego niż miesiąc) poza 37-miesięcznym okresem ważności, zwracają błąd DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED w wersji 24 i nowszych (lub DateRangeError.UNKNOWN w wersji 23). Więcej informacji znajdziesz w artykule Zakresy dat.

Przykłady kodu

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