Język zapytań Google Ads

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 rodzajami danych, rodzaje danych są dzielone według segmentu.

Wskaźnik

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, co umożliwia 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 rodzaje informacji:

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

  Jeśli zażądano jakichkolwiek atrybutów lub danych, wiersz zawiera również 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 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 kampanii, 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 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 Campaigndokumentacją.

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ę dostępnych do zapytania danych 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 wynikowy elementGoogleAdsRow będzie reprezentować krotkę składającą się z kampanii i segmentu dat. 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 Segmentsdokumentacji.

Zapytanie o atrybuty powiązanego zasobu

W zapytaniu dotyczącym danego zasobu możesz w razie potrzeby połączyć go z innymi powiązanymi zasobami. Te powiązane zasoby są określane jako „zasoby 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 element 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 środowiska LIMIT, aby uniknąć przetwarzania dużych zbiorów wyników.
• Aby zminimalizować transfer danych i rozmiar odpowiedzi, zastosuj filtry w klauzuli WHERE.
• Używaj symbolu GoogleAdsFieldService, aby sprawdzić zgodność pól i typów danych przed utworzeniem złożonych zapytań.
• 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 zapytania 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 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 funkcję CampaignService.MutateCampaigns, podając zmodyfikowane kampanie i odpowiedni parametr FieldMask, aby je zaktualizować.

Metadane pola

Zapytania wysyłane do GoogleAdsFieldService służą do pobierania metadanych pól. Te informacje mogą pomóc w zrozumieniu, 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 zapytań, co umożliwia programistom wykonywanie tych czynności 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, które można uwzględnić w zapytaniu, znajdziesz w  GoogleAdsFielddokumentacji usługi.

Różnice w poszczególnych wersjach

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

• 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ą wysyłane z ujednoliconych zasobów goal i campaign_goal_config, zastępując customer_lifecycle_goal i campaign_lifecycle_goal (które były używane w przypadku celów związanych z pozyskiwaniem nowych klientów w wersji 24 i starszych, a także goal i campaign_goal_config w przypadku celów związanych z utrzymaniem klientów).
• Dane o wyświetleniach komponentów z rozwiniętym końcowym adresem URL: w wersji 25 i nowszych zapytanie final_url_expansion_asset_view zwraca wszystkie dane, które można wybrać w przypadku wyświetlenia. W wersji 24 i starszych odpowiedzi obejmują tylko metrics.conversions i metrics.conversions_value w przypadku kampanii Performance Max oraz metrics.impressions w przypadku kampanii w sieci wyszukiwania.
• Raportowanie produktów w kampaniach produktowych w przypadku kampanii promujących aplikacje: w wersji 24 i nowszych zasób shopping_product zwraca wiersze produktów w przypadku kampanii promujących aplikacje, a także kampanii produktowych, kampanii Performance Max, kampanii generujących popyt i kampanii wideo (w wersji 23 kampanie promujące aplikacje są wykluczone z wyników shopping_product).
• Zasoby, segmenty i dane dotyczące konkretnej wersji:
  • Wersja 25 i nowsze: zawiera zasoby pomiaru wzrostu (np. lift_measurement_config), segmenty takie jak segments.ad_sub_format_type i segments.loyalty_membership oraz dane o zaangażowaniu w 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 na campaign_budget i segments.click_type na ad_group_asset, campaign_asset i customer_asset (które można wybrać tylko w wersji 23).
• Kod błędu dotyczący szczegółowych danych historycznych: zapytania, które segmentują dane według segments.date, segments.week lub segments.hour (albo filtrują dane według zakresu dat w okresie krótszym niż miesiąc) poza 37-miesięcznym okresem danych historycznych, 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 sekcji Zakresy dat.

Przykłady kodu

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