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 znaków zapytania w języku zapytań Search Ads 360. Możesz zdefiniować zapytania, aby:

  • Pobieranie określonych atrybutów obiektów.
  • Pobieranie danych o skutecznoś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ć buforowane dane bez oczekiwania na zakończenie całego strumienia.
Search

wysyła wiele żądań po stronie, aby pobrać cały raport.

SearchStreamzazwyczaj zapewnia lepszą wydajność, ponieważ eliminuje czas potrzebny na przetwarzanie danych w sieci w obie strony, który jest wymagany do wczytania poszczególnych stron. Zalecamy używanie formatu SearchStream w przypadku wszystkich raportów zawierających ponad 10 tys. wierszy. W przypadku mniejszych raportów (mniej niż 10 tys. wierszy) nie ma znaczącej różnicy w wydajności między metodami.

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 podzielonych 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 żą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 zapytanie poniżej 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 zasobu 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 zasobu

W kolumnie Pola zasobu znajdują się wszystkie pola zasobu. 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 segmentu są dostępne w przypadku danego zasobu.

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 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, możesz użyć menu Tak/Nie, aby odfiltrować segmenty, które są niedostępne.

Kolumna danych

Nie wszystkie pola danych są dostępne w przypadku danego zasobu.

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

Wyniki wyszukiwania możesz podzielić na segmenty, dodając pole segments.FIELD_NAME do klauzuli SELECT w zapytaniu.

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 zwracane przez funkcję 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 podać większą liczbę 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 dla każdej kombinacji atrybutów 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.

Poniższe przykładowe zapytanie zwraca 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 sposób domyślny

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ć w klauzuli WHERE podstawowych segmentów daty.

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 okresie wybranym przez Ciebie. 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 podzielone według miesiąca za 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,

Aby określić daty i zakresy dat, możesz użyć 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 z poprzednich 7 dni (bez bieżącego dnia).
LAST_BUSINESS_WEEK Poprzedni 5-dniowy tydzień roboczy (od poniedziałku do piątku).
THIS_MONTH Wszystkie dni bieżącego miesiąca.
LAST_MONTH Wszystkie dni w poprzednim miesiącu.
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 rozpoczynający się w poprzedni poniedziałek.

Przykład:

WHERE segments.date DURING LAST_30_DAYS

Dane o wartości 0

Podczas wykonywania zapytania możesz zobaczyć dane o wartości 0 w przypadku niektórych jednostek. 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, oznacza to, że ten typ nie jest w pełni obsługiwany w tej wersji interfejsu API. Te zasoby mogły zostać utworzone za pomocą innych interfejsów. 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 każdej chwili. 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 za pomocą innych interfejsów lub dlatego, że zasób nie jest już oficjalnie obsługiwany.
  • Zasoby UNKNOWN mogą mieć szczegółowe dane, do których możesz się odwoływać.
  • UNKNOWN są zwykle w pełni widoczne w interfejsie Search Ads 360.