Struktura zapytania

Zapytania dotyczące pól zasobów, segmentów i danych mogą być wysyłane do GoogleAdsService Wyszukiwarka lub Strumień wyszukiwania . Aby utworzyć zapytanie w języku zapytań Google Ads, musisz użyć do tego celu gramatyki języka, Zapytanie składa się z klauzule:

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

Klauzule używają nazw pól, nazw zasobów, operatorów, warunków oraz orderings, które ułatwią Ci wybranie właściwych danych. Po połączeniu w jeden żądanie można wysłać za pomocą interfejsu Google Ads API.

Ważne: GoogleAdsFieldService udostępnia katalog klientów Google Ads Query Language zawierający metadane dotyczące wszystkich zasobów pola, pola segmentów i dane, a także ich relacje oraz dostępność w poszczególnych klauzulach, jak opisano poniżej. Aby dowiedzieć się więcej, zapoznaj się z dokumentacją dotyczącą GoogleAdsField.

Klauzule

Wideo: zgodność pól GAQL

WYBIERZ

Klauzula SELECT określa zbiór pól do pobrania w żądaniu. SELECT stosuje rozdzielaną przecinkami listę pól zasobów, pól segmentów, i wskaźniki, które zwracają wartości w odpowiedzi. Klauzula SELECT ma postać wymagany w zapytaniu.

W przykładowym zapytaniu poniżej pokazujemy, jak wybierać atrybuty dla danego atrybutu zasób:

SELECT
  campaign.id,
  campaign.name
FROM campaign

W jednym żądaniu możesz zażądać różnych typów 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 segmentu

  • segments.device
  • segments.date

• Dane

  • metrics.impressions
  • metrics.clicks

Niektóre pola mogą być niedozwolone w klauzuli SELECT z tych powodów: ograniczenia:

• Zapytanie o pola, których nie można wybrać. Te pola będą miały swoje Atrybut metadanych Selectable został oznaczony jako false.
• Wybór atrybutów pól powtarzanych. Te pola będą miały swoje Atrybut metadanych isRepeated został oznaczony jako true.
• Wybieram pola, które są niedostępne w przypadku danego zasobu w FROM. . Atrybutów niektórych zasobów nie można wybrać razem, ponieważ wszystkie dane i segmenty będą dostępne dla zasobu w klauzulę FROM.
• Wybranie segmentów lub danych, które są ze sobą niezgodne. Dla: więcej informacji na ten temat znajdziesz w sekcją podziału na segmenty.

Informacje dotyczące powyższych warunków można znaleźć w naszych dokumentach referencyjnych lub od 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 w przypadku pozostałych dla danego zapytania. W funkcji klauzulę FROM. Klauzula FROM jest wymagana w zapytaniu skierowanym do GoogleAdsService Wyszukiwarka lub Strumień wyszukiwania metod, jednak nie należy go określać, jeśli używasz parametru GoogleAdsFieldService

Chociaż w klauzuli FROM dla danego zapytania może istnieć tylko 1 zasób, pola z Przypisanych zasobów. Te zasoby są domyślnie połączone z zasobem w klauzuli FROM, więc wystarczy dodać ich atrybuty do klauzuli SELECT, aby zwrócić ich wartości. Nie wszystkie Zasoby mają przypisane zasoby. W przykładzie poniżej można 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 pole ad_group.resource_name zostanie uwzględnione w parametrze mimo że nie została wyraźnie wybrana w zapytaniu:

SELECT ad_group.id
FROM ad_group

To samo dotyczy innych zasobów, gdy wybierzesz co najmniej 1 pole. Na przykład: campaign.resource_name znajdzie się w odpowiedzi dla atrybutu to zapytanie:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Ważne: jeśli zasób w klauzuli FROM zawiera inny zasób jako segment, a następnie wybrane atrybuty tego zasobu będą działać jako segment.

WHERE

Klauzula WHERE określa warunki, które należy stosować podczas filtrowania danych: użytkownika. Jeśli używasz klauzuli WHERE, możesz określić co najmniej 1 warunek za pomocą AND. Każdy warunek powinien być zgodny ze wzorem field_name Operator value Klauzula WHERE jest opcjonalna w zapytaniu.

Poniżej znajdziesz przykład użycia funkcji WHERE do zwrócenia danych z określonego momentu okres:

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

Możesz łączyć kilka warunków, aby filtrować dane. W tym przykładzie poproś o liczbę kliknięć dla wszystkich kampanii z wyświetleniami na urządzeniach mobilnych w 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ą znajdować się w klauzuli SELECT, a z parametrem następujące segmenty dat, nazywane podstawowymi segmentami dat, są wyjątki:

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

W poniższym zapytaniu zaznaczono pole segments.date. Ten segment jest podstawowym segmentem dat, więc wymaga podania daty skończonej zakres złożony z podstawowych segmentów dat w klauzuli WHERE, która ma zostać podana.

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

Wszystkie segmenty spełniające ten warunek to: segments.date, segments.week, segmenty.miesiąc, segmenty.kwartał i segmenty.rok. Jeśli któryś z tych segmentów jest wybrany, w klauzuli WHERE musi być użyty co najmniej 1 z nich.

Ważne: separatora AND można używać tylko między warunkami operatora (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE"), a nie w warunku pojedynczego operatora (WHERE segments.device != "DESKTOP" AND "MOBILE"),

Podczas filtrowania warto pamiętać, że operator uwzględnia wielkość liter. umysł. Więcej informacji znajdziesz w sekcji Wielkość liter.

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

ORDER BY

Klauzula ORDER BY określa kolejność, w jakiej wyniki mają zostać wyświetlone. . Pozwala to uporządkować dane w kolejności rosnącej lub malejącej. na podstawie nazwy pola. Każde zamówienie jest określane za pomocą znaku field_name, po którym następuje znak ASC lub DESC. Jeśli nie podasz ani ASC, ani DESC, kolejność będzie domyślnie ustawiona do ASC. Klauzula ORDER BY jest opcjonalna w zapytaniu.

Następujące zapytanie porządkuje zwrócone kampanie według liczby kliknięć pochodzących z od najwyższej do najniższej:

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

W klauzuli ORDER BY możesz określić większą liczbę pól, rozdzielając je przecinkami z listy. Kolejność wyświetlania reklam będzie wykonywana w takiej samej kolejności jak w zapytaniu. Na przykład w tym zapytaniu wybranie danych grupy reklam spowoduje sortowanie wyników w kolejności rosnącej według nazwy kampanii, a następnie w kolejności malejącej według liczby wyświetleń, a następnie 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 do zwrócenia. Przydaje się to, jeśli interesuje Cię tylko podsumowanie.

Na przykład LIMIT można użyć do ograniczenia łącznej liczby wyników dla zapytania to zapytanie:

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

Ważne: LIMIT umożliwia skracanie wyników. Korzystanie z pola page_size z GoogleAdsService.Search na obsługi długich list wyników.

PARAMETRY

Klauzula PARAMETERS umożliwia określenie metaparametrów dla żądania. Te parametry mogą wpływać na rodzaj zwracanych wierszy.

Obecnie obsługiwane są te metaparametry:

include_drafts

Aby umożliwić zwracanie wersji roboczych elementów, ustaw include_drafts na true. Domyślna wartość to false.

Na przykład to zapytanie pobiera robocze wersje kampanii razem ze zwykłymi kampanie:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

Ustaw omit_unselected_resource_names na true, aby zapobiec nazwie zasobu każdy typ zasobu w odpowiedzi, chyba że zostanie bezpośrednio zażądany w klauzuli SELECT. Domyślna wartość to false.

Uwaga: jeśli planujesz użyć zwróconego obiektu do aktualizacji lub usunięcia operacji, zalecamy ustawienie tej opcji na false, zasobów, które nie mają nazw zasobów, nie można używać w operacjach mutacji. Jeśli ustawisz tę opcję pod kątem true, upewnij się, że żądasz nazw zasobów w obu zasobu głównego i wszystkich zasobów atrybutów pobranych za pomocą zapytania.

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 ma domyślną wartość false, więc wszystkie pola resource_name.
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true	Returned resources:, Brak. Pole omit_unselected_resource_names jest określone jako true i campaign.resource_name oraz 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_name omit_unselected_resource_names jest określony jako true i campaign.resource_name prosili w ramach Klauzula SELECT.

Dodatkowe reguły dotyczące języka

Oprócz przykładów poszczególnych klauzul, język zapytań Google Ads ma te funkcje: zachowań, które można wykorzystać:

• Pole głównego zasobu nie musi znajdować się w elemencie SELECT klauzuli dla zapytania. Na przykład można używać tylko jednej lub kilku głównych pola zasobów do filtrowania danych:

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

• Wskaźniki można wybrać wyłącznie dla danego zasobu. brak innych pól z zasobu są wymagane w zapytaniu:

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

• Pola podziału na segmenty można wybierać bez towarzyszących pól zasobów lub dane:

  SELECT segments.device FROM campaign
  

• Pole resource_name (np. campaign.resource_name) można służy do filtrowania lub porządkowania danych:

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