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
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
Dane
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 jakofalse
. - Wybieranie atrybutów pól powtarzanych. Te pola będą miały atrybut metadanych
isRepeated
oznaczony jakotrue
. - 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 klauzuliFROM
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
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.cost_micros FROM campaign
Pola podziału na segmenty można wybrać bez towarzyszących pól zasobów lub 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'