Struktura zapytania

Zapytania dotyczące pól zasobu, segmentu i wskaźnika można wysyłać do metod GoogleAdsService wyszukiwania lub SearchStream. Aby utworzyć zapytanie w języku zapytania Google Ads, musisz je utworzyć za pomocą gramatyki językowej. Zapytanie składa się z wielu klauzul:

  • SELECT
  • FROM
  • WHERE
  • ORDER BY
  • LIMIT
  • PARAMETERS

Klauzule wykorzystują nazwy pól, nazwy zasobów, operatory, warunki i zamówienia, które ułatwiają wybór prawidłowych danych. Po połączeniu w jedno zapytanie można wysłać żądanie za pomocą interfejsu Google Ads API.

Klauzule

Film: zgodność z GAQL

WYBIERZ

Klauzula SELECT określa zestaw pól, które należy pobrać w żądaniu. SELECT zwraca listę oddzielonych przecinkami pól zasobów, pól segmentu i danych, które zwracają wartości w odpowiedzi. Klauzula SELECT jest wymagana w zapytaniu.

Zapoznaj się z przykładowym zapytaniem przedstawiającym wybór atrybutów dla 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 zasobów

    • campaign.id
    • campaign.name
  • Pola zasobów

    • bidding_strategy.id
    • bidding_strategy.name
  • Pola segmentów

    • segments.device
    • segments.date
  • Wskaźniki

    • metrics.impressions
    • metrics.clicks

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

  • pola zapytań, których nie można wybrać; Te pola będą miały atrybut metadanych Selectable oznaczony jako false.
  • Wybranie atrybutów pól powtarzanych. Te pola będą miały atrybut metadanych isRepeated oznaczony jako true.
  • Wybór pól, które są niedostępne dla danego zasobu w klauzuli FROM. Atrybuty niektórych zasobów nie mogą być wybrane razem. Dodatkowo w klauzuli FROM dostępny będzie tylko podzbiór wszystkich wskaźników i segmentów.
  • Wybranie segmentów lub danych, które są ze sobą niezgodne. Więcej informacji na ten temat znajdziesz w sekcji na temat segmentacji.

Informacje dotyczące powyższych warunków można znaleźć 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 pola, których można użyć we wszystkich klauzulach dla danego zapytania. W klauzuli FROM można określić tylko 1 zasób. Klauzula FROM jest wymagana w zapytaniu dotyczącym metod GoogleAdsService Search i SearchStream, ale nie powinna być określona podczas korzystania z GoogleAdsFieldService.

W klauzuli FROM dla danego zapytania może istnieć tylko 1 zasób, ale dostępne mogą być również pola z przypisanych zasobów. Zasoby te są domyślnie połączone z zasobem w klauzuli FROM, więc wystarczy, że dodasz ich atrybuty do klauzuli SELECT, aby zwrócić ich wartości. Nie wszystkie zasoby mają przypisane zasoby. W przykładzie poniżej możemy 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 poniższym przykładzie w odpowiedzi użyjemy ad_group.resource_name, mimo że zapytanie nie jest wyraźnie wybrane:

SELECT ad_group.id
FROM ad_group

To samo dotyczy innych zasobów po wybraniu co najmniej jednego pola. Na przykład ciąg campaign.resource_name zawiera odpowiedź 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 dla żądania. Gdy używasz klauzuli WHERE, możesz określić co najmniej 1 warunek, aby rozdzielić je za pomocą AND. Każdy warunek powinien być zgodny ze wzorcem field_name Operator value. Klauzula WHERE jest opcjonalna w zapytaniu.

Ten przykład pokazuje, jak używać metody WHERE do zwracania danych z wybranego okresu:

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

Możesz filtrować dane, łącząc wiele warunków. Ten przykład zażą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ą być w klauzuli SELECT z następującymi segmentami dat określanymi jako główne segmenty dat. Wyjątki:

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

W tym zapytaniu zaznaczono segments.date. Ponieważ ten segment jest podstawowym segmentem dat, musisz podać skończony zakres dat złożony 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ą podane wyżej warunki, to: segment.data, segmenty.week, segmenty.miesiąc, segmenty.kwartalny i segmenty.rok. Jeśli wybierzesz którykolwiek z tych segmentów, w klauzuli WHERE musisz użyć co najmniej jednego z tych segmentów.

.

Podczas filtrowania rozróżniana jest wielkość liter operatora. Więcej informacji znajdziesz w sekcji Wielkość liter.

Pełną listę operatorów znajdziesz w języku gramatyczny.

ORDER BY

Klauzula ORDER BY określa kolejność zwracania wyników. Pozwala to uporządkować dane w kolejności rosnącej lub malejącej według nazwy pola. Każde zamówienie jest określane jako field_name, po którym następuje ASC lub DESC. Jeśli nie określono właściwości ASC ani DESC, domyślną kolejnością jest ASC. Klauzula ORDER BY jest opcjonalna w zapytaniu.

W wyniku tego zapytania zwracane kampanie są podzielone według liczby kliknięć: od najwyższej do najniższej:

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

W klauzuli ORDER BY możesz podać wiele pól, rozdzielając je przecinkami. Kolejność wyświetlania będzie taka sama jak w zapytaniu. Na przykład w tym zapytaniu wybierającym dane grupy reklam, zostaną one posortowane w kolejności rosnącej według nazwy kampanii, następnie w kolejności malejącej według liczby wyświetleń i 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, które zostaną zwrócone. Jest to przydatne, jeśli interesuje Cię tylko podsumowanie.

LIMIT pozwala 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 parametrów metadanych dla żądania. Te parametry mogą wpływać na rodzaj zwracanych wierszy.

Obecnie obsługiwane są te parametry meta:

uwzględnij wersje robocze

Aby umożliwić zwracanie wersji roboczych encji, ustaw include_drafts na true. 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 uniemożliwić zwracanie nazwy zasobu każdego typu zasobu w odpowiedzi, jeśli nie zostanie to wyraźnie określone w klauzuli SELECT. Domyślna wartość to false.

Przykłady omit_unselected_resource_names
SELECT
  campaign.name,
  customer.id
FROM campaign
Returned resources:
campaign.resource_name
customer.resource_name

omit_unselected_resource_names przyjmuje domyślnie wartość false, dlatego wszystkie pola resource_name są zwracane.
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_nameWłaściwość
jest określona jako true, a campaign.resource_name jest wymagana w klauzuli SELECT.

Dodatkowe reguły dotyczące języka

Oprócz przykładów w poszczególnych klauzulach można użyć następujących zachowań w Google Ads:

  • Nie jest wymagane, aby główne pole zasobu znajdowało się w klauzuli SELECT zapytania. Możesz na przykład użyć tylko jednego głównego pola zasobu, aby filtrować dane:

    SELECT campaign.id
    FROM ad_group
    WHERE ad_group.status = PAUSED
    
  • Dla danego zasobu można wybrać wyłącznie wskaźniki. Inne zapytania z tego zasobu nie są wymagane:

    SELECT
      metrics.impressions,
      metrics.clicks,
      metrics.costMicros
    FROM campaign
    
  • Pola podziału na segmenty można wybrać bez towarzyszących pól zasobu lub wskaźników:

    SELECT segments.device FROM campaign
    
  • Pole resource_name (np. campaign.resource_name) może służyć do filtrowania lub zamawiania danych:

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