Struktura zapytania

Zapytania dotyczące pól zasobów, segmentów i danych można wysyłać do metod GoogleAdsService wyszukiwania i SearchStream. Aby utworzyć zapytanie w języku zapytań Google Ads, musisz je utworzyć za pomocą gramatyki językowej. Zapytanie składa się z wielu klauzul:

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

W doboru prawidłowych danych służą nazwy pól, nazwy zasobów, operatory, warunki i zamówienia. Po połączeniu w jedno zapytanie możesz wysłać żądanie za pomocą Google Ads API.

Klauzule

ondemand_video Film: Zgodność pól GAQL

WYBIERZ

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

Przykładowe zapytanie poniżej pokazuje przykład wyboru atrybutów dla danego zasobu:

SELECT
  campaign.id,
  campaign.name
FROM campaign

W jednym żądaniu możesz poprosić o różne typy 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

• Dane

  • metrics.impressions
  • metrics.clicks

Niektóre pola mogą być niedozwolone w klauzuli SELECT z powodu tych ograniczeń:

• Zapytania dotyczące pól, których nie można wybrać. Będzie on miał atrybut metadanych Selectable oznaczony jako false.
• Wybieranie atrybutów pól powtarzanych. Będzie on miał atrybut metadanych isRepeated oznaczony jako true.
• Wybierz pola, które są niedostępne dla danego zasobu w klauzuli FROM. Nie można wybrać razem atrybutów niektórych zasobów. Dla zasobu w klauzuli FROM dostępny będzie tylko podzbiór wszystkich wskaźników i segmentów.
• Wybranie segmentów, które są ze sobą niezgodne. Więcej informacji znajdziesz w sekcji o segmentacji.

Informacje dotyczące powyższych warunków można znaleźć w naszych dokumentach referencyjnych lub na stronie GoogleAdsFieldService.

FROM

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

W klauzuli FROM dla danego zapytania może istnieć tylko 1 zasób, ale mogą być też dostępne pola z przypisanych zasobów. Zasoby te są domyślnie połączone z zasobem w klauzuli FROM, musisz więc tylko dodać ich atrybuty do klauzuli SELECT, aby zwrócić wartości. Nie wszystkie zasoby mają przypisane zasoby. W tym przykładzie możesz poprosić o identyfikator zarówno grupy reklam, jak i kampanii:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Pole resource_name zasobu głównego jest zawsze zwracane. W tym przykładzie w odpowiedzi zostanie umieszczony element ad_group.resource_name, który nie został wyraźnie wybrany w zapytaniu:

SELECT ad_group.id
FROM ad_group

To samo dotyczy innych zasobów, jeśli wybrano co najmniej jedno pole. Na przykład campaign.resource_name będzie 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 dla żądania. Jeśli używasz klauzuli WHERE, możesz podać co najmniej 1 warunek, aby oddzielić je od siebie za pomocą AND. Każdy warunek powinien być zgodny ze wzorcem field_name Operator value. Klauzula WHERE jest opcjonalna w zapytaniu.

Poniżej znajdziesz przykład użycia 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

Możesz filtrować dane, łącząc wiele warunków. W tym przykładzie zażądasz 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ą być zawarte w klauzuli SELECT, z następującymi segmentami dat nazywanymi podstawowymi segmentami dat, z wyjątkami:

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

W zapytaniu zaznacz opcję segments.date. Ponieważ ten segment jest głównym segmentem dat, musisz podać skończony zakres dat złożony z segmentów podstawowych dat w klauzuli WHERE.

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

Wszystkie segmenty spełniające powyższy warunek to: segment.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 tych segmentów.

Ważne jest, aby podczas filtrowania uwzględniać wielkość liter w operatorze pod względem wielkości liter. Więcej informacji znajdziesz w artykule Wielkość liter.

Pełną listę operatorów zawiera gramatyka 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ślona jako field_name, po której następuje ASC lub DESC. Jeśli nie określono właściwości ASC ani DESC, wartość domyślna kolejności to ASC. Klauzula ORDER BY jest opcjonalna w zapytaniu.

To zapytanie porządkuje zwrócone kampanie według liczby kliknięć od najwyższej do najniższej liczby:

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

W klauzuli ORDER BY możesz określić wiele pól, rozdzielając je przecinkami. Kolejność jest taka sama jak w zapytaniu. W tym zapytaniu, wybranym na podstawie danych grupy reklam, wyniki zostaną posortowane rosnąco według nazwy kampanii, następnie w kolejności malejącej według liczby wyświetleń, a następnie malejąco 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 pozwala określić liczbę wyników do zwrócenia. Jest to przydatne, jeśli interesuje Cię tylko podsumowanie.

Możesz na przykład użyć LIMIT, by 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 pozwala określić parametry meta dla żądania. Te parametry mogą wpływać na to, jakie wiersze są zwracane.

Obecnie obsługiwane są te parametry meta:

Uwzględnij wersje robocze

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

To zapytanie pobiera na przykład wersje robocze kampanii wraz ze zwykłymi kampaniami:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

brak nazwy_wybranego_zasobu

Aby zapobiec zwróceniu nazwy zasobu każdego typu zasobu w odpowiedzi, w klauzuli SELECT ustaw omit_unselected_resource_names jako true. 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ęzykowe

Oprócz przykładów w każdej klauzuli w języku zapytań Google Ads możesz zastosować te zachowania:

• Nie jest wymagane, aby główne pole zasobu w zapytaniu zawierało klauzulę SELECT. Możesz na przykład użyć tylko jednego głównego pola zasobów do filtrowania danych:

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

• W przypadku danego zasobu wskaźniki mogą być wybrane wyłącznie; zapytanie nie wymaga żadnych innych pól z zasobu:

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

• Pola do segmentacji można wybierać bez powiązanych pól zasobów i danych:

  SELECT segments.device FROM campaign
  

• Pole resource_name (np. campaign.resource_name) może służyć do filtrowania lub porządkowania danych:

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