Język zapytań Google Ads

Wysyłanie 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: wynikiem zapytania do 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 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.

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 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 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ż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, o które można wysyłać zapytania, 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 z atrybucją są dostępne w przypadku zapytań dotyczących kampanii, zapoznaj się z Campaign dokumentacją.

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 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, 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 (podstawowe działania) znajdziesz przykłady takie jak GetCampaigns, GetKeywords i SearchForGoogleAdsFields.