Struktura interfejsu API

W tym przewodniku przedstawiamy 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 pobierają elementy Google Ads i nimi zarządzają.

Hierarchia obiektów

Konto Google Ads można postrzegać 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 jedną grupę reklam, która służy do grupowania reklam w logiczne kolekcje.

• Reklama w grupie reklam to reklama, którą wyświetlasz w grupie reklam. Z wyjątkiem kampanii promujących aplikacje, które mogą mieć tylko jedną reklamę w grupie reklam, każda grupa reklam zawiera co najmniej jedną reklamę.

Kampanie Performance Max mają inną strukturę niż inne typy kampanii: zamiast grup reklam i reklam w grupach reklam kampania Performance Max zawiera grupy komponentów. Komponenty kreacji możesz połączyć z grupą plików za pomocą AssetGroupAsset, a sygnały dotyczące odbiorców lub tematów wyszukiwania możesz dołączyć za pomocą AssetGroupSignal.

Do grupy reklam lub kampanii możesz dołączyć co najmniej 1 zasób AdGroupCriterion lub CampaignCriterion. Są to kryteria, które określają, jak wywoływane są reklamy.

Istnieje wiele typów kryteriów, takich jak słowa kluczowe, przedziały wiekowe i lokalizacje. Kryteria zdefiniowane na poziomie kampanii mają wpływ na wszystkie inne zasoby w kampanii. Możesz też określić budżety oraz daty i godziny rozpoczęcia i zakończenia kampanii lub poszczególnych reklam, używając parametrów AdGroupAd.start_date_time i AdGroupAd.end_date_time.

Komponenty możesz dodawać na poziomie konta, kampanii, grupy reklam lub grupy plików. Komponenty umożliwiają dodawanie do reklam dodatkowych informacji, takich jak numery telefonów, adresy czy promocje. Zobacz Omówienie 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 za pomocą własnego identyfikatora. Niektóre z tych identyfikatorów są unikalne na wszystkich kontach Google Ads, a inne są unikalne tylko w ograniczonym zakresie.

Te reguły dotyczące identyfikatorów mogą być przydatne podczas projektowania lokalnego miejsca przechowywania 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 elastyczna reklama w wyszukiwarce, reklama hotelu lub reklama generująca popyt. Tę wartość można uzyskać w polu AdGroupAd.ad.type. Zwraca ona wartość w typie wyliczeniowym AdType. Pamiętaj, że zmienność może się różnić w zależności od wersji (np. VideoResponsiveAdInfo w Ad jest zmienny w wersji 24 i nowszych).

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 parametr resource_name będzie miał postać:

customers/1234567/campaigns/987654

Usługi

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

modyfikować (mutować) obiekty,

Usługi związane z konkretnymi zasobami modyfikują instancje powiązanego typu zasobu za pomocą żądania mutate. Możesz też używać metody GoogleAdsService.Mutate do wykonywania niepodzielnych mutacji w przypadku wielu typów zasobów w jednym żądaniu (np. do jednoczesnego tworzenia budżetu kampanii, kampanii i grupy reklam).

Przykłady usług związanych z zasobami:

• CustomerService do modyfikowania klientów.

• CampaignService do modyfikowania kampanii.

• AdGroupService, aby zmodyfikować grupy 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 Obiekty zmian.

Równoczesne mutacje

Obiekt Google Ads nie może być modyfikowany jednocześnie przez więcej niż jedno źródło. Może to powodować błędy, jeśli wielu użytkowników aktualizuje ten sam obiekt za pomocą Twojej aplikacji lub jeśli modyfikujesz obiekty Google Ads równolegle przy użyciu 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 interfejsu Google Ads).

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

Mutacje asynchroniczne i synchroniczne

Metody mutate interfejsu Google Ads API są synchroniczne. Wywołania interfejsu API zwracają odpowiedź dopiero po zmodyfikowaniu obiektów, co wymaga oczekiwania na odpowiedź na każde żądanie. Chociaż to podejście jest stosunkowo proste do zakodowania, może negatywnie wpłynąć na równoważenie obciążenia i marnować zasoby, jeśli procesy będą musiały czekać na zakończenie wywołań.

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

Więcej informacji o przetwarzaniu asynchronicznym znajdziesz w przewodniku po przetwarzaniu wsadowym.

Weryfikacja mutacji

Większość żądań modyfikacji 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 faktycznego wykonywania operacji.

Aby użyć tej funkcji, ustaw opcjonalne pole logiczne validate_only żądania na true. Żądanie jest w pełni sprawdzane, tak jakby miało zostać wykonane, ale ostateczne wykonanie jest pomijane. Jeśli nie zostaną znalezione żadne błędy, odpowiedź zostanie zwrócona bez wypełnionych wyników mutacji (results jest puste). Jeśli weryfikacja się nie powiedzie, żądanie domyślnie zakończy się błędem RPC GoogleAdsFailure (partial_failure = false) lub zwróci normalną odpowiedź z błędami związanymi z operacją w partial_failure_error, gdy partial_failure = true.

validate_only jest szczególnie przydatny 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ą nieodpowiednią długość. Jedna zła reklama może spowodować, że cała partia zostanie odrzucona. Przetestowanie nowej reklamy w ramach żądania validate_only może ujawnić takie naruszenia. Aby zobaczyć, jak to działa, zapoznaj się z przykładowym kodem dotyczącym obsługi błędów związanych z naruszeniem zasad.

Pobieranie obiektów i statystyk wydajności

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

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

Pobieranie metadanych

GoogleAdsFieldService pobiera metadane dotyczące zasobów w interfejsie Google Ads API, np. dostępne atrybuty zasobu i jego typ danych. Szczegółowe informacje o wysyłaniu zapytań do tej usługi znajdziesz w przewodniku po metadanych zasobów.

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