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

Przeczytaj poniższe sekcje, aby dowiedzieć się, jak tworzyć raporty wyszukiwania w interfejsie Search Ads 360 Reporting API.

Usługa wyszukiwania

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

SearchAds360Service to ujednolicona usługa pobierania i raportowania obiektów, która udostępnia 2 metody wyszukiwania: SearchStream i Search. Wyszukiwania są przekazywane w ciągu zapytania zapisanym 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ądkuj obiekty na podstawie 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 campaign.id, campaign.name i metrics.clicks, interfejs API zwraca wartość SearchAds360Row zawierającą obiekt kampanii z ustawionymi polami id i name oraz obiekt metrics z zestawem pól clicks.

Metody wyszukiwania

SearchStream

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

  • Pobieranie pakietów danych rozpoczyna się natychmiast, a cały wynik jest zapisywany w buforze danych.
  • Kod może zacząć odczytywać dane zbuforowane bez konieczności czekania na zakończenie całego strumienia.
Search

Wysyła wiele podzielonych na strony żądań pobrania całego raportu.

SearchStream zwykle zapewnia większą wydajność, ponieważ eliminuje konieczność przesyłania żądań do poszczególnych stron przez sieć w obie strony. Zalecamy użycie SearchStream w przypadku wszystkich raportów,które mają więcej niż 10 000 wierszy. Różnice w skuteczności między metodami w przypadku mniejszych raportów (poniżej 10 000 wierszy) są takie same.

Używana metoda nie wpływa na limity interfejsu API: pojedyncze zapytanie czy raport jest liczone jako jedna operacja niezależnie od tego, czy wyniki są stronowane, czy przesyłane strumieniowo.

Przykładowe zapytanie

To przykładowe zapytanie zwraca dane o skuteczności konta z ostatnich 30 dni według kampanii, podzielone 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 znaków customer_id i query do interfejsu SearchAds360Service.SearchStream lub SearchAds360Service.Search.

Żądanie składa się z protokołu POST HTTP 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 dotyczącego funkcji 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 wypełnianych na podstawie pól żądanych w klauzuli SELECT zapytania. Atrybuty, które nie są uwzględnione w klauzuli SELECT, nie są wypełniane w obiektach w odpowiedzi.

Na przykład podane niżej zapytanie wypełnia każdy obiekt SearchAds360Row tylko właściwościami campaign.id, campaign.name i campaign.status. Inne atrybuty, takie jak campaign.engine_id czy campaign.bidding_strategy_type, są pomijane.

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

Dokumentacja źródłowa

Sekcja Dokumentacja zawiera wszystkie informacje potrzebne do prawidłowego korzystania z poszczególnych artefaktów. Każdy zasób ma 1 stronę, na przykład ad_group i campaign. Na stronach segments i metrics znajdziesz wszystkie dostępne pola segmentów i danych.

Niektóre zasoby, segmenty i wskaźniki są niezgodne i nie mogą być używane razem, a inne są w pełni zgodne i uzupełniają się nawzajem. Każda strona zasobów zawiera m.in. te informacje (jeśli są dostępne i odpowiednie):

Przypisane zasoby

W przypadku niektórych zasobów możesz wybrać opcję pośredniego złączenia powiązanych zasobów, 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, gdy używasz w zapytaniu ad_group w klauzuli FROM.

W sekcji Przypisane zasoby znajdziesz listę dostępnych zasobów. Nie wszystkie zasoby mają przypisane zasoby.

Kolumna pól zasobów

Wszystkie pola zasobu są uwzględnione w kolumnie Pola zasobu. Każde pole zasobu zawiera linki do dodatkowych informacji na temat pola, w tym do jego opisu, kategorii, typu danych, adresu URL typu oraz ustawienia z możliwością filtrowania, wyboru, sortowania i powtarzania.

Kolumna Segmenty

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

Kolumna Segmenty zawiera listę pól segments, których możesz używać w tej samej klauzuli SELECT, co pola zasobu. Każde pole zawiera linki do szczegółowych informacji o polu, w tym do jego opisu, kategorii, typu danych, typu danych oraz ustawienia z możliwością filtrowania, wyboru, sortowania i powtarzania. Jeśli używasz zasobu w klauzuli FROM, za pomocą menu Tak/Nie możesz odfiltrować segmenty, które są niedostępne.

Kolumna danych

Nie wszystkie pola wskaźników można wybrać dla danego zasobu.

Kolumna Wskaźniki zawiera listę pól metrics, których możesz używać w tej samej klauzuli SELECT co pola zasobu. Każde pole zawiera linki do szczegółowych informacji o polu, w tym do jego opisu, kategorii, typu danych, typu danych oraz ustawienia z możliwością filtrowania, wyboru, sortowania i powtarzania. Jeśli używasz zasobu w klauzuli FROM, za pomocą menu Tak/Nie odfiltruj niedostępne wskaźniki.

Podział zasobów na segmenty

Niektóre zasoby mają pola zasobów do podziału na segmenty, które możesz wybrać, gdy zasób znajduje się w klauzuli FROM. Jeśli na przykład wybierzesz pole zasobu campaign, takie jak campaign.name, podczas korzystania z campaign_budget w klauzuli FROM automatycznie zwrócimy wartość campaign.resource_name i będziesz ją posegmentować, ponieważ campaign jest zasobem do podziału na segmenty campaign_budget.

Sekcja Zasoby do podziału na segmenty zawiera listę dostępnych zasobów służących do podziału na segmenty. Nie wszystkie zasoby mają zasoby umożliwiające segmentację.

Do wyboru w przypadku

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

Strona segments zawiera rozwinięcie Do wyboru w przypadku każdego pola segments, które zawiera listę wszystkich zgodnych pól zasobów, pól metrics i innych pól segments, które można uwzględnić w klauzuli SELECT.

Podział na segmenty

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

Na przykład zapytanie segments.device w poniższym zapytaniu spowoduje wygenerowanie raportu z wierszem reprezentującym 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 jak ten ciąg JSON:

{
  "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"
      }
    },
    ...
  ]
}

Listę dostępnych pól segmentów, których możesz użyć, znajdziesz segments.

Wiele segmentów

W klauzuli SELECT zapytania możesz określić wiele segmentów. Odpowiedź zawiera po 1 obiekcie SearchAds360Row na każdą kombinację instancji zasobu głównego określonego w klauzuli FROM i wartość każdego wybranego pola segment.

To zapytanie zwróci na przykład po 1 wierszu na każdą kombinację właściwoś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 podzielone na segmenty według poszczególnych wystąpień głównego zasobu, ale nie według wartości poszczególnych wybranych pól.

Poniższe przykładowe zapytanie daje 1 wiersz na kampanię, a nie 1 wiersz na różną wartość w polu campaign.status.

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

Pośrednicza segmentacja

Każdy raport jest wstępnie podzielony na segmenty według zasobu określonego w klauzuli FROM. Wskaźniki są podzielone na segmenty według pola resource_name tego zasobu

To przykładowe zapytanie automatycznie zwraca właściwość ad_group.resource_name i niejawnie wykorzystuje ją do podziału danych na segmenty na poziomie ad_group.

SELECT metrics.impressions
FROM ad_group

Zwrócony ciąg JSON wygląda podobnie do tego:

{
  "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 okres, w klauzuli WHERE możesz używać podstawowych segmentów dat.

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

Podstawowe pola segmentów dat są wyjątkiem od ogólnej reguły, zgodnie z którym w klauzuli WHERE nie można używać pola segmentów, chyba że dodasz też to pole w klauzuli SELECT. Więcej informacji znajdziesz w sekcji Niedozwolone filtrowanie.

Podstawowe reguły segmentu dat:

  • W klauzuli WHERE możesz użyć podstawowego pola daty, nie dodając go w klauzuli SELECT. Jeśli chcesz, możesz to zrobić w obu klauzulach.

    To przykładowe zapytanie zwraca clicks rodzajów danych według nazwy kampanii w wybranym zakresie dat. Zwróć uwagę, że klauzula SELECT nie obejmuje elementu segments.date.

    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ędnione jest podstawowe pole daty, w klauzuli WHERE musisz określić skończoną 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 posegmentowane według miesiąca i obejmują 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

Daty i zakresy dat możesz określić w formacie 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ą przedziału czasu (segments.week, segments.month, segments.quarter), możesz użyć operatora = z pierwszym dniem przedziału czasu, np.:

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

Wstępnie zdefiniowane daty

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

Wstępnie zdefiniowane daty
TODAY Tylko dzisiaj.
YESTERDAY Tylko wczoraj.
LAST_7_DAYS Ostatnie 7 dni (bez bieżącego dnia).
LAST_BUSINESS_WEEK Poprzedni 5-dniowy tydzień roboczy (od poniedziałku do piątku)
THIS_MONTH Wszystkie dni w bieżącym miesiącu.
LAST_MONTH Wszystkie dni w poprzednim miesiącu.
LAST_14_DAYS Poprzednie 14 dni (z wyłączeniem dzisiaj).
LAST_30_DAYS Ostatnie 30 dni (nie licząc dnia dzisiejszego).
THIS_WEEK_SUN_TODAY Okres od poprzedniej niedzieli do dnia bieżącego.
THIS_WEEK_MON_TODAY Okres między poprzednim poniedziałkiem a dniem bieżącym.
LAST_WEEK_SUN_SAT 7-dniowy okres od poprzedniej niedzieli.
LAST_WEEK_MON_SUN 7-dniowy okres od poprzedniego poniedziałku.

Przykład:

WHERE segments.date DURING LAST_30_DAYS

Zero danych

Podczas wykonywania zapytania możesz napotkać dla niektórych elementów wskaźniki z wartością 0. Więcej informacji o obsłudze w zapytaniach danych zerowych

UNKNOWN typów wyliczeniowych

Jeśli zasób jest zwracany z typem danych wyliczenia UNKNOWN, oznacza to, że ten typ nie jest w pełni obsługiwany przez wersję interfejsu API. Te zasoby mogły zostać utworzone za pomocą innych interfejsów. Przykład: nowa kampania lub reklama pojawiają się w interfejsie Search Ads 360, ale nie są jeszcze obsługiwane w wersji interfejsu API, której dotyczy Twoje zapytanie.

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

  • Zasób typu UNKNOWN może być obsługiwany później, ale może pozostawać bez ograniczeń czasowych UNKNOWN.
  • W każdej chwili mogą pojawić się nowe obiekty typu UNKNOWN. Obiekty te są zgodne wstecznie, ponieważ wartość wyliczenia jest już dostępna. Wraz z tą zmianą wprowadzamy zasoby, które są dostępne, aby zapewnić Ci dokładny wgląd w Twoje konto. Zasób UNKNOWN może się pojawić w wyniku nowej aktywności na Twoim koncie w innych interfejsach lub gdy nie jest już oficjalnie obsługiwany.
  • Zasoby UNKNOWN mogą mieć dołączone szczegółowe wskaźniki, do których możesz wysyłać zapytania.
  • UNKNOWN zasobów jest zwykle w pełni widocznych w interfejsie Search Ads 360.