Struktura zapytania

Zapytania dotyczące pól zasobów, segmentów i danych można wysyłać do metody Search lub SearchStream GoogleAdsService. Aby utworzyć zapytanie w języku Google Ads Query Language, użyj gramatyki języka. Ogólne informacje o języku Google Ads Query Language znajdziesz w artykule na jego temat. 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 porządkowania, aby ułatwić Ci wybór odpowiednich danych. Po połączeniu w jedno zapytanie możesz wysłać żądanie do interfejsu Google Ads API.

Klauzule

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

WYBIERZ

Klauzula SELECT określa zestaw pól, które mają zostać pobrane w żądaniu. SELECT przyjmuje listę pól zasobów, pól segmentów i danych rozdzieloną przecinkami i zwraca wartości w odpowiedzi. Klauzula SELECT jest wymagana w zapytaniu.

Poniższe przykładowe zapytanie pokazuje, jak wybrać atrybuty 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 zasobu głównego
    • campaign.id
    • campaign.name
  • Pola zasobów przypisanych
    • bidding_strategy.id
    • bidding_strategy.name
  • Pola segmentu
    • segments.device
    • segments.date
  • Dane
    • metrics.impressions
    • metrics.clicks
  • Wysyłanie zapytań o pola, których nie można wybrać. Atrybut metadanych selectable tych pól jest oznaczony jako false.
  • Wybieranie atrybutów pól powtarzanych. Atrybut metadanych is_repeated tych pól jest oznaczony jako true.
  • wybór pól, które są niedostępne dla danego zasobu w klauzuli FROM; Atrybutów niektórych zasobów nie można wybierać razem, a w przypadku zasobu we fragmencie kodu FROM dostępny jest tylko podzbiór wszystkich danych i segmentów.
  • wybór segmentów lub danych, które są ze sobą niezgodne; Więcej informacji znajdziesz w artykule na temat segmentacji.

Informacje dotyczące powyższych warunków można znaleźć w naszej dokumentacji referencyjnej lub na stronie GoogleAdsFieldService.

FROM

Klauzula FROM określa główny zasób, który ma zostać zwrócony. Zasób we fragmencie kodu FROM określa, jakich pól można używać we wszystkich pozostałych fragmentach kodu w danym zapytaniu. W klauzuli FROM można określić tylko 1 zasób. Klauzula FROM jest wymagana w zapytaniu do metody GoogleAdsService Search lub SearchStream. Jednak podczas korzystania z GoogleAdsFieldService nie należy podawać klauzuli FROM.

Chociaż w klauzuli FROM danego zapytania może występować tylko jeden zasób, dostępne mogą być też pola z zasobów przypisanych. Te zasoby są niejawnie połą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 przykładzie poniżej 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 pole ad_group.resource_name jest uwzględnione w odpowiedzi, mimo że nie zostało wyraźnie wybrane w zapytaniu:

SELECT ad_group.id
FROM ad_group

To samo dotyczy zasobów przypisanych, gdy wybrane jest co najmniej 1 pole. Na przykład campaign.resource_name jest uwzględniany 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. Używając klauzuli WHERE, określ co najmniej 1 warunek, oddzielając warunki operatorem AND. Warunki zwykle mają wzorzec field_name Operator value (lub używają BETWEEN value AND value, IS NULL lub IS NOT NULL). Klauzula WHERE jest opcjonalna w zapytaniu.

W przykładzie poniżej użyto WHERE, aby zwrócić dane z danego okresu:

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

Możesz połączyć kilka warunków, aby filtrować dane. Ten przykład żąda 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ą też występować w klauzuli SELECT, z wyjątkiem tych segmentów daty, które są nazywane podstawowymi segmentami daty:

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

W poniższym zapytaniu wybrano segments.date. Ten segment jest podstawowym segmentem daty, dlatego musisz podać skończony zakres dat w klauzuli WHERE składającej się z podstawowych segmentów daty:

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

Wszystkie segmenty, które spełniają poprzedni warunek, to segments.date, segments.week, segments.month, segments.quarter i segments.year. Jeśli wybrano którykolwiek z tych segmentów, co najmniej jeden z nich musi być użyty w klauzuli WHERE.

Więcej informacji o filtrowaniu według daty znajdziesz w artykule Zakresy dat.

Podczas filtrowania pamiętaj o uwzględnianiu wielkości liter w operatorze. Więcej informacji znajdziesz w sekcji Uwzględnianie wielkości liter.

Pełną listę operatorów znajdziesz w gramatyce 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 sortowanie jest określone jako field_name, po którym następuje ASC lub DESC. Jeśli nie określono ani ASC, ani DESC, domyślnie używana jest kolejność 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, używając listy rozdzielonej przecinkami. Kolejność jest 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, 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 potrzebujesz tylko podzbioru wyników.

Na przykład LIMIT może 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ć metaparametry żądania. Te parametry mogą wpływać na to, jakie rodzaje wierszy są zwracane.

Obsługiwane są te metaparametry:

include_drafts

Ustaw include_drafts na true, aby zwracać elementy w wersji roboczej. 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

omit_unselected_resource_names

Ustaw omit_unselected_resource_names na true, aby pominąć nazwę zasobu każdego typu zasobu w odpowiedzi, chyba że jest to wyraźnie wymagane w klauzuli SELECT. Domyślna wartość to false.

Zapytanie Zwrócone zasoby 
SELECT
  campaign.name,
  customer.id
FROM campaign
  • campaign.resource_name
  • customer.resource_name

Domyślna wartość parametru omit_unselected_resource_names to false, więc zwracane są wszystkie pola resource_name.

 
SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

Brak

Parametr omit_unselected_resource_names jest określony jako true, a ani campaign.resource_name, ani customer.resource_name nie jest częścią klauzuli SELECT.

 
SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true
  • campaign.resource_name

Wartość omit_unselected_resource_names jest określona jako true, a wartość campaign.resource_name jest wymagana w ramach klauzuli SELECT.

Dodatkowe reguły językowe

Oprócz przykładów dla każdej klauzuli język zapytań Google Ads obsługuje te zachowania:

  • Pole zasobu głównego nie jest wymagane w klauzuli SELECT zapytania. Możesz na przykład użyć co najmniej jednego pola zasobu głównego do filtrowania danych bez ich wybierania:

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

  • Wskaźniki można wybierać wyłącznie dla danego zasobu. Żadne inne pola z zasobu nie są wymagane w zapytaniu:

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

  • Pola segmentacji można wybierać bez żadnych powiązanych 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'
Wstecz
Gramatyka zapytania
Dalej
Zakresy dat