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

Z poniższych sekcji dowiesz się, jak tworzyć raporty wyszukiwania w Search Ads 360 Reporting API.

Usługa wyszukiwania

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

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

• pobierać określone atrybuty obiektów;
• pobierać dane o skuteczności obiektów na podstawie zakresu dat;
• porządkować obiekty na podstawie ich atrybutów;
• filtrować wyniki za pomocą warunków określających, które obiekty mają być zwracane;
• ograniczać liczbę zwracanych obiektów.

Obie metody wyszukiwania zwracają wszystkie wiersze pasujące do zapytania. Jeśli na przykład pobierzesz campaign.id, campaign.name i metrics.clicks, interfejs API zwróci SearchAds360Rowzawierający obiekt kampanii z ustawionymi polami id i name oraz obiekt metrics z ustawionym polem clicks.

Metody wyszukiwania

SearchStream

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

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

Search

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

SearchStream zwykle zapewnia lepszą skuteczność, ponieważ eliminuje czas potrzebny na wysyłanie żądań do poszczególnych stron. W przypadku wszystkich raportów zawierających więcej niż 10 tys. wierszy zalecamy używanie SearchStream. W przypadku mniejszych raportów (poniżej 10 tys. wierszy) nie ma znaczącej różnicy w skuteczności między tymi metodami.

Używana metoda nie ma wpływu na limity i limity interfejsu API : pojedyncze zapytanie lub raport jest liczony jako 1 operacja niezależnie od tego, czy wyniki są podzielone na strony, 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 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ć customer_id i ciąg query do interfejsu SearchAds360Service.SearchStream lub SearchAds360Service.Search.

Żądanie składa się z 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 do searchStream zawarty 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 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 żądanych w klauzuli SELECT zapytania. Atrybuty nieuwzględnione w klauzuli SELECT nie są wypełniane w obiektach w odpowiedzi.

Na przykład poniższe zapytanie wypełnia każdy obiekt SearchAds360Row tylko atrybutami 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 źródłowa zawiera wszystkie informacje, których potrzebujesz, aby prawidłowo korzystać z każdego artefaktu. Każdy zasób ma swoją stronę, np. ad_group i campaign. Na stronach segments i metrics znajdziesz listę wszystkich dostępnych pól segmentów i danych.

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

Zasoby z atrybutami

W przypadku niektórych zasobów możesz mieć możliwość niejawnego łączenia powiązanych zasobów, wybierając ich pola razem z polami zasobu w klauzuli FROM. Na przykład zasób campaign jest zasobem z atrybutami zasobu ad_group. Oznacza to, że gdy używasz ad_group w klauzuli FROM, możesz uwzględnić w zapytaniu pola takie jak campaign.id i campaign.bidding_strategy_type.

Sekcja Zasoby z atrybutami zawiera listę dostępnych zasobów z atrybutami. Nie wszystkie zasoby mają zasoby z atrybutami.

Kolumna „Pola zasobu”

Wszystkie pola zasobu są uwzględnione w kolumnie Pola zasobu. Każde pole zasobu zawiera link do szczegółowych informacji o tym polu, w tym jego opisu, kategorii, typu danych, adresu URL typu oraz ustawień dotyczących filtrowania, wybierania, sortowania i powtarzania.

Kolumna „Segmenty”

Nie wszystkie pola segmentów można wybrać w przypadku danego zasobu.

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 link do szczegółowych informacji o tym polu, w tym jego opisu, kategorii, typu danych, adresu URL typu oraz ustawień dotyczących filtrowania, wybierania, sortowania i powtarzania. Jeśli używasz zasobu w klauzuli FROM, możesz użyć menu Tak/Nie , aby odfiltrować niedostępne segmenty.

Kolumna „Dane”

Nie wszystkie pola danych można wybrać w przypadku danego zasobu.

Kolumna Dane zawiera listę pól metrics, których możesz używać w tej samej klauzuli SELECT co pola zasobu. Każde pole zawiera link do szczegółowych informacji o tym polu, w tym jego opisu, kategorii, typu danych, adresu URL typu oraz ustawień dotyczących filtrowania, wybierania, sortowania i powtarzania. Jeśli używasz zasobu w klauzuli FROM, użyj menu Tak/Nie , aby odfiltrować niedostępne dane.

Segmentowanie zasobów

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, takie jak campaign.name, gdy używasz campaign_budget w klauzuli FROM, campaign.resource_name zostanie automatycznie zwrócony i podzielony na segmenty, ponieważ campaign jest zasobem segmentującym campaign_budget.

Sekcja Zasoby segmentujące zawiera listę dostępnych zasobów segmentujących. Nie wszystkie zasoby mają zasoby segmentujące.

Można wybrać za pomocą

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

Strona segments zawiera rozwijaną sekcję Można wybrać za pomocą dla każdego pola segments, która zawiera listę wszystkich zgodnych 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 SELECTzapytania.

Na przykład segments.device w poniższym zapytaniu spowoduje utworzenie raportu z wierszem dla impressions każdego urządzenia w przypadku zasobu określonego w FROM klauzuli.

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

Wyniki zwracane 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żywać, znajdziesz w sekcji segments.

Wiele segmentów

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

Na przykład to zapytanie zwróci 1 wiersz dla każdej kombinacji campaign, segments.ad_network_type i segments.date.

SELECT
  segments.ad_network_type
  segments.date
FROM campaign

Pamiętaj, że wyniki są niejawnie dzielone na segmenty według każdej instancji głównego zasobu, ale nie według wartości poszczególnych wybranych pól.

Poniższe przykładowe zapytanie spowoduje utworzenie 1 wiersza na kampanię, a nie 1 wiersza na odrębną wartość pola campaign.status.

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

Niejawny podział na segmenty

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 ad_group.resource_name i niejawnie używa go do dzielenia 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

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

Te pola segmentów są nazywane podstawowymi 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 zasady, że w klauzuli WHERE nie można używać pola segmentów, chyba że uwzględnisz je też w klauzuli SELECT. Więcej informacji znajdziesz w artykule Zabronione filtrowanie.

Reguły podstawowych segmentów dat:

• W klauzuli WHERE możesz użyć pola podstawowej 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 danym zakresie dat. Pamiętaj, że segments.date nie jest uwzględniony 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 pole podstawowej daty, w klauzuli WHERE musisz określić skończoną datę lub zakres dat. Pola określone w klauzulach SELECT i WHERE nie muszą się zgadzać.

  To przykładowe zapytanie zwraca dane clicks według nazwy kampanii, podzielone na segmenty według miesiąca we wszystkich dniach 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 (segments.week, segments.month, segments.quarter), możesz użyć operatora = z pierwszym dniem okresu, na przykład:

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

Wstępnie zdefiniowane daty

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

Przykład:

WHERE segments.date DURING LAST_30_DAYS

Dane równe zero

Podczas wykonywania zapytania możesz napotkać dane o wartości zero w przypadku niektórych elementów. Dowiedz się, jak obsługiwać dane równe zero w zapytaniach.

Typy wyliczeń UNKNOWN

Jeśli zasób jest zwracany z typem danych wyliczenia 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 w interfejsie Search Ads 360 wprowadzono nową kampanię lub reklamę, ale nie jest ona jeszcze obsługiwana w wersji interfejsu API, z której korzystasz.

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

• Zasób z typem UNKNOWN może być obsługiwany w przyszłości, ale może też pozostać UNKNOWN na stałe.

• Nowe obiekty z typem UNKNOWN mogą pojawiać się w dowolnym momencie. Te obiekty są zgodne wstecznie, ponieważ wartość wyliczenia jest już dostępna. Wprowadzamy zasoby z tą zmianą, gdy są dostępne, aby zapewnić Ci dokładny wgląd w konto. Zasób UNKNOWN może się pojawić z powodu nowej aktywności na koncie za pomocą innych interfejsów lub dlatego, że zasób nie jest już formalnie obsługiwany.

• Do zasobów UNKNOWN mogą być dołączone szczegółowe dane, o które możesz wysyłać zapytania.

• Zasoby UNKNOWN są zwykle w pełni widoczne w interfejsie Search Ads 360.