Struktura zapytania

Zapytania dotyczące pól zasobów, segmentów i danych można wysyłać do metod GoogleAdsService Search lub SearchStream. Aby utworzyć zapytanie w języku zapytań Google Ads, musisz je zbudować, korzystając z gramatyki języka. Zapytanie składa się z kilku klauzul:

• SELECT
• FROM
• WHERE
• ORDER BY
• LIMIT
• PARAMETERS

Aby pomóc Ci w wybieraniu odpowiednich danych, klauzule używają nazwy pól, nazwy zasobów, operatorów, warunków i kolejności. Po połączeniu w pojedyncze zapytanie można wysłać żądanie za pomocą interfejsu Google Ads API.

Ważna informacja: GoogleAdsFieldService udostępnia klientom języka zapytań Google Ads katalog z metadanymi dotyczącymi wszystkich pól zasobu, pól segmentu i danych, a także ich wzajemnych relacji i dostępności w każdej klauzuli zgodnie z definicją podaną poniżej. Więcej informacji znajdziesz w dokumentacji GoogleAdsField.

Klauzule

Film: zgodność pól GAQL

WYBIERZ

Klauzula SELECT określa zestaw pól do pobrania w żądaniu. SELECT przyjmuje listę pól zasobów, pól segmentów i danych oddzielonych przecinkami, a w odpowiedzi zwraca wartości. W zapytaniu wymagana jest klauzula SELECT.

Przykładowe zapytanie poniżej pokazuje wybór atrybutów danego zasobu:

SELECT
  campaign.id,
  campaign.name
FROM campaign

W jednym żądaniu możesz poprosić o różne typy pól, np.:

SELECT
  campaign.id,
  campaign.name,
  bidding_strategy.id,
  bidding_strategy.name,
  segments.device,
  segments.date,
  metrics.impressions,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

• Pola zasobów

  • campaign.id
  • campaign.name

• Pola zasobów

  • bidding_strategy.id
  • bidding_strategy.name

• Pola segmentu

  • segments.device
  • segments.date

• Dane

  • metrics.impressions
  • metrics.clicks

Niektóre pola mogą nie być dozwolone w klauzuli SELECT ze względu na te ograniczenia:

• Zapytania dotyczące pól, które nie są możliwe do wybrania. Atrybuty metadanych tych pól (Selectable) będą oznaczone jako false.
• Wybieranie atrybutów pól powtarzanych. Atrybuty metadanych tych pól (isRepeated) będą oznaczone jako true.
• Wybieranie pól, które nie są dostępne dla danego zasobu w klauzuli FROM. Atrybutów niektórych zasobów nie można wybierać razem, a dla zasobu w klauzuli FROM będzie dostępny tylko podzbiór wszystkich danych i segmentów.
• Wybieranie segmentów lub danych, które są ze sobą niezgodne. Więcej informacji na ten temat znajdziesz w sekcji dotyczącej podziału na segmenty.

Informacje związane z powyższymi warunkami znajdziesz w naszych dokumentach referencyjnych lub w GoogleAdsFieldService.

FROM

Klauzula FROM określa główny zasób, który zostanie zwrócony. Zasoby w klauzuli FROM określają, których pól można używać we wszystkich pozostałych klauzulach danego zapytania. W klauzuli FROM można podać tylko 1 zasób. Klauzula FROM jest wymagania w zapytaniu do metod GoogleAdsService Search lub SearchStream. Jednak podczas korzystania z funkcji GoogleAdsFieldService nie należy określać klauzuli FROM.

W przypadku danego zapytania w klauzuli FROM może występować tylko 1 zasób, ale mogą być też dostępne pola z zasobów przypisanych. Te zasoby są dołączane do zasobu w nawiasach klamrowych FROM, więc aby zwrócić ich wartości, wystarczy dodać ich atrybuty do nawiasu klamrowego SELECT. Nie wszystkie zasoby mają przypisane zasoby. W tym przykładzie możesz poprosić o identyfikator grupy reklam i identyfikator kampanii:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Zawsze zwracane jest pole resource_name zasobu głównego. W tym przykładzie parametr ad_group.resource_name zostanie uwzględniony w odpowiedzi, mimo że nie został wybrany w zapytaniu:

SELECT ad_group.id
FROM ad_group

To samo dotyczy innych zasobów, gdy wybrane jest co najmniej 1 pole. Na przykład: campaign.resource_name zostanie uwzględnione w odpowiedzi na to zapytanie:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Ważna informacja: jeśli zasób w klauzuli FROM zawiera w elementzie segment inny zasób, wybranie dowolnych atrybutów tego zasobu będzie działać jako segment.

WHERE

Klauzula WHERE określa warunki stosowane podczas filtrowania danych w ramach żądania. Jeśli używasz klauzuli WHERE, możesz określić co najmniej 1 warunek, rozdzielając go znakiem AND. Każdy warunek powinien być zgodny ze wzorcem field_name Operator value. Klauzula WHERE jest opcjonalna w zapytaniu.

Oto przykład użycia zapytania WHERE do zwrócenia danych z określonego przedziału czasu:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Aby filtrować dane, możesz łączyć ze sobą wiele warunków. W tym przykładzie żądamy liczby kliknięć we wszystkich kampaniach z wyświetleniami na urządzeniach mobilnych w ciągu ostatnich 30 dni.

SELECT
  campaign.id,
  campaign.name,
  segments.device,
  metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
  AND segments.device = MOBILE
  AND segments.date DURING LAST_30_DAYS

Segmenty w klauzuli WHERE muszą znajdować się w klauzuli SELECT, z wyjątkiem tych segmentów dat, które są nazywane podstawowymi segmentami dat:

• segments.date
• segments.week
• segments.month
• segments.quarter
• segments.year

W tym zapytaniu wybrana jest opcja segments.date. Ponieważ jest to podstawowy segment dat, wymaga on zdefiniowania ograniczonego zakresu dat składającego się z podstawowych segmentów dat w klauzuli WHERE.

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Wszystkie segmenty, które spełniają powyższy warunek, to: segments.date, segments.week, segments.month, segments.quarter i segments.year. Jeśli wybierzesz któryś z tych segmentów, musisz użyć co najmniej jednego z nich w klauzuli WHERE.

Ważna uwaga: separatora AND można używać tylko między warunkami operatora (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE"), a nie w ramach pojedynczego warunku operatora (WHERE segments.device != "DESKTOP" AND "MOBILE").

Podczas filtrowania należy pamiętać o tym, że wielkość liter w operatorze ma znaczenie. Więcej informacji znajdziesz w sekcji Znaczenie wielkości liter.

Pełną listę operatorów znajdziesz w gramatyce języka.

ORDER BY

Klauzula ORDER BY określa kolejność zwracania wyników. Dzięki temu możesz układać dane w kolejności rosnącej lub malejącej na podstawie nazwy pola. Każde uporządkowanie jest określone jako field_name, po którym następuje ASC lub DESC. Jeśli nie określono ani właściwości ASC, ani DESC, zamówienie przyjmie domyślnie wartość ASC. Klauzula ORDER BY jest opcjonalna w zapytaniu.

Podane niżej zapytanie sortuje zwrócone kampanie według liczby kliknięć od największej do najmniejszej:

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

W klauzuli ORDER BY możesz podać wiele pól, korzystając z listy rozdzielonej przecinkami. Sortowanie nastąpi w tej samej kolejności, jaką określono w zapytaniu. Na przykład w tym zapytaniu, które wybiera dane o grupach reklam, wyniki zostaną posortowane w kolejności rosnącej według nazwy kampanii, a potem w kolejności malejącej według liczby wyświetleń i w kolejności malejącej według liczby kliknięć:

SELECT
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks
FROM ad_group
ORDER BY
  campaign.name,
  metrics.impressions DESC,
  metrics.clicks DESC

LIMIT

Klauzula LIMIT umożliwia określenie liczby wyników do zwrócenia. Jest to przydatne, jeśli interesuje Cię tylko podsumowanie.

Na przykład za pomocą parametru LIMIT możesz ograniczyć łączną liczbę wyników w ramach tego zapytania:

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

Ważne: ciąg LIMIT pozwala obcinać wyniki. Użyj GoogleAdsService.Search, aby obsłużyć długie listy wyników.

PARAMETRY

Klauzula PARAMETERS umożliwia określenie metaparametrów żądania. Te parametry mogą wpływać na rodzaje zwracanych wierszy.

Obsługiwane są te parametry metadanych:

include_drafts

Aby umożliwić zwracanie wersji roboczych, ustaw wartość parametru include_drafts na true. Domyślna wartość to false.

Na przykład to zapytanie zwraca zarówno kampanie robocze, jak i zwykłe:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

Ustaw wartość parametru omit_unselected_resource_names na true, aby zapobiec zwracaniu nazwy zasobu każdego typu zasobu w odpowiedzi, chyba że zostanie ona wyraźnie zażądana w klauzuli SELECT. Domyślna wartość to false.

Uwaga: jeśli zamierzasz używać zwracanych obiektów do operacji aktualizacji lub usuwania, zalecamy ustawienie tej opcji na false, ponieważ zasobów bez nazw nie można używać w operacjach modyfikacji. Jeśli ustawisz tę opcję na true, pamiętaj, aby wyraźnie poprosić o nazwy zasobów zarówno zasobu głównego, jak i wszelkich zasobów atrybutów pobieranych za pomocą zapytania.

omit_unselected_resource_names przykłady
SELECT campaign.name, customer.id FROM campaign	Returned resources: campaign.resource_name customer.resource_name omit_unselected_resource_names ma domyślną wartość false, więc zwracane są wszystkie pola resource_name.
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true	Returned resources: Brak omit_unselected_resource_names jest określony jako true a campaign.resource_name i customer.resource_name nie są częścią klauzuli SELECT.
SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true	Returned resource: campaign.resource_name omit_unselected_resource_names jest określony jako true, a campaign.resource_name jest wymagany w ramach klauzuli SELECT.

Dodatkowe zasady językowe

Oprócz przykładów dotyczących poszczególnych klauzul język zapytań Google Ads umożliwia też stosowanie tych zachowań:

• W zapytaniu nie musi występować w klauzuli SELECT pole głównego zasobu. Możesz np. filtrować dane, korzystając tylko z jednego lub większej liczby pól zasobu głównego:

  SELECT campaign.id
  FROM ad_group
  WHERE ad_group.status = PAUSED
  

• Dane można wybierać tylko w przypadku danego zasobu. W zapytaniu nie trzeba podawać innych pól tego zasobu:

  SELECT
    metrics.impressions,
    metrics.clicks,
    metrics.cost_micros
  FROM campaign
  

• Pola segmentacji można wybierać bez towarzyszących pól zasobów ani danych:

  SELECT segments.device FROM campaign
  

• Pola resource_name (np. campaign.resource_name) można używać do filtrowania i sortowania danych:

  SELECT
    campaign.id,
    campaign.name
  FROM campaign
  WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'