Struktura zapytania

Zapytania dotyczące pól zasobów, segmentów i rodzajów danych można wysyłać za pomocą metod GoogleAdsService Search lub SearchStream. Aby utworzyć zapytanie w języku zapytań Google Ads, musisz użyć gramatyki języka. Ogólne omówienie języka zapytań Google Ads znajdziesz w artykule Omówienie języka zapytań Google Ads. 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 kolejności, aby pomóc Ci wybrać odpowiednie dane. Po połączeniu w jedno zapytanie można wysłać żądanie za pomocą interfejsu Google Ads API.

Klauzule

W sekcjach poniżej znajdziesz opis przeznaczenia i składni poszczególnych klauzul języka zapytań Google Ads.

WYBIERZ

Klauzula SELECT określa zestaw pól do pobrania w żądaniu. SELECT przyjmuje rozdzieloną przecinkami listę pól zasobów, pól segmentów i danych, a w odpowiedzi zwraca ich wartości. Klauzula SELECT jest wymagana w zapytaniu.

To przykładowe zapytanie pokazuje, jak wybrać atrybuty danego zasobu:

SELECT
  campaign.id,
  campaign.name
FROM campaign

W ramach jednego żądania możesz poprosić o różne typy pól, np.:

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

• Główne pola zasobu
  • campaign.id
  • campaign.name
• Pola zasobów z atrybucją
  • bidding_strategy.id
  • bidding_strategy.name
• Pola segmentu
  • segments.device
  • segments.date
• Dane
  • metrics.impressions
  • metrics.clicks

• Wysyłanie zapytań dotyczących pól, których nie można wybrać. Pola te będą miały atrybut metadanych selectable oznaczony jako false.
• wybieranie atrybutów pól powtarzanych; Pola te będą miały atrybut metadanych is_repeated oznaczony jako true.
• wybieranie w klauzuli FROMpól, które nie są dostępne w przypadku danego zasobu; Atrybutów niektórych zasobów nie można wybierać razem, a w klauzuli FROM dostępna będzie tylko część wszystkich rodzajów danych i segmentów.
• wybieranie segmentów lub danych, które są ze sobą niezgodne; Więcej informacji znajdziesz w sekcji dotyczącej segmentacji.

Informacje dotyczące powyższych warunków znajdziesz 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, które pola mogą być używane we wszystkich pozostałych klauzulach w danym zapytaniu. W klauzuli FROM można określić tylko 1 zasób. Klauzula FROM jest wymagana w zapytaniu do metod GoogleAdsService Search lub SearchStream. Jeśli jednak używasz atrybutu GoogleAdsFieldService, klauzula FROM nie powinna być określona.

W przypadku danego zapytania w klauzuli FROM może występować tylko 1 zasób, ale mogą być też dostępne pola z zasobów z atrybutami. Te zasoby są niejawnie łączone z zasobem w klauzuli FROM, więc aby zwrócić ich wartości, wystarczy dodać ich atrybuty do klauzuli SELECT. Nie wszystkie zasoby mają przypisane zasoby. W tym przykładzie możesz poprosić o identyfikator grupy reklam i identyfikator kampanii z grup reklam:

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 campaign.resource_name zostanie uwzględniony 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 na potrzeby żądania. W przypadku klauzuli WHERE można określić co najmniej 1 warunek, rozdzielając je znakiem AND. Warunki zwykle mają postać field_name Operator value (lub używają BETWEEN value AND value, IS NULL lub IS NOT NULL). Klauzula WHERE jest w zapytaniu opcjonalna.

Oto przykład użycia znaku WHERE do zwracania danych z określonego 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. Ten przykład wysyła żądanie liczby kliknięć wszystkich kampanii, które w ciągu ostatnich 30 dni uzyskały wyświetlenia na urządzeniach mobilnych:

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. Wyjątkiem są te segmenty dat, które są nazywane podstawowymi segmentami dat:

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

Zwróć uwagę, że w tym zapytaniu wybrano segments.date. Ten segment jest podstawowym segmentem dat, dlatego wymaga podania skończonego zakresu dat składającego się 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 segments.date, segments.week, segments.month, segments.quarter i segments.year. Jeśli wybierzesz któryś z tych segmentów, musisz użyć co najmniej jednego z nich w klauzuli WHERE.

Więcej informacji o filtrowaniu dat znajdziesz w sekcji Zakresy dat.

Podczas filtrowania pamiętaj o tym, czy operator uwzględnia wielkość liter. Więcej informacji znajdziesz w sekcji Wielkość liter.

Pełną listę operatorów znajdziesz w gramatyce języka.

ORDER BY

Klauzula ORDER BY określa kolejność, w jakiej mają być zwracane wyniki. Pozwala to uporządkować dane rosnąco lub malejąco na podstawie nazwy pola. Każde zamówienie jest określone jako field_name, a następnie ASC lub DESC. Jeśli nie określono ani ASC, ani DESC, domyślna kolejność to ASC. Klauzula ORDER BY jest w zapytaniu opcjonalna.

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, używając listy rozdzielonej przecinkami. Kolejność będzie taka sama jak w zapytaniu. Na przykład w tym zapytaniu wybierającym dane grupy reklam wyniki zostaną posortowane w kolejności rosnącej według nazwy kampanii, a następnie w kolejności malejącej według liczby wyświetleń i 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.

Na przykład parametru LIMIT można użyć, aby ograniczyć łączną liczbę wyników w tym zapytaniu:

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 rodzaje zwracanych wierszy.

Obsługiwane są te parametry meta:

include_drafts

Ustaw wartość include_drafts na true, aby zezwolić na zwracanie wersji roboczych encji. Domyślna wartość to false.

Na przykład to zapytanie pobiera kampanie w wersji roboczej wraz ze zwykłymi kampaniami:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

Ustaw wartość omit_unselected_resource_names na true, aby zapobiec zwracaniu nazwy zasobu każdego typu zasobu w odpowiedzi, chyba że zostanie to wyraźnie zażądane w klauzuli SELECT. 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 zasady językowe

Oprócz przykładów dotyczących poszczególnych klauzul język zapytań Google Ads ma te funkcje:

• W przypadku zapytania nie jest wymagane, aby główne pole zasobu znajdowało się w klauzuli SELECT. Możesz na przykład użyć tylko jednego lub kilku głównych pól zasobu do filtrowania danych:

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

• Dane można wybierać wyłącznie w przypadku danego zasobu. W zapytaniu nie są wymagane żadne inne pola z tego zasobu:

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

• Pola segmentacji można wybierać bez towarzyszących im pól zasobów ani 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'