Struktura zapytania

Zapytania o pola zasobów, segmentów i danych można wysyłać do GoogleAdsService Search lub SearchStream metod. Aby utworzyć zapytanie w języku Google Ads Query Language, musisz je zbudować zgodnie z gramatyką tego języka. Ogólny opis języka Google Ads Query Language znajdziesz w artykule Omówienie języka Google Ads Query Language. Zapytanie składa się z kilku klauzul:

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

Klauzule używają nazw pól, nazw zasobów, operatorów, warunków i kolejności, aby pomóc Ci wybrać prawidłowe dane. Gdy połączysz je w jedno zapytanie, możesz wysłać żądanie za pomocą interfejsu Google Ads API.

Klauzule

ondemand_video Film: zgodność pól GAQL

SELECT

Klauzula SELECT określa zestaw pól do pobrania w żądaniu. Klauzula SELECT przyjmuje rozdzieloną przecinkami listę pól zasobów, pól segmentów i danych, zwracając wartości w odpowiedzi. Klauzula SELECT jest wymagana w zapytaniu.

Przykładowe zapytanie poniżej pokazuje, jak wybrać atrybuty 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 segmentów

  • segments.device
  • segments.date

• Dane

  • metrics.impressions
  • metrics.clicks

• Wykonywanie zapytań o pola, których nie można wybrać. W przypadku tych pól atrybut metadanych Selectable będzie oznaczony jako false.
• Wybieranie atrybutów pól powtarzanych. W przypadku tych pól atrybut metadanych isRepeated będzie oznaczony jako true.
• Wybieranie pól, które nie są dostępne w przypadku danego zasobu w klauzuli FROM. Nie można wybierać razem atrybutów niektórych zasobów. Ponadto w przypadku zasobu w klauzuli FROM dostępny będzie tylko podzbiór wszystkich danych i segmentów.
• Wybieranie segmentów lub danych, które nie są ze sobą zgodne. Więcej informacji na ten temat znajdziesz w sekcji dotyczącej segmentacji.

Informacje dotyczące powyższych warunków znajdziesz w dokumentacji lub w GoogleAdsFieldService.

FROM

Klauzula FROM określa główny zasób, który zostanie zwrócony. Zasób w klauzuli FROM określa, jakich pól można używać we wszystkich innych klauzulach danego zapytania. W klauzuli FROM można określić tylko 1 zasób. Klauzula FROM jest wymagana w zapytaniu do GoogleAdsService Search lub SearchStream metod. Jednak klauzula FROM nie powinna być określona w przypadku korzystania z GoogleAdsFieldService.

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

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Pole resource_name głównego zasobu jest zawsze zwracane. W tym przykładzie pole ad_group.resource_name zostanie uwzględnione w odpowiedzi, mimo że nie zostało wyraźnie wybrane w zapytaniu:

SELECT ad_group.id
FROM ad_group

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

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE

Klauzula WHERE określa warunki, które mają być stosowane podczas filtrowania danych na potrzeby żądania. Gdy używasz klauzuli WHERE, możesz określić co najmniej 1 warunek, oddzielając je za pomocą AND. Każdy warunek powinien być zgodny ze wzorcem field_name Operator value. Klauzula WHERE jest opcjonalna w zapytaniu.

Oto przykład użycia klauzuli WHERE do zwracania danych z danego okresu:

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

Możesz połączyć kilka warunków, aby filtrować dane. Ten przykład spowoduje wysłanie żądania 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. Wyjątkiem są te segmenty dat, które są nazywane podstawowymi segmentami dat, :

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

W tym zapytaniu zwróć uwagę, że wybrany jest segment segments.date. Ponieważ ten segment jest podstawowym segmentem dat, wymaga podania w klauzuli WHERE skończonego zakresu dat składającego się z podstawowych segmentów dat.

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órykolwiek z tych segmentów, co najmniej 1 z nich musi być użyty w klauzuli WHERE.

Więcej informacji o filtrowaniu według dat znajdziesz w artykule Zakresy dat.

Podczas filtrowania ważne jest, aby pamiętać o rozróżnianiu wielkości liter w operatorze. Więcej informacji znajdziesz w artykule Rozróżnianie wielkości liter.

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

ORDER BY

Klauzula ORDER BY określa kolejność, w jakiej mają być zwracane wyniki. Umożliwia to uporządkowanie danych w porządku rosnącym lub malejącym na podstawie nazwy pola. Każda kolejność jest określana jako field_name , po której następuje ASC lub DESC. Jeśli nie określono ani ASC, ani DESC, domyślnie używana jest kolejność ASC. Klauzula ORDER BY jest opcjonalna w zapytaniu.

To zapytanie porządkuje zwracane 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 określić wiele pól, używając listy rozdzielonej przecinkami. Kolejność będzie taka sama jak w zapytaniu. Na przykład w tym zapytaniu wybierającym dane grupy reklam wyniki zostaną posortowane w porządku rosnącym według nazwy kampanii, a następnie w porządku malejącym według liczby wyświetleń, a potem w porządku malejącym 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 klauzuli LIMIT można użyć do ograniczenia łącznej liczby wyników tego zapytania:

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

PARAMETERS

Klauzula PARAMETERS umożliwia określenie parametrów meta dla żądania. Te parametry mogą wpływać na to, jakie rodzaje wierszy są zwracane.

Obsługiwane są te parametry meta:

include_drafts

Ustaw wartość include_drafts na true, aby umożliwić zwracanie jednostek wersji roboczej. Domyślna wartość to false.

Na przykład to zapytanie pobiera kampanie w wersji roboczej wraz ze zwykłymi kampaniami:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

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

SELECT
  campaign.name,
  customer.id
FROM campaign

SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true

Dodatkowe reguły języka

Oprócz przykładów dotyczących każdej klauzuli język Google Ads Query Language ma te zachowania, które można wykorzystać:

• Pole zasobu głównego nie musi znajdować się w klauzuli SELECT zapytania. Możesz np. używać tylko 1 lub kilku pól zasobu głównego do filtrowania danych:

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

• W przypadku danego zasobu można wybrać wyłącznie dane. W zapytaniu nie są wymagane żadne inne pola z tego zasobu:

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

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

  SELECT segments.device FROM campaign
  

• Pola resource_name (campaign.resource_name, np.) można używać do filtrowania lub porządkowania danych:

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