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
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 jakofalse
. - Wybieranie atrybutów powtórzonych pól. Będzie on miał atrybut metadanych
isRepeated
oznaczony jakotrue
. - 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 klauzuliFROM
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 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'