Ta strona została przetłumaczona przez Cloud Translation API.

Struktura zapytania

Zapytania dotyczące pól zasobów, segmentów i danych można wysyłać do metod wyszukiwania lub SearchStream w GoogleAdsService. Aby utworzyć zapytanie w języku zapytań Google Ads, musisz je utworzyć za pomocą gramatyki językowej. 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 zamówień, aby ułatwić wybór właściwych danych. Po połączeniu zapytania w jedno żądanie można wysłać żądanie za pomocą interfejsu Google Ads API.

Klauzule

Film: zgodność pola GAQL

WYBIERZ

Klauzula SELECT określa zestaw pól do pobrania. SELECT pobiera rozdzieloną przecinkami listę pól zasobów, pól segmentu 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 danego zasobu:

SELECT
  campaign.id,
  campaign.name
FROM campaign

W jednym żą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
Dane
- metrics.impressions
- metrics.clicks

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

Zapytania, których nie można wybrać. Będzie on miał atrybut metadanych Selectable oznaczony jako false.
Wybieranie atrybutów powtórzonych pól. Będzie on miał atrybut metadanych isRepeated oznaczony jako true.
Wybierz pola, które są niedostępne w przypadku danego zasobu w klauzuli FROM. Nie można wybrać razem atrybutów niektórych zasobów. W klauzuli FROM dostępne będą tylko zbiory danych i segmentów.
Wybranie segmentów lub danych, które są ze sobą niezgodne. Więcej informacji na ten temat znajdziesz w sekcji podziału na segmenty.

Informacje związane z powyższymi warunkami 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órych można użyć w innych klauzulach dla danego zapytania. W klauzuli FROM można podać tylko jeden zasób. Klauzula FROM jest wymagana w zapytaniu do metod GoogleAdsService Search lub SearchStream, ale nie należy ich używać podczas korzystania z GoogleAdsFieldService.

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

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Pole resource_name zasobu głównego jest zawsze zwracane. W tym przykładzie fragment ad_group.resource_name zostanie uwzględniony w odpowiedzi, mimo że nie zostanie wyraźnie wybrany w zapytaniu:

SELECT ad_group.id
FROM ad_group

To samo dotyczy innych zasobów po zaznaczeniu co najmniej jednego pola. Na przykład odpowiedź campaign.resource_name będzie uwzględniona 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. Gdy używasz klauzuli WHERE, możesz określić co najmniej 1 warunek za pomocą właściwości AND. Każdy warunek powinien być zgodny ze wzorcem field_name Operator value. Klauzula WHERE jest opcjonalna w zapytaniu.

Poniższy przykład pokazuje, jak użyć funkcji WHERE do zwrócenia danych z wybranego okresu:

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

Aby filtrować dane, możesz łączyć wiele warunków. W tym przykładzie zażądano 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ć w klauzuli SELECT z następującymi segmentami daty nazywanymi podstawowymi segmentami dat. Wyjątkiem są te segmenty:

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

W poniższym zapytaniu zaznaczono segments.date. Jako że ten segment jest głównym segmentem dat, musisz podać skończony zakres dat składający się 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ższe warunki 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 nich.

Ważne jest, aby podczas filtrowania pamiętać o wielkości liter operatora. Więcej informacji znajdziesz w artykule Uwzględnianie wielkości 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żde z kolejności jest określane jako field_name, po którym następuje ASC lub DESC. Jeśli nie określono właściwości ASC ani DESC, kolejność jest domyślnie ustawiona na ASC. Klauzula ORDER BY jest opcjonalna w zapytaniu.

Następujące zapytanie sortuje zwrócone kampanie według liczby kliknięć: od najwyższej do najniższej:

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

W klauzuli ORDER BY możesz określić wiele pól, korzystając z listy rozdzielanej przecinkami. Kolejność będzie taka sama jak w zapytaniu. Na przykład w tym zapytaniu wybierającym dane grupy reklam wyniki są sortowane w kolejności rosnącej według nazwy kampanii, następnie w kolejności malejącej według liczby wyświetleń, 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 (limit)

Klauzula LIMIT pozwala określić liczbę wyników, które zostaną zwrócone. Jest to przydatne, jeśli interesuje Cię tylko podsumowanie.

Za pomocą 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 parametrów meta żądania. Te parametry mogą wpływać na rodzaj zwracanych wierszy.

Obecnie obsługiwane są te metadane:

wersje robocze

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

Na przykład to zapytanie pobiera wersje robocze kampanii wraz ze zwykłymi kampaniami:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

brak nazwy_wybranego_zasobu

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

przykłady omit_unselected_resource_names
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 wszystkie pola resource_name zostaną zwrócone.
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` i `campaign.resource_name` określony w klauzuli `SELECT`.

Dodatkowe reguły językowe

Oprócz przykładów z każdej klauzuli Język zapytań Google Ads ma wiele zastosowań.

Nie jest wymagane, aby pole zapytania głównego zasobu znajdowało się w klauzuli SELECT. Możesz np. użyć tylko jednego głównego pola zasobów, aby filtrować dane:
```
SELECT campaign.id
FROM ad_group
WHERE ad_group.status = PAUSED
```
Wskaźniki mogą być wybrane tylko dla danego zasobu. W zapytaniu nie są wymagane żadne inne pola z zasobu:
```
SELECT
  metrics.impressions,
  metrics.clicks,
  metrics.costMicros
FROM campaign
```
Pola podziału na segmenty możesz wybrać bez towarzyszących pól zasobów lub danych:
```
SELECT segments.device FROM campaign
```

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

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