Tworzenie raportów wyszukiwania w interfejsie Search Ads 360 Reporting API

W poniższych sekcjach dowiesz się, jak tworzyć raporty wyszukiwania w interfejsie Search Ads 360 Reporting API.

Usługa wyszukiwania

Interfejs Search Ads 360 Reporting API zapewnia specjalną usługę wyszukiwania i raportowania.

SearchAds360Service to zintegrowana usługa wyszukiwania i raportowania obiektów, która udostępnia 2 metody wyszukiwania: SearchStream i Search. Wyszukiwania są przekazywane w postaci ciągu zapytania w języku zapytań Search Ads 360. Możesz zdefiniować zapytania, aby:

  • Pobieranie określonych atrybutów obiektów.
  • Pobieranie danych o wydajności obiektów na podstawie zakresu dat.
  • porządkować obiekty według ich atrybutów;
  • Filtrowanie wyników za pomocą warunków określających, które obiekty mają zostać zwrócone
  • Ogranicz liczbę zwracanych obiektów.

Obie metody wyszukiwania zwracają wszystkie wiersze pasujące do zapytania. Gdy np. pobierasz dane campaign.id, campaign.name i metrics.clicks, interfejs API zwraca obiekt SearchAds360Row zawierający obiekt kampanii z ustawionymi polami id i name oraz obiekt metrics z ustawionym polem clicks.

Metody wyszukiwania

SearchStream

Wysyła 1 żądanie i inicjuje trwałe połączenie z interfejsem Search Ads 360 Reporting API niezależnie od rozmiaru raportu.

  • Pakiety danych zaczynają się pobierać natychmiast, a cały wynik jest przechowywany w buforze danych.
  • Twój kod może zacząć odczytywać zbuforowane dane bez konieczności czekania na zakończenie całego strumienia.
Search

Wysyła wiele żądań podziału na strony, aby pobrać cały raport.

SearchStreamzazwyczaj zapewnia lepszą wydajność, ponieważ eliminuje czas potrzebny na przesyłanie i odbieranie danych przez sieć w przypadku poszczególnych stron. Zalecamy używanie formatu SearchStream w przypadku wszystkich raportów zawierających ponad 10 tys. wierszy. Nie ma istotnych różnic w skuteczności między metodami w przypadku mniejszych raportów (poniżej 10 000 wierszy).

Metoda, której używasz, nie ma wpływu na kwoty i limity interfejsu API: pojedyncze zapytanie lub raport jest liczone jako 1 operacja niezależnie od tego, czy wyniki są pobierane w postaci stron czy strumieniowo.

Przykładowe zapytanie

To przykładowe zapytanie zwraca dane o skuteczności konta z ostatnich 30 dni według kampanii podzielone na segmenty według urządzenia:

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Poproś

Aby wysłać żądanie, musisz przekazać ciąg customer_id i query do interfejsu SearchAds360Service.SearchStream lub SearchAds360Service.Search.

Żądanie składa się z żądania HTTP POST do serwera Search Ads 360 Reporting API pod jednym z tych adresów URL:

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream
 
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search

Oto pełny przykład definicji raportu searchStream zawartej w żądaniu HTTP POST:

POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1
Host: searchads360.googleapis.com
User-Agent: curl
Content-Type: application/json
Accept: application/json
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]

Parameters:
{
  "query" : "SELECT campaign.name, campaign.status, segments.device,
                    metrics.impressions, metrics.clicks, metrics.ctr,
                    metrics.average_cpc, metrics.cost_micros
            FROM campaign
            WHERE segments.date DURING LAST_30_DAYS"
}

Przetwarzanie odpowiedzi

SearchAds360Service zwraca listę obiektów SearchAds360Row.

Każdy element SearchAds360Row reprezentuje obiekt zwrócony przez zapytanie. Każdy obiekt składa się z zestawu atrybutów, które są wypełniane na podstawie pól określonych w klauzuli SELECT w zapytaniu. Atrybuty, których nie ma w klauzuli SELECT, nie są wypełniane w obiektach w odpowiedzi.

Na przykład poniższe zapytanie wypełnia każdy obiekt SearchAds360Row tylko wartościami campaign.id, campaign.name i campaign.status. Inne atrybuty, takie jak campaign.engine_id lub campaign.bidding_strategy_type, są pomijane.

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign

Dokumentacja źródłowa

Sekcja Informacje zawiera wszystkie informacje potrzebne do prawidłowego korzystania z każdego artefaktu. Dla każdego zasobu jest jedna strona, np. ad_group i campaign. Na stronach segments i metrics znajduje się lista wszystkich dostępnych pól segmentów i danych.

Niektóre zasoby, segmenty i dane są ze sobą niezgodne i nie można ich używać razem, a inne są w pełni zgodne i wzajemnie się uzupełniają. Każda strona zasobu zawiera te informacje (jeśli są dostępne i odpowiednie):

Przypisane zasoby

W przypadku niektórych zasobów możesz mieć możliwość dołączania zasobów powiązanych w sposób domyślny, wybierając ich pola razem z polami zasobu w klauzuli FROM. Na przykład zasób campaign jest przypisanym zasobem ad_group. Oznacza to, że możesz uwzględniać w zapytaniu pola takie jak campaign.id i campaign.bidding_strategy_type, jeśli używasz w klauzuli FROM pola ad_group.

W sekcji Zasoby przypisane wymieniono dostępne zasoby przypisane. Nie wszystkie zasoby mają przypisane zasoby.

Kolumna Pola zasobów

Wszystkie pola zasobu są widoczne w kolumnie Pola zasobów. Każde pole zasobu zawiera link do dodatkowych informacji o polu, w tym opisu, kategorii, typu danych, adresu URL typu oraz ustawień filtrowania, wybierania, sortowania i powtarzania.

Kolumna Segmenty

Nie wszystkie pola segmentów można wybrać z danym zasobem.

W kolumnie Segmenty wymienione są pola segments, których możesz używać w tej samej klauzuli SELECT co pola zasobu. Każde pole zawiera szczegółowe informacje na jego temat, w tym jego opis, kategorię, typ danych, typ danych, a także ustawienia z możliwością filtrowania, wyboru, sortowania i powtarzania. Jeśli używasz zasobu w klauzuli FROM, możesz użyć menu Tak/Nie, aby odfiltrować segmenty, które są niedostępne.

Kolumna danych

Nie wszystkie pola wskaźników można wybrać z danym zasobem.

W kolumnie Dane wymienione są pola metrics, których możesz używać w tej samej klauzuli SELECT co pola zasobu. Każde pole zawiera link do pełnych informacji o polu, w tym opisu, kategorii, typu danych, adresu URL typu oraz ustawień filtrowania, wybierania, sortowania i powtarzania. Jeśli używasz zasobu w klauzuli FROM, użyj menu Tak/Nie, aby odfiltrować dane, które są niedostępne.

Podział zasobów na segmenty

Niektóre zasoby mają pola zasobów segmentujących, które możesz wybrać, gdy zasób znajduje się w klauzuli FROM. Jeśli na przykład wybierzesz pole zasobu campaign, np. campaign.name, a w klauzuli FROM użyjesz pola campaign_budget, pole campaign.resource_name będzie automatycznie zwracane i segmentowane, ponieważ campaign jest zasobem segmentującym campaign_budget.

W sekcji Zasoby do segmentacji znajdziesz listę dostępnych zasobów do segmentacji. Nie wszystkie zasoby mają zasoby segmentujące.

Dostępne w ramach

Niektóre pola segments są niezgodne z innymi zasobami, segmentami i danymi.

Na stronie segments znajduje się pole wyboru, które można rozwinąć w przypadku każdego pola segments, aby wyświetlić listę wszystkich kompatybilnych pól zasobów, pól metrics i innych pól segments, które możesz uwzględnić w klauzuli SELECT.

Podział na segmenty

Możesz podzielić wyniki wyszukiwania na segmenty, dodając pole segments.FIELD_NAME do klauzuli SELECT zapytania.

Na przykład segments.device w zapytaniu poniżej powoduje, że raport zawiera wiersz z wartością impressions każdego urządzenia dla zasobu określonego w klauzuli FROM.

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions
FROM campaign

Wyniki zwrócone przez SearchAds360Service.SearchStream wyglądają mniej więcej tak:

{
  "results":[
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"10922"
      },
      "segments":{
        "device":"MOBILE"
      }
    },
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"28297"
      },
      "segments":{
        "device":"DESKTOP"
      }
    },
    ...
  ]
}

Na stronie segments znajdziesz listę dostępnych pól segmentów, których możesz używać.

Wiele segmentów

W klauzuli SELECT zapytania możesz określić wiele segmentów. Odpowiedź zawiera 1 obiekt SearchAds360Row dla każdej kombinacji wystąpienia zasobu głównego określonego w klauzuli FROM oraz wartości każdego wybranego pola segment.

Na przykład to zapytanie zwróci po 1 wierszu na każdą kombinację wartości campaign, segments.ad_network_type i segments.date.

SELECT
  segments.ad_network_type
  segments.date
FROM campaign

Pamiętaj, że wyniki są domyślnie dzielone na segmenty według każdego wystąpienia głównego zasobu, ale nie według wartości poszczególnych wybranych pól.

Podany poniżej przykładowy wynik zapytania zawiera 1 wiersz na kampanię, a nie 1 wiersz na każdą niepowtarzalną wartość pola campaign.status.

SELECT
  campaign.status,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

Podział na segmenty w ramach kampanii

Każdy raport jest początkowo dzielony na segmenty według zasobu określonego w klauzuli FROM. Dane są dzielone na segmenty według pola resource_name tego zasobu

To przykładowe zapytanie automatycznie zwraca wartość ad_group.resource_name i używa jej do podziału danych na segmenty na poziomie ad_group.

SELECT metrics.impressions
FROM ad_group

Zwrócony ciąg JSON wygląda mniej więcej tak:

{
  "results":[
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/2222222222"
      },
      "metrics":{
        "impressions":"237"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/33333333333"
      },
      "metrics":{
        "impressions":"15"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/44444444444"
      },
      "metrics":{
        "impressions":"0"
      }
    }
  ]
}

Podstawowe segmenty dat

Aby określić datę lub przedział czasu, możesz użyć podstawowych segmentów dat w klauzuli WHERE.

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

To przykładowe zapytanie zwraca dane clicks kampanii z ostatnich 30 dni.

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

Pola podstawowych segmentów dat są wyjątkiem od ogólnej reguły, że nie możesz używać pola segmentów w nawiasach klamrowych WHERE, chyba że uwzględnisz to pole również w nawiasach klamrowych SELECT. Więcej informacji znajdziesz w sekcji Zabronione filtrowanie.

Podstawowe reguły segmentu dat:

  • W klauzuli WHERE możesz użyć podstawowego pola daty bez uwzględniania go w klauzuli SELECT. Jeśli chcesz, możesz też uwzględnić to pole w obu klauzulach.

    To przykładowe zapytanie zwraca dane clicks według nazwy kampanii w zakresie dat. Pamiętaj, że segments.date nie jest uwzględniona w klauzuli SELECT.

    SELECT
    campaign.name,
    metrics.clicks
FROM campaign
WHERE segments.date > '2022-02-01'
  AND segments.date < '2022-03-01'

  • Jeśli w klauzuli SELECT uwzględnisz podstawowe pole daty, w klauzuli WHERE musisz podać konkretną datę lub zakres dat. Pola określone w klauzulach SELECT i WHERE nie muszą być takie same.

    To przykładowe zapytanie zwraca dane clicks według nazwy kampanii pogrupowane według miesiąca i obejmujące wszystkie dni w zakresie dat.

    SELECT
  campaign.name,
  metrics.clicks,
  segments.month
FROM campaign
WHERE segments.date > '2022-02-01'
  AND segments.date < '2022-03-01'

daty w formacie ISO 8601,

Do określania dat i zakresów dat możesz używać formatu YYYY-MM-DD (ISO 8601), na przykład:

WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'

WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'

W przypadku podstawowych segmentów dat, które wymagają okresu czasu (segments.week, segments.month, segments.quarter), możesz użyć operatora = z pierwszym dniem okresu czasu, na przykład:

WHERE segments.month = '2022-06-01'

Wstępnie zdefiniowane daty

Możesz też użyć tych wstępnie zdefiniowanych dat i zakresów dat:

Wstępnie zdefiniowane daty
TODAY Tylko dzisiaj.
YESTERDAY Tylko wczoraj.
LAST_7_DAYS W ciągu poprzednich 7 dni (bez bieżącego dnia).
LAST_BUSINESS_WEEK Poprzednie 5 dni roboczych (od poniedziałku do piątku).
THIS_MONTH Wszystkie dni bieżącego miesiąca.
LAST_MONTH Wszystkie dni poprzedniego miesiąca.
LAST_14_DAYS Ostatnie 14 dni (z wyłączeniem dnia dzisiejszego).
LAST_30_DAYS Ostatnie 30 dni z wyłączeniem dnia dzisiejszego.
THIS_WEEK_SUN_TODAY Okres między poprzednią niedzielą a dniem bieżącym.
THIS_WEEK_MON_TODAY Okres między poprzednim poniedziałkiem a dniem bieżącym.
LAST_WEEK_SUN_SAT 7-dniowy okres rozpoczynający się w poprzednią niedzielę.
LAST_WEEK_MON_SUN 7-dniowy okres od poprzedniego poniedziałku.

Przykład:

WHERE segments.date DURING LAST_30_DAYS

Dane o wartości 0

Podczas wykonywania zapytania w przypadku niektórych elementów możesz natrafić na wskaźniki z wartością 0. Dowiedz się, jak obsługiwać dane o wartości 0 w zapytaniach

Typy enum UNKNOWN

Jeśli zasób jest zwracany z typem danych UNKNOWN enum, oznacza to, że typ nie jest w pełni obsługiwany w tej wersji interfejsu API. Zasoby te mogły zostać utworzone przez inne interfejsy. Na przykład nowa kampania lub reklama została wprowadzona w interfejsie Search Ads 360, ale nie jest jeszcze obsługiwana w wersji interfejsu API, z której wysyłasz zapytanie.

Nadal możesz wybierać dane, gdy zasób ma typ UNKNOWN, ale musisz pamiętać o tych kwestiach:

  • Zasób o typie UNKNOWN może zostać obsługiwany w przyszłości, ale może też pozostać w stanie UNKNOWN w nieskończoność.
  • Nowe obiekty typu UNKNOWN mogą pojawić się w dowolnym momencie. Te obiekty są zgodne wstecznie, ponieważ wartość typu enum jest już dostępna. Wraz z wprowadzeniem tej zmiany udostępniamy odpowiednie materiały, aby zapewnić Ci dokładny wgląd w stan Twojego konta. Zasób UNKNOWN może się pojawić z powodu nowej aktywności na Twoim koncie w innych interfejsach lub dlatego, że zasób przestał być oficjalnie obsługiwany.
  • Zasoby UNKNOWN mogą mieć szczegółowe dane, do których możesz się odwoływać.
  • Zasoby usługi UNKNOWN są zwykle w pełni widoczne w interfejsie Search Ads 360.