Struktura zapytań i klauzule

Zapytanie składa się z kilku klauzul: SELECT, FROM, WHERE, ORDER BY, LIMIT i PARAMETERS.

Klauzule używają nazw pól, nazw zasobów, operatorów, warunków i kolejności, które łączą się w jedno żądanie zapytania.

W uproszczeniu, aby utworzyć zapytanie, wykonaj te czynności:

• Określ zasób, z którego chcesz pobrać dane.
• Dodaj pola i dane, aby zdefiniować dane, które chcesz zwrócić.
• Dodaj segmenty, aby pogrupować wyniki.
• Dodaj zasoby z atrybutami, aby niejawnie połączyć powiązane dane zasobów.
• Filtruj, sortuj i ograniczaj wyniki.

Klauzula SELECT

Klauzula SELECT:

• Jest wymaganą klauzulą w zapytaniu.
• Określa zestaw pól do pobrania w żądaniu.
• Przyjmuje rozdzieloną przecinkami listę pól zasobów, kolumn niestandardowych, niestandardowych zmiennych Floodlight, pól segmentów i danych oraz zwraca wartości w odpowiedzi.

Ten przykładowy kod pokazuje, jak wybrać atrybuty zasobu campaign:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Różne typy pól

W tym samym żądaniu możesz poprosić o różne typy pól.

Poniższy przykładowy kod pokazuje pojedyncze zapytanie z kombinacją:

• Pola zasobów: campaign.id, campaign.name, bidding_strategy.id i bidding_strategy.name.

• Pola segmentów: segments.device i segments.date.

• Pola danych: metrics.impressions i metrics.clicks.

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

Więcej informacji o segmentowaniu raportów wyszukiwania znajdziesz w artykule Segmentacja.

Pole zasobu głównego

Zwykle pole zasobu głównego umieszcza się w klauzuli SELECT, ale jest to opcjonalne (nie wymagane).

Ten przykładowy kod używa pola zasobu głównego (ad_group.status) tylko do filtrowania wyników.

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

Niestandardowe zmienne Floodlight

W klauzuli SELECT możesz uwzględnić niestandardowe zmienne Floodlight, używając ich identyfikatorów.

W tym przykładzie zapytanie zawiera zmienną niestandardową o identyfikatorze 123454321 dla zasobu kampanii.

SELECT
  conversion_custom_metrics.id[123454321]
FROM campaign

SELECT
  conversion_custom_dimensions.id[123454321]
FROM campaign

Kolumny niestandardowe

W klauzuli SELECT możesz uwzględnić kolumny niestandardowe, używając ich identyfikatorów.

W tym przykładzie zapytanie zawiera kolumnę niestandardową o identyfikatorze 12345678 dla zasobu kampanii.

SELECT
  custom_columns.id[12345678]
FROM campaign

Dowiedz się jak uzyskać identyfikatory kolumn niestandardowych.

Pola danych

Możesz wybrać pola danych dla danego zasobu bez uwzględniania w klauzuli SELECT żadnych innych pól z tego zasobu.

Ten przykładowy kod wybiera dane impressions i clicks dla zasobu campaign.

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

Listę pól danych, których możesz używać w zapytaniach, znajdziesz w sekcji metrics.

Pola segmentów

Możesz wybrać pola segmentów bez określania w klauzuli SELECT towarzyszących pól zasobów ani danych.

Ten przykładowy kod segmentuje wyniki według urządzenia.

SELECT segments.device
FROM campaign

Listę pól segmentów, których możesz używać w zapytaniach, znajdziesz w sekcji segments.

Pola zabronione

W klauzuli SELECT nie możesz używać tych pól:

• Pola niepodlegające wyborowi, czyli pola z atrybutem metadanych Selectable oznaczonym jako false.

• Pola powtarzane, czyli pola z atrybutem metadanych Repeated oznaczonym jako true.

• Pola, które nie są dostępne w przypadku danego zasobu w klauzuli FROM. Nie można wybrać razem atrybutów niektórych zasobów. Niektóre zasoby udostępniają tylko podzbiór wszystkich danych i segmentów.

• Niezgodne segmenty lub dane. Więcej informacji znajdziesz w artykule Segmentacja.

Szczegółowe informacje o tym, gdzie znaleźć te informacje w przypadku poszczególnych zasobów, znajdziesz w dokumentacji.

Klauzula FROM

Klauzula FROM:

• Jest wymaganą klauzulą w przypadku zapytań do SearchAds360Service (metody Search i SearchStream).

• **Nie** należy jej uwzględniać w przypadku zapytań do SearchAds360FieldService.

• Określa główny zasób zwracany przez zapytanie.

• Może określać tylko 1 zasób.

• Określa pola, których możesz używać we wszystkich innych klauzulach zapytania.

Uwaga: w sekcji Odniesienie na stronie każdego zasobu znajduje się pole wyboru Tak/Nie, które filtruje pola zasobów, pola segmentów i pola danych, których nie można używać, gdy w klauzuli FROM określono zasób.

Zasoby z atrybutami

Jeśli dostępne są zasoby z atrybutami, są one niejawnie łączone z zasobem określonym w klauzuli FROM. Aby zwrócić ich wartości, wystarczy dodać ich atrybuty do klauzuli SELECT.

Ten przykładowy kod zwraca zarówno identyfikator grupy reklam, jak i identyfikator kampanii, ponieważ campaign jest zasobem z atrybutami zasobu ad_group.

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Uwaga: nie wszystkie zasoby mają zasoby z atrybutami. W sekcji Odniesienie znajdziesz szczegółowe informacje o zasobach z atrybutami dostępnych w przypadku każdego zasobu.

Pole resource_name

Pole resource_name zasobu głównego w klauzuli FROM jest zawsze zwracane.

W tym przykładowym kodzie pole ad_group.resource_name zostanie uwzględnione w odpowiedzi, mimo że nie zostało wyraźnie wybrane w zapytaniu:

SELECT ad_group.id
FROM ad_group

Pole resource_name zasobu z atrybutami jest zwracane, gdy wybrano co najmniej 1 pole.

W tym przykładowym kodzie pole campaign.resource_name zostanie uwzględnione w odpowiedzi, ponieważ wybrano pole campaign.id:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Uwaga: jeśli zasób w klauzuli FROM zawiera inny zasób jako segment, wybranie dowolnych atrybutów tego zasobu działa jak segment.

Klauzula WHERE

Klauzula WHERE:

• Jest opcjonalną klauzulą w zapytaniu.

• Określa warunki filtrowania i segmentowania danych na potrzeby żądania. Warunki mają postać: FIELD_NAME OPERATOR VALUE (rozdzielone spacjami).

• Może zawierać wiele warunków rozdzielonych separatorem AND.

Ten przykładowy kod pokazuje, jak użyć klauzuli WHERE, aby zwrócić dane impressions za dany okres:

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

Więcej informacji o segmentowaniu raportów wyszukiwania znajdziesz w artykule Segmentacja.

Więcej informacji o określaniu zakresów dat w zapytaniach znajdziesz w artykule Zakresy dat.

Filtrowanie według pola resource_name

Do filtrowania i sortowania danych możesz używać pola resource_name.

Ten przykładowy kod używa pola campaign.resource_name do filtrowania wyników według danej kampanii:

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

Wiele warunków

Aby filtrować dane, możesz połączyć kilka warunków.

Ten przykładowy kod żąda liczby danych clicks we wszystkich kampaniach z danymi impressions 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

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

Więcej informacji o segmentowaniu raportów znajdziesz w artykule Segmentacja.

Rozróżnianie wielkości liter

Podczas filtrowania według wartości ciągów znaków domyślne rozróżnianie wielkości liter w przypadku każdego operatora odgrywa ważną rolę w prawidłowym filtrowaniu wyników.

Tabela poniżej pokazuje domyślne rozróżnianie wielkości liter w przypadku każdego operatora.

Domyślne rozróżnianie wielkości liter
=/!=	Case sensitive
IN/NOT IN	Case sensitive
LIKE/NOT LIKE	Case insensitive
CONTAINS (...)	Case sensitive
REGEXP_MATCH/NOT REGEXP_MATCH	Case sensitive

Aby zmienić domyślne rozróżnianie wielkości liter w przypadku operatorów REGEXP_MATCH i NOT REGEXP_MATCH na nierozróżnianie wielkości liter, możesz użyć modyfikatora (?i), na przykład:

SELECT campaign.id
FROM campaign
WHERE campaign.name REGEXP_MATCH "(?i).*test.*"

Pełną listę operatorów, których możesz używać do filtrowania danych, znajdziesz w artykule Odniesienie do gramatyki zapytań.

Podstawowe segmenty dat

Te pola segmentów są nazywane podstawowymi segmentami dat: segments.date, segments.week, segments.month, segments.quarter, i segments.year.

W klauzuli WHERE możesz używać podstawowych segmentów dat, aby określić datę lub okres.

Ten przykładowy kod określa DURING LAST_30_DAYS dla pola segments.date w klauzuli WHERE:

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

Szczegółowe informacje o używaniu podstawowych segmentów dat znajdziesz w artykule Segmentacja > Podstawowe segmenty dat.

Zabronione filtrowanie

Filtrowanie jest niedozwolone:

• W przypadku nie wybranych pól segmentów, z wyjątkiem podstawowych segmentów dat.

• W przypadku pól dowolnego typu wiadomości, z wyjątkiem typów prostych (np. Int64Value, StringValue itp.).

• W przypadku atrybutów pól powtarzanych dowolnego typu wiadomości, z wyjątkiem typów prostych (np. Int64Value, StringValue itp.).

Klauzula ORDER BY

Klauzula ORDER BY:

• Jest opcjonalną klauzulą w zapytaniu.
• Określa kolejność, w jakiej mają być zwracane wyniki. Kolejność ma postać: FIELD_NAME ORDERING_OPTION (rozdzielone spacją).
• Umożliwia 2 opcje: ASC (rosnąco) lub DESC (malejąco). Domyślnie jest to kolejność rosnąca.

Ten przykładowy kod sortuje kampanie według liczby kliknięć w kolejności malejącej (od największej do najmniejszej):

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

Wiele kolejności

W klauzuli ORDER BY możesz określić wiele pól, używając listy rozdzielonej przecinkami. Wyniki będą sortowane w takiej samej kolejności, w jakiej określisz je w zapytaniu.

Ten przykładowy kod wybiera dane grupy reklam i sortuje wyniki 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

Łączenie sortowania i limitu

Aby zawęzić wyniki, możesz użyć klauzuli ORDER BY w połączeniu z klauzulą LIMIT.

Ten przykładowy kod zwraca 5 kampanii z największą liczbą wyświetleń w ciągu ostatnich 30 dni:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5

Zabronione sortowanie

Sortowanie jest niedozwolone:

• Według atrybutów nie wybranych zasobów.
• Według nie wybranych danych.
• Według nie wybranych segmentów.
• W przypadku tych typów pól:
  • MESSAGE
  • Pola powtarzane
  • Atrybuty pól powtarzanych.

Klauzula LIMIT

Klauzula LIMIT:

• Jest opcjonalną klauzulą w zapytaniu.
• Pozwala ograniczyć liczbę wyników zwracanych przez zapytanie.

Ta klauzula jest przydatna np. wtedy, gdy interesuje Cię tylko próbka lub podsumowanie wyników.

Ten przykładowy kod ogranicza łączną liczbę wyników do 50:

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

Klauzula PARAMETERS

Klauzula PARAMETERS pozwala określić metaparametry żądania.

Uwzględnij wersje robocze

Parametr include_drafts określa, czy w wynikach mają być uwzględniane encje w wersji roboczej. Domyślnie jest ustawiony na false. Aby uwzględnić encje w wersji roboczej, ustaw go na true.

Ten przykładowy kod zwraca zarówno kampanie w wersji roboczej, jak i zwykłe kampanie:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Pomijanie nie wybranych pól resource_name

Parametr omit_unselected_resource_names pozwala wykluczyć resource_name pole wszystkich zasobów, które nie zostały wyraźnie określone w SELECT klauzuli. Domyślnie jest ustawiony na false. Jeśli ustawisz ten parametr na true, zalecamy, aby w klauzuli SELECT wyraźnie zażądać nazwy zasobu głównego i wszystkich zasobów z atrybutami.

Ten przykładowy kod nie zwraca pola campaign.resource_name ani pola customer.resource_name, ponieważ nie są one uwzględnione w klauzuli SELECT:

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

Ten przykładowy kod zwraca pole campaign.resource_name, ponieważ jest ono wyraźnie określone w klauzuli SELECT:

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

Zmiana waluty używanej w danych

Parametr metrics_currency pozwala określić walutę, która ma być używana podczas obliczania danych uwzględnionych w klauzuli SELECT. Domyślnie używana jest waluta konta określonego przez customer_id. Jeśli ustawisz ten parametr, musisz użyć 3-znakowego kodu waluty w standardzie ISO 4217. Na przykład: PLN, EUR.

Ten przykładowy kod zwraca dane cost_micros w walucie konta określonego przez customer_id.

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"

Ten przykładowy kod zwraca dane cost_micros w peso chilijskim (CLP).

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
PARAMETERS metrics_currency = "CLP"

Włączanie rozszerzenia MCC

Gdy parametr enable_mcc_expansion jest ustawiony na true, możesz uwzględniać dane, pola i segmenty ze wszystkich kont powiązanych z customer_id w przypadku zasobu w klauzuli FROM. Odpowiedź będzie używać waluty customer_id, chyba że zostanie ona wyraźnie określona w parametrze metrics_currency.

Uwaga: Parametr enable_mcc_expansion jest zgodny tylko z bidding_strategy. Z czasem interfejs API będzie obejmował dodatkowe zasoby.

Ten przykładowy kod zwraca bidding_strategy.name, bidding_strategy.type i metrics.cost_micros ze wszystkich kont w hierarchii kont powiązanych z customer_id, ponieważ parametr enable_mcc_expansion jest ustawiony na true.

SELECT
  bidding_strategy.name,
  bidding_strategy.type,
  metrics.cost_micros
FROM bidding_strategy
WHERE segments.date DURING LAST_14_DAYS
PARAMETERS enable_mcc_expansion = true

Więcej informacji

• Gramatyka zapytań