Struktura zapytania

Zapytania dotyczące pól zasobów, segmentów i rodzajów danych można wysyłać do metod GoogleAdsService Search lub SearchStream. Aby utworzyć zapytanie w języku zapytań Google Ads, musisz użyć gramatyki języka. 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

ondemand_video Film: zgodność pól GAQL

WYBIERZ

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

Przykładowe zapytanie poniżej pokazuje, jak wybrać atrybuty dla 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 zasobów

  • campaign.id
  • campaign.name

• Pola zasobów

  • bidding_strategy.id
  • bidding_strategy.name

• Pola segmentu

  • segments.device
  • segments.date

• Dane

  • metrics.impressions
  • metrics.clicks

Niektóre pola mogą być niedozwolone w klauzuli SELECT z powodu tych ograniczeń:

• Wykonywanie 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 isRepeated oznaczony jako true.
• wybieranie pól, które nie są dostępne dla danego zasobu w klauzuli FROM; Atrybutów niektórych zasobów nie można wybierać razem. W klauzuli FROM dostępna będzie też tylko część wszystkich danych i segmentów.
• wybieranie segmentów lub danych, które nie są ze sobą zgodne; Więcej informacji na ten temat znajdziesz w sekcji dotyczącej segmentacji.

Informacje dotyczące powyższych warunków znajdziesz w naszej dokumentacji referencyjnej lub GoogleAdsFieldService.

FROM

Klauzula FROM określa główny zasób, który zostanie zwrócony. Zasób w klauzuli FROM określa, których pól można używać we wszystkich pozostałych klauzulach w danym zapytaniu. W klauzuli FROM można określić tylko jeden zasób. Klauzula FROM jest wymagana w zapytaniu do metod GoogleAdsService Search lub SearchStream. Klauzula FROM nie powinna być jednak określana podczas korzystania z funkcji GoogleAdsFieldService.

W przypadku danego zapytania w klauzuli FROM może istnieć 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 poniższym 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 w odpowiedzi zostanie uwzględniony parametr ad_group.resource_name, mimo że nie został on 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. Każdy warunek powinien być zgodny ze wzorcem field_name Operator value. Klauzula WHERE jest w zapytaniu opcjonalna.

Oto przykład użycia 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. W tym przykładzie zostanie wysłane żądanie liczby kliknięć we wszystkich kampaniach, w których w ciągu ostatnich 30 dni wystąpił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 segmentem daty podstawowej, dlatego wymaga podania skończonego zakresu dat składającego się z segmentów daty podstawowej 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órykolwiek z tych segmentów, musisz użyć co najmniej jednego z nich w klauzuli WHERE.

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 w porządku rosnącym lub malejącym 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ślisz wartości ASC ani DESC, zamówienie domyślnie przyjmie wartość 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 rosnąco według nazwy kampanii, a następnie malejąco 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 przypadku 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 rodzaje zwracanych wierszy.

Obsługiwane są te parametry meta:

include_drafts

Ustaw wartość include_drafts na true, aby zezwolić na zwracanie elementów wersji roboczej. 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 ona wyraźnie zażądana 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 reguły językowe

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

• Nie jest wymagane, aby główne pole zasobu znajdowało się w klauzuli SELECT w przypadku zapytania. 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 lub danych:

  SELECT segments.device FROM campaign
  

• Pole resource_name (np. campaign.resource_name) może służyć do filtrowania lub sortowania danych:

  SELECT
    campaign.id,
    campaign.name
  FROM campaign
  WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'