Struktura interfejsu API

ondemand_video Film: omówienie usług i zasobów z warsztatów w 2019 r.

Z tego przewodnika dowiesz się, jakie są główne komponenty interfejsu Google Ads API. Interfejs Google Ads API składa się z zasobów i usług. Zasób reprezentuje element Google Ads, a usługi służą do pobierania i modyfikowania elementów Google Ads.

Hierarchia obiektów

Konto Google Ads można traktować jako hierarchię obiektów.

• Zasobem najwyższego poziomu na koncie jest klient.

• Każdy klient ma co najmniej 1 aktywną kampanię.

• Każda kampania zawiera co najmniej 1 grupę reklam, która służy do grupowania reklam w logiczne zbiory.

• Reklama w grupie reklam reprezentuje reklamę, którą wyświetlasz. Każda grupa reklam zawiera co najmniej 1 reklamę w grupie reklam, z wyjątkiem kampanii promujących aplikacje, które mogą mieć tylko 1 reklamę w grupie reklam.

Do grupy reklam lub kampanii możesz dołączyć co najmniej 1 element AdGroupCriterion lub CampaignCriterion. Reprezentują one kryteria określające, jak wyzwalane są reklamy.

Istnieje wiele typów kryteriów, takich jak słowa kluczowe, zakresy wiekowe i lokalizacje. Kryteria zdefiniowane na poziomie kampanii wpływają na wszystkie inne zasoby w kampanii. Możesz też określić budżety i daty dla całej kampanii.

Na koniec możesz dołączyć komponenty na poziomie konta, kampanii lub grupy reklam. Komponenty umożliwiają podawanie w reklamach dodatkowych informacji, takich jak numery telefonów, adresy lub promocje. Więcej informacji znajdziesz w artykule Przegląd komponentów.

Zasoby

Zasoby reprezentują elementy na koncie Google Ads. Campaign i AdGroup to 2 przykłady zasobów.

Identyfikatory obiektów

Każdy obiekt w Google Ads jest identyfikowany przez własny identyfikator. Niektóre z tych identyfikatorów są unikalne globalnie we wszystkich kontach Google Ads, a inne – tylko w ograniczonym zakresie.

Te reguły dotyczące identyfikatorów mogą być przydatne podczas projektowania pamięci lokalnej dla obiektów Google Ads.

Niektóre obiekty mogą być używane w przypadku wielu typów elementów. W takich przypadkach obiekt zawiera pole type, które opisuje jego zawartość. Na przykład, AdGroupAd może odnosić się do obiektu takiego jak reklama tekstowa, reklama hotelu lub reklama lokalna. Do tej wartości można uzyskać dostęp za pomocą pola AdGroupAd.ad.type, które zwraca wartość z wyliczenia AdType.

Nazwy zasobów

Każdy zasób jest jednoznacznie identyfikowany przez ciąg znaków resource_name, który łączy zasób i jego elementy nadrzędne w ścieżkę. Na przykład nazwy zasobów kampanii mają postać:

customers/customer_id/campaigns/campaign_id

W przypadku kampanii o identyfikatorze 987654 na koncie Google Ads o identyfikatorze klienta 1234567 nazwa resource_name będzie wyglądać tak:

customers/1234567/campaigns/987654

Usługi

Usługi umożliwiają pobieranie i modyfikowanie elementów Google Ads. Istnieją 3 rodzaje usług: modyfikacji, pobierania obiektów i statystyk oraz pobierania metadanych.

Modyfikowanie (zmienianie) obiektów

Te usługi modyfikują instancje powiązanego typu zasobu za pomocą żądania mutate. Udostępniają też żądanie get, które pobiera pojedynczą instancję zasobu. Może to być przydatne do sprawdzania struktury zasobu.

Przykłady usług:

• CustomerService do modyfikowania klientów.

• CampaignService do modyfikowania kampanii.

• AdGroupService do modyfikowania grup reklam.

Każde żądanie mutate musi zawierać odpowiednie obiekty operation. Na przykład metoda CampaignService.MutateCampaigns oczekuje co najmniej 1 instancji CampaignOperation. Szczegółowe omówienie operacji znajdziesz w artykule Zmienianie i sprawdzanie obiektów.

Równoczesne zmiany

Obiektu Google Ads nie można modyfikować równocześnie z więcej niż 1 źródła. Może to powodować błędy, jeśli wielu użytkowników aktualizuje ten sam obiekt za pomocą Twojej aplikacji lub jeśli zmieniasz obiekty Google Ads równolegle za pomocą wielu wątków. Obejmuje to aktualizowanie obiektu z wielu wątków w tej samej aplikacji lub z różnych aplikacji (np. z Twojej aplikacji i równoczesnej sesji w interfejsie Google Ads).

Interfejs API nie umożliwia blokowania obiektu przed aktualizacją. Jeśli 2 źródła próbują równocześnie zmienić obiekt, interfejs API zgłasza błąd DatabaseError.CONCURRENT_MODIFICATION_ERROR.

Zmiany asynchroniczne i synchroniczne

Metody zmiany interfejsu Google Ads API są synchroniczne. Wywołania interfejsu API zwracają odpowiedź dopiero po zmianie obiektów, co wymaga czekania na odpowiedź na każde żądanie. Chociaż to podejście jest stosunkowo proste w kodowaniu, może negatywnie wpływać na równoważenie obciążenia i marnować zasoby, jeśli procesy muszą czekać na zakończenie wywołań.

Alternatywnym podejściem jest asynchroniczne zmienianie obiektów za pomocą BatchJobService, które wykonuje pakiety operacji w wielu usługach bez czekania na ich zakończenie. Po przesłaniu zadania wsadowego serwery interfejsu Google Ads API wykonują operacje asynchronicznie, co pozwala procesom wykonywać inne operacje. Możesz okresowo sprawdzać stan zadania, aby dowiedzieć się, czy zostało ono ukończone.

Więcej informacji o przetwarzaniu asynchronicznym znajdziesz w przewodniku Przetwarzanie wsadowe.

Weryfikacja zmian

Większość żądań zmiany można zweryfikować bez wykonywania wywołania na rzeczywistych danych. Możesz przetestować żądanie pod kątem brakujących parametrów i nieprawidłowych wartości pól bez wykonywania operacji.

Aby użyć tej funkcji, ustaw opcjonalne pole logiczne validate_only żądania na true. Żądanie zostanie w pełni zweryfikowane tak, jakby miało zostać wykonane, ale ostateczne wykonanie zostanie pominięte. Jeśli nie zostaną znalezione żadne błędy, zostanie zwrócona pusta odpowiedź. Jeśli weryfikacja się nie powiedzie, komunikaty o błędach w odpowiedzi wskażą punkty, w których wystąpił błąd.

validate_only jest szczególnie przydatne do testowania reklam pod kątem typowych naruszeń zasad. Reklamy są automatycznie odrzucane, jeśli naruszają zasady, np. zawierają określone słowa, znaki interpunkcyjne, wielkie litery lub mają określoną długość. Jedna zła reklama może spowodować niepowodzenie całej partii. Testowanie nowej reklamy w żądaniu validate_only może ujawnić takie naruszenia. Aby zobaczyć, jak to działa, zapoznaj się z przykładem kodu dotyczącym obsługi błędów naruszenia zasad.

Pobieranie obiektów i statystyk skuteczności

GoogleAdsService to pojedyncza, ujednolicona usługa do pobierania obiektów i statystyk skuteczności.

Wszystkie Search i SearchStream żądania dotyczące GoogleAdsService wymagają zapytania, które określa zasób, do którego ma być kierowane zapytanie, atrybuty zasobu i statystyki skuteczności do pobrania, predykaty do filtrowania żądania oraz segmenty do dalszego podziału statystyk skuteczności. Więcej informacji o formacie zapytań, znajdziesz w przewodniku po języku zapytań Google Ads.

Pobieranie metadanych

GoogleAdsFieldService pobiera metadane o zasobach w interfejsie Google Ads API, takie jak dostępne atrybuty zasobu i jego typ danych.

Ta usługa zawiera informacje potrzebne do utworzenia zapytania do GoogleAdsService. Dla wygody informacje zwracane przez GoogleAdsFieldService są też dostępne w dokumentacji referencyjnej pól.