Struktura zapytania

Zapytania o pola zasobów, segmentów i danych można wysyłać do metody GoogleAdsService Search lub SearchStream. Aby utworzyć zapytanie w języku Google Ads Query Language, użyj gramatyki tego języka. Ogólne informacje o języku Google Ads Query Language znajdziesz w artykule Omówienie języka Google Ads Query Language. 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ć prawidłowe dane. Po połączeniu w jedno zapytanie możesz wysłać żądanie do interfejsu Google Ads API.

Klauzule

W sekcjach poniżej znajdziesz opis celu i składni każdej klauzuli języka Google Ads Query Language.

SELECT

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, zwracając wartości w odpowiedzi. Klauzula SELECT jest wymagana w zapytaniu.

Ten przykładowy kod 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, 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
  • Pola zasobu głównego
    • campaign.id
    • campaign.name
  • Pola zasobu powiązanego
    • 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ć. W przypadku tych pól atrybut metadanych selectable jest oznaczony jako false.
  • Wybieranie atrybutów pól powtarzanych. W przypadku tych pól atrybut metadanych is_repeated jest oznaczony jako true.
  • Wybieranie pól, które nie są dostępne w przypadku danego zasobu w klauzuli FROM. Nie można wybrać razem atrybutów niektórych zasobów, a w przypadku zasobu w klauzuli FROM dostępny jest tylko podzbiór wszystkich danych i segmentów.
  • Wybieranie segmentów lub danych, które nie są ze sobą zgodne. Więcej informacji znajdziesz w sekcji Podział na segmenty.

Informacje związane z powyższymi warunkami znajdziesz w dokumentacji lub w GoogleAdsFieldService.

FROM

Klauzula FROM określa główny zasób do zwrócenia. Zasób w klauzuli FROM określa, które pola można używać we wszystkich innych klauzulach danego zapytania. W klauzuli FROM można określić tylko 1 zasób. Klauzula FROM jest wymagana w zapytaniu do metody GoogleAdsService Search lub SearchStream. Jednak klauzula FROM nie powinna być określona w przypadku korzystania z GoogleAdsFieldService.

W klauzuli FROM danego zapytania może znajdować się tylko 1 zasób, ale mogą być też dostępne pola z zasobów powiązanych. 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ą zasoby powiązane. 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 zasobu głównego jest zawsze zwracane. W tym przykładzie ad_group.resource_name jest uwzględniane w odpowiedzi, mimo że nie zostało wyraźnie wybrane w zapytaniu:

SELECT ad_group.id
FROM ad_group

To samo dotyczy zasobów powiązanych, gdy wybrano co najmniej 1 pole. Na przykład campaign.resource_name jest uwzględniane 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. Gdy używasz klauzuli WHERE, określ co najmniej 1 warunek rozdzielony operatorem 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 opcjonalna w zapytaniu.

Ten przykład używa klauzuli WHERE do zwracania danych 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ż znajdować się w klauzuli SELECT, z wyjątkiem tych segmentów dat, które są nazywane podstawowymi segmentami daty:

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

W tym zapytaniu wybrany jest segment segments.date. Ponieważ ten segment jest podstawowym segmentem daty, w klauzuli WHERE musisz podać skończony zakres dat składający 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ą powyższy warunek, to segments.date, segments.week, segments.month, segments.quarter i segments.year. Jeśli którykolwiek z tych segmentów jest wybrany, co najmniej 1 z nich musi być użyty w klauzuli WHERE.

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

Podczas filtrowania pamiętaj o rozróżnianiu wielkości liter w operatorze. Więcej informacji znajdziesz w sekcji Rozróżnianie wielkości 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 w kolejności rosnącej lub malejącej na podstawie nazwy pola. Każda kolejność jest określana jako field_name z dopiskiem ASC lub DESC. Jeśli nie określono ani ASC, ani DESC, kolejność domyślnie jest ustawiona na ASC. Klauzula ORDER BY jest opcjonalna w zapytaniu.

To zapytanie porządkuje zwracane 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ć kilka 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, następnie w kolejności malejącej według liczby wyświetleń, a potem 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 pozwala określić liczbę 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 w przypadku tego zapytania:

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

PARAMETERS

Klauzula PARAMETERS pozwala określić parametry meta dla żądania. Te parametry mogą wpływać na to, jakie rodzaje wierszy są zwracane.

Obsługiwane są te parametry meta:

include_drafts

Ustaw include_drafts na true, aby zwracać jednostki wersji roboczej. Domyślnie jest ustawiona wartość false.

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

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 została wyraźnie zażądana w klauzuli SELECT. Domyślnie jest ustawiona wartość false.

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

omit_unselected_resource_names ma domyślnie wartość false, więc zwracane są wszystkie pola resource_name fields are returned.

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

Brak

omit_unselected_resource_names ma wartość true, a ani campaign.resource_name, ani customer.resource_name nie są częścią klauzuli SELECT.

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

omit_unselected_resource_names ma wartość true, a campaign.resource_name jest żądana w ramach klauzuli SELECT.

Dodatkowe reguły języka

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

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

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

  • W przypadku danego zasobu można wybrać wyłącznie dane. 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 wybierać bez żadnych towarzyszących pól zasobów ani danych:

    SELECT segments.device FROM campaign

  • Pole resource_name (campaign.resource_name, np.) może być używane 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