Pobieram obiekty

Cel: dowiedz się, jak pobierać obiekty i statystyki skuteczności za pomocą GoogleAdsService. Informacje o pojęciach związanych z raportowaniem znajdziesz w przewodnikach po raportowaniu.

GoogleAdsService to ujednolicona usługa pobierania obiektów i raportowania w interfejsie Google Ads API. Usługa ma metody, które:

• pobierać określone atrybuty obiektów;
• Pobieranie wskaźników skuteczności obiektów na podstawie zakresu dat.
• porządkować obiekty na podstawie ich atrybutów;
• Użyj warunków, aby wskazać, które obiekty mają zostać zwrócone w odpowiedzi.
• Ogranicz liczbę zwracanych obiektów.

GoogleAdsService może zwracać wyniki na 2 sposoby:

• GoogleAdsService.SearchStream zwraca wszystkie wiersze w jednej odpowiedzi strumieniowej, co jest bardziej wydajne w przypadku dużych zbiorów wyników (ponad 10 000 wierszy). Zalecamy to, jeśli aplikacja pobiera pełne zbiory wyników lub przetwarza wiersze jako strumień.
• GoogleAdsService.Search dzieli duże odpowiedzi na łatwe do zarządzania strony wyników. Jest to przydatne, jeśli aplikacja interaktywna wyświetla po jednej stronie wyników naraz.

Dowiedz się więcej o stronicowaniu i strumieniowaniu.

Poproś

GoogleAdsService.SearchStream oczekuje wartości SearchGoogleAdsStreamRequest, a GoogleAdsService.Search oczekuje wartości SearchGoogleAdsRequest. Oba typy żądań obejmują:

• customer_id
• query w języku zapytań Google Ads, które wskazuje, do jakiego zasobu ma zostać wysłane zapytanie, jakie atrybuty, segmenty i dane mają zostać pobrane oraz jakie warunki mają zostać użyte do ograniczenia zwracanych obiektów.

W zależności od metody żądanie obsługuje też pola specyficzne dla metody:

• SearchGoogleAdsStreamRequest (tylko SearchStream):
  • Opcjonalny parametr summary_row_setting, który umożliwia żądanie wiersza podsumowania zawierającego zagregowane dane.
• SearchGoogleAdsRequest (tylko Search):
  • Opcjonalny parametr page_token do pobierania następnej partii wyników podczas korzystania ze stronicowania (parametr page_size jest ustawiony na stałą wartość 10 000 wierszy; ustawienie parametru page_size w żądaniu powoduje błąd RequestError.PAGE_SIZE_NOT_SUPPORTED).
  • Opcjonalny komunikat search_settings do skonfigurowania return_summary_row, return_total_results_count i omit_results
  • Opcjonalna wartość logiczna validate_only do sprawdzania poprawności zapytania bez jego wykonywania

Więcej informacji o języku Google Ads Query Language znajdziesz w przewodniku po tym języku.

Przetwarzanie odpowiedzi

Metoda GoogleAdsService zwraca listę obiektów GoogleAdsRow (w ramach strumieniowych zbiorów SearchGoogleAdsStreamResponse lub w podzielonym na strony obiekcie SearchGoogleAdsResponse).

Każdy obiekt GoogleAdsRow reprezentuje obiekt zwracany przez zapytanie i składa się ze zbioru atrybutów, które są wypełniane na podstawie pól żądanych w klauzuli SELECT. Atrybuty, które nie są uwzględnione w klauzuli SELECT, nie są wypełniane w obiektach GoogleAdsRow w odpowiedzi.

Na przykład, chociaż ad_group_criterion ma atrybut status, pole status atrybutu ad_group_criterion wiersza nie jest wypełniane w odpowiedzi na zapytanie, w którym klauzula SELECT nie zawiera ad_group_criterion.status. Podobnie atrybut campaign wiersza nie jest wypełniany, jeśli klauzula SELECT nie zawiera żadnych pól z zasobu campaign.

Każdy obiekt GoogleAdsRow może mieć inne atrybuty i dane niż inny wiersz w tym samym zbiorze wyników, dlatego wiersze należy traktować jako obiekty, a nie stałe wiersze tabeli.

Typy wyliczeniowe UNKNOWN i UNSPECIFIED

Zasoby zwracane z wartością typu wyliczeniowego UNKNOWN nie są w pełni obsługiwane w tej wersji interfejsu API, natomiast wartość UNSPECIFIED wskazuje, że pole typu wyliczeniowego nie zostało ustawione lub nie zostało uwzględnione w klauzuli SELECT. Zasoby z wartością typu wyliczeniowego UNKNOWN mogły zostać utworzone za pomocą innych interfejsów, np. interfejsu Google Ads. Możesz wybrać dane, gdy zasób ma typ UNKNOWN, ale nie możesz go zmienić za pomocą interfejsu API. Przykładem może być kampania lub typ reklamy dostępny w interfejsie, który nie jest obsługiwany w wersji interfejsu API, do której wysyłasz zapytanie.

Oto kwestie, które warto mieć na uwadze:

• Zasób typu UNKNOWN może być obsługiwany w późniejszej wersji interfejsu API lub pozostać UNKNOWN na czas nieokreślony.
• Nowe obiekty typu UNKNOWN mogą pojawić się w każdej chwili. Te obiekty są zgodne wstecznie, ponieważ wartość typu wyliczeniowego UNKNOWN jest obecna w każdym typie wyliczeniowym w interfejsie API. Zasoby są zwracane z parametrem UNKNOWN, dzięki czemu masz dokładny wgląd w ogólne wskaźniki skuteczności konta.
• Zasoby UNKNOWN mogą mieć dołączone szczegółowe dane, które można wyszukiwać.
• Zasoby UNKNOWN są zwykle w pełni widoczne w interfejsie Google Ads.
• Zasobów UNKNOWN nie można zwykle modyfikować za pomocą interfejsu API.

Podział na segmenty

Odpowiedź zawiera po jednym obiekcie GoogleAdsRow dla każdej kombinacji tych elementów:

• Instancja głównego zasobu określonego w klauzuli FROM
• Wartość każdego wybranego pola segments

Na przykład odpowiedź na zapytanie, które wybiera FROM campaign i zawiera segments.ad_network_type oraz segments.date w klauzuli SELECT, zawiera po 1 wierszu dla każdej kombinacji tych elementów:

• campaign
• segments.ad_network_type
• segments.date

Wyniki są niejawnie dzielone na segmenty według poszczególnych instancji głównego zasobu, a nie według wartości wybranych pól. Na przykład

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

zwraca po jednym wierszu na kampanię, a nie po jednym wierszu na każdą odrębną wartość pola campaign.status.

Uwaga: dostępność segmentów może się różnić w zależności od wersji interfejsu API. Na przykład segments.click_type w AdGroupAsset, CampaignAsset i CustomerAsset oraz segments.ad_sub_network_type w campaign_budget można wybrać tylko w wersji 23 i starszych, segments.ad_network_type w PerformanceMaxPlacementView jest dostępny w wersji 24 i nowszych, segments.ad_sub_format_type i segments.loyalty_membership są dostępne w wersji 25 i nowszych, a segments.search_lift_keyword_bundle i segments.search_property są dostępne w wersji 26 i nowszych. Użyj GoogleAdsFieldService, aby sprawdzić zgodność segmentów z wersją interfejsu API, do której wysyłasz zapytanie.