Pobieram obiekty

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 danych o skuteczności obiektów na podstawie zakresu dat.
• Uporządkuj obiekty na podstawie ich atrybutów.
• Użyj warunków, aby wskazać, które obiekty mają być zwracane w odpowiedzi.
• Ogranicz liczbę zwracanych obiektów.

GoogleAdsService może zwracać wyniki na 2 sposoby:

• GoogleAdsService.SearchStreamzwraca wszystkie wiersze w jednej odpowiedzi strumieniowej, co jest bardziej wydajne w przypadku dużych (ponad 10 tys. wierszy) zbiorów wyników. Jest to zalecane, jeśli aplikacja pobiera pełne zbiory wyników lub przetwarza wiersze jako strumień.
• GoogleAdsService.Search dzieli długie odpowiedzi na mniejsze strony z wynikami. Jest to przydatne, jeśli aplikacja interaktywna wyświetla po jednej stronie wyników.

Dowiedz się więcej o stronicowaniu a strumieniowaniu.

Poproś

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

• customer_id
• Język zapytań Google Ads query, który wskazuje zasób, o który należy wysłać zapytanie, atrybuty, segmenty i dane do pobrania oraz warunki, które należy zastosować, aby ograniczyć liczbę 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 z stronicowania (page_size jest stałą wartością 10 000 wierszy; ustawienie page_size w żądaniu powoduje błąd RequestError.PAGE_SIZE_NOT_SUPPORTED).
  • Opcjonalna wiadomość search_settings do skonfigurowania return_summary_row, return_total_results_count i omit_results
  • Opcjonalna wartość logiczna validate_only, która umożliwia sprawdzenie poprawności zapytania bez jego wykonywania.

Więcej informacji o języku zapytań Google Ads znajdziesz w przewodniku po języku zapytań Google Ads.

Przetwarzanie odpowiedzi

Funkcja GoogleAdsService zwraca listę obiektów GoogleAdsRow (w strumieniowanych SearchGoogleAdsStreamResponse partiach lub w stronicowanych SearchGoogleAdsResponse).

Każdy element GoogleAdsRow reprezentuje obiekt zwrócony przez zapytanie i składa się z zestawu atrybutów, które są wypełniane na podstawie pól żądanych w klauzuli SELECT. Atrybuty nieuwzględnione w klauzuli SELECT nie są wypełniane w obiektach GoogleAdsRow w odpowiedzi.

Na przykład chociaż element ad_group_criterion ma atrybut status, pole status atrybutu ad_group_criterion w wierszu 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 GoogleAdsRow może mieć inne atrybuty i dane niż inny wiersz w tym samym zbiorze wyników, więc wiersze należy traktować jako obiekty, a nie stałe wiersze tabeli.

Typy wyliczeniowe UNKNOWN i UNSPECIFIED

Zasoby zwracane z wartością wyliczeniową UNKNOWN nie są w pełni obsługiwane w danej wersji interfejsu API, natomiast UNSPECIFIED oznacza, że pole wyliczeniowe nie zostało ustawione lub nie zostało uwzględnione w klauzuli SELECT. Zasoby z wartością wyliczeniową UNKNOWN mogły zostać utworzone w innych interfejsach, np. w interfejsie Google Ads. Wskaźniki możesz wybierać, gdy zasób ma typ UNKNOWN, ale nie możesz zmieniać zasobu za pomocą interfejsu API. Przykładem może być kampania lub typ reklamy dostępny w interfejsie, ale nieobsługiwany w wersji interfejsu API, z której korzystasz.

Oto kilka kwestii, o których warto pamiętać:

• Zasób typu UNKNOWN może być obsługiwany w późniejszej wersji interfejsu API lub pozostać UNKNOWN bezterminowo.
• Nowe obiekty typu UNKNOWN mogą pojawiać się w dowolnym momencie. Te obiekty są wstecznie zgodne, ponieważ wartość wyliczenia UNKNOWN występuje w każdym wyliczeniu w interfejsie API. Zasoby są zwracane z wartością UNKNOWN, dzięki czemu masz dokładny wgląd w ogólne dane o skuteczności konta.
• Do zasobów UNKNOWN można dołączyć szczegółowe rodzaje danych, które można wyszukiwać.
• UNKNOWN są zwykle w pełni widoczne w interfejsie Google Ads.
• Zasobów UNKNOWN nie można zwykle zmieniać za pomocą interfejsu API.

Podział na segmenty

Odpowiedź zawiera 1 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 ma w klauzuli SELECT warunki segments.ad_network_type i segments.date, zawiera wiersz dla każdej kombinacji tych elementów:

• campaign
• segments.ad_network_type
• segments.date

Wyniki są niejawnie segmentowane według każdej instancji głównego zasobu, a nie według wartości poszczególnych wybranych pól. Na przykład

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

daje w wyniku 1 wiersz na kampanię, a nie 1 wiersz na każdą odrębną wartość pola campaign.status.