Struktura zapytania

Zapytania dotyczące pól zasobów, segmentów i danych można wysyłać do metod GoogleAdsService Search lub SearchStream. Aby zbudować zapytanie w języku Google Ads Query Language, należy tworzyć je według gramatyki języka. Zapytanie składa się z kilku klauzul:

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

Aby ułatwić Ci wybór właściwych danych, klauzule korzystają z nazw pól, nazw zasobów, operatorów, warunków i kolejności. Po połączeniu w jedno zapytanie można wysłać żądanie za pomocą interfejsu Google Ads API.

Klauzule

Wideo: zgodność pól GAQL

SELECT

Klauzula SELECT określa zbiór pól do pobrania w żądaniu. SELECT pobiera oddzieloną przecinkami listę pól zasobów, pól segmentów i wskaźników, zwracając w odpowiedzi wartości. Klauzula SELECT jest wymagana w zapytaniu.

W przykładowym zapytaniu poniżej znajdziesz przykład wyboru atrybutów danego zasobu:

SELECT
  campaign.id,
  campaign.name
FROM campaign

W pojedynczym żądaniu możesz zażądać różnych typów pól, na przykład:

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
  • Wskaźniki

    • metrics.impressions
    • metrics.clicks

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

  • Zapytania dotyczące pól, których nie można wybrać. Te pola będą miały atrybut metadanych Selectable oznaczony jako false.
  • Wybieranie atrybutów pól powtarzanych. Te pola będą miały atrybut metadanych isRepeated oznaczony jako true.
  • Wybór pól, które są niedostępne w przypadku danego zasobu w klauzuli FROM. Nie można wybrać jednocześnie atrybutów niektórych zasobów. W klauzuli FROM dla zasobu będzie dostępny tylko podzbiór wszystkich wskaźników i segmentów.
  • Wybór segmentów lub danych, które są ze sobą niezgodne. Więcej informacji na ten temat znajdziesz w sekcji na temat podziału na segmenty.

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

FROM

Klauzula FROM określa zasób główny, który zostanie zwrócony. Zasób w klauzuli FROM określa, które pola mogą być używane we wszystkich pozostałych klauzulach danego zapytania. W klauzuli FROM można określić tylko 1 zasób. Klauzula FROM jest wymagana w zapytaniu w przypadku metod GoogleAdsService Search lub SearchStream, ale nie należy jej określać podczas korzystania z GoogleAdsFieldService.

Chociaż w klauzuli FROM dla danego zapytania może istnieć tylko 1 zasób, dostępne mogą być również pola z przypisanych zasobów. Te zasoby są niejawnie połączone z zasobem w klauzuli FROM. Wystarczy więc dodać do klauzuli SELECT tylko ich atrybuty, aby zwrócić ich wartości. Nie wszystkie zasoby mają przypisane zasoby. W poniższym przykładzie możesz zażądać od grup reklam zarówno identyfikatora grupy reklam, jak i identyfikatora kampanii:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Pole resource_name głównego zasobu jest zawsze zwracane. W tym przykładzie parametr ad_group.resource_name zostanie uwzględniony w odpowiedzi, mimo że nie został wyraźnie 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 w odpowiedzi na to zapytanie: campaign.resource_name:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE

Klauzula WHERE określa warunki, które mają być stosowane przy filtrowaniu danych na potrzeby żądania. W przypadku klauzuli WHERE 1 lub więcej warunków można rozdzielić 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 funkcji WHERE do zwrócenia danych z danego okresu:

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

Aby filtrować dane, możesz połączyć kilka warunków. W tym przykładzie poprosimy o liczbę 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 i zawierać te segmenty dat, które są określane jako podstawowe segmenty daty, a oprócz tego są wyjątkami:

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

W poniższym zapytaniu zaznaczono segments.date. Ten segment jest głównym segmentem dat, więc wymaga określenia skończonego zakresu dat złożonego 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 segmenty.data, segmenty.tydzień, segmenty.miesiąc, segmenty.kwartał i segmenty.rok. Jeśli wybierzesz dowolny z tych segmentów, w klauzuli WHERE musisz użyć co najmniej jednego z nich.

Podczas filtrowania należy pamiętać o rozróżnianiu wielkości liter operatora. Więcej informacji znajdziesz w artykule Uwzględnianie wielkości liter.

Pełną listę operatorów znajdziesz w sekcji dotyczącej gramatyki języka.

ORDER BY

Klauzula ORDER BY określa kolejność zwracania wyników. Pozwala to uporządkować dane w kolejności rosnącej lub malejącej na podstawie nazwy pola. Każda kolejność jest określana za pomocą symbolu field_name, po którym następuje ASC lub DESC. Jeśli nie określono żadnej wartości ASC ani DESC, domyślnie przyjmuje się ASC. Klauzula ORDER BY jest opcjonalna w zapytaniu.

To zapytanie porządkuje 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 określić wiele pól za pomocą listy rozdzielanej przecinkami. Kolejność będzie taka sama jak w zapytaniu. Na przykład zapytanie obejmujące dane grupy reklam zostaną posortowane w kolejności rosnącej według nazwy kampanii, a następnie w kolejności malejącej według liczby wyświetleń, a następnie 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.

Za pomocą funkcji LIMIT możesz na przykład ograniczyć łączną liczbę wyników dla tego zapytania:

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

PARAMETRY

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

Obecnie obsługiwane są następujące metaparametry:

include_drafts

Ustaw include_drafts na true, aby umożliwić zwracanie wersji roboczych elementów. Domyślna wartość to false.

Na przykład to zapytanie pobierze robocze wersje kampanii razem ze zwykłymi kampaniami:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

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

przykłady pominięcia_niewybranych_nazw_zasobów
SELECT
  campaign.name,
  customer.id
FROM campaign
Returned resources:
campaign.resource_name
customer.resource_name

omit_unselected_resource_names przyjmuje domyślnie wartość false, więc zwracane są wszystkie pola 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 wymagany w klauzuli SELECT jako true, a żądanie campaign.resource_name to campaign.resource_name.

Dodatkowe reguły dotyczące języka

Oprócz przykładów każdej klauzuli język zapytań Google Ads ma następujące działania:

  • Nie jest to wymagane, aby główne pole zasobu znajdowało się w klauzuli SELECT w przypadku zapytania. Możesz np. filtrować dane tylko za pomocą jednego lub kilku pól zasobów głównych:

    SELECT campaign.id
    FROM ad_group
    WHERE ad_group.status = PAUSED
    
  • Wskaźniki można wybrać wyłącznie dla danego zasobu. W zapytaniu nie są wymagane żadne inne pola z tego zasobu:

    SELECT
      metrics.impressions,
      metrics.clicks,
      metrics.costMicros
    FROM campaign
    
  • Pola podziału na segmenty można wybrać bez towarzyszących pól zasobów ani wskaźników:

    SELECT segments.device FROM campaign
    
  • Pole resource_name (np. campaign.resource_name) może służyć do filtrowania i sortowania danych:

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