Z tego przewodnika dowiesz się, z jakich głównych komponentów składa się interfejs Google Ads API. Interfejs Google Ads API składa się z zasobów i usług. Zasób reprezentuje jednostkę Google Ads, a usługi pobierają jednostki Google Ads i nimi manipulują.
Hierarchia obiektów
Konto Google Ads można traktować jako hierarchię obiektów.
Zasobem najwyższego poziomu konta 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 to reklama, którą wyświetlasz w grupie reklam. Z wyjątkiem kampanii promujących aplikacje, które mogą zawierać tylko 1 reklamę w grupie reklam, każda grupa reklam zawiera co najmniej 1 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 tematu wyszukiwania za pomocą AssetGroupSignal.
Do grupy reklam lub kampanii możesz dołączyć co najmniej 1 komponent AdGroupCriterion lub CampaignCriterion. Są to kryteria określające, w jaki sposób są wywoływane reklamy.
Istnieje wiele rodzajów kryteriów, takich jak słowa kluczowe, przedziały wiekowe i lokalizacje. Kryteria zdefiniowane na poziomie kampanii wpływają na wszystkie inne zasoby w kampanii. Możesz też określać budżety oraz daty i godziny rozpoczęcia i zakończenia kampanii lub poszczególnych reklam za pomocą symboli AdGroupAd.start_date_time i AdGroupAd.end_date_time.
Komponenty możesz też 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 Komponenty – omówienie.
Zasoby
Zasoby reprezentują jednostki na koncie Google Ads.
Campaign i AdGroup to dwa 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ą niepowtarzalne na całym świecie we wszystkich kontach Google Ads, a inne są niepowtarzalne tylko w określonym zakresie.
| Identyfikator obiektu | Zakres unikalności | Globalnie unikalny? |
|---|---|---|
| Identyfikator budżetu | Globalny | Tak |
| Identyfikator kampanii | Globalny | Tak |
| Identyfikator grupy reklam | Globalny | Tak |
| Identyfikator reklamy | Grupa reklam | Nie, ale para (AdGroupId, AdId) jest unikalna na całym świecie. Udostępnianie AdId w wielu grupach reklam jest zabronione. |
| Identyfikator kryterium w grupie reklam | Grupa reklam | Nie, ale para (AdGroupId, CriterionId) jest unikalna na całym świecie |
| Identyfikator CampaignCriterion | Kampania | Nie, ale para (CampaignId, CriterionId) jest unikalna na całym świecie |
| Identyfikator etykiety | Klient | Nie, ale para (CustomerId, LabelId) jest unikalna na całym świecie |
| Identyfikator listy użytkowników | Globalny | Tak |
| Identyfikator zasobu | Globalny | Tak |
Te reguły 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 jednostek. 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 hoteli lub reklama generująca popyt. Dostęp do tej wartości można uzyskać za pomocą pola AdGroupAd.ad.type, które zwraca wartość z wyliczenia AdType. Pamiętaj, że
możliwość zmiany może się różnić w zależności od wersji (np. VideoResponsiveAdInfo w Ad można zmieniać 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 wartość 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: usługi modyfikacji, pobierania obiektów i statystyk oraz pobierania metadanych.
Modyfikowanie obiektów
Usługi dotyczące konkretnych zasobów modyfikują instancje powiązanego typu zasobu za pomocą mutate żądania. Możesz też używać GoogleAdsService.Mutate do przeprowadzania 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 konkretnymi zasobami:
CustomerService– modyfikowanie klientów.CampaignService– do modyfikowania kampanii.AdGroupService– umożliwia modyfikowanie 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 sekcji Obiekty zmian.
Równoczesne mutacje
Obiektu Google Ads nie może modyfikować jednocześnie 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 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 z sesji interfejsu Google Ads).
Interfejs API nie umożliwia blokowania obiektu przed aktualizacją. Jeśli 2 źródła próbują jednocześnie zmienić obiekt, interfejs API zgłasza błąd DatabaseError.CONCURRENT_MODIFICATION_ERROR.
Asynchroniczne i synchroniczne zmiany
Metody mutacji 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 prowadzić do marnowania zasobów, jeśli procesy są zmuszone do czekania na zakończenie wywołań.
Innym podejściem jest asynchroniczne zmienianie obiektów za pomocą funkcji BatchJobService, która wykonuje partie operacji w wielu usługach bez czekania na ich zakończenie. Po przesłaniu zadania wsadowego serwery interfejsu Google Ads API wykonują operacje asynchronicznie, zwalniając procesy do wykonywania 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ń 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 korzystać z tej funkcji, ustaw opcjonalne pole logiczne validate_only w żądaniu na wartość true. Żądanie jest w pełni weryfikowane tak, jakby miało zostać wykonane, ale ostateczne wykonanie jest pomijane. Jeśli nie zostaną znalezione żadne błędy, zwracana jest odpowiedź bez wypełnionych wyników zmian (results jest puste). Jeśli weryfikacja się nie powiedzie, żądanie domyślnie zakończy się niepowodzeniem i zostanie zwrócony błąd RPC GoogleAdsFailure (partial_failure = false) lub zwrócona zostanie normalna odpowiedź z błędami specyficznymi dla operacji w partial_failure_error, gdy partial_failure = true.
validate_only jest szczególnie przydatne do testowania reklam pod kątem typowych naruszeń zasad. Reklamy są automatycznie odrzucane, jeśli naruszają zasady dotyczące np. używania określonych słów, znaków interpunkcyjnych, wielkich liter lub długości. Jedna zła reklama może spowodować niepowodzenie całego wsadu. Testowanie nowej reklamy w ramach validate_only
może ujawnić takie naruszenia. Aby zobaczyć to w praktyce, zapoznaj się z przykładem kodu dotyczącym obsługi błędów związanych z naruszeniem zasad.
Pobieranie obiektów i statystyk wydajności
GoogleAdsService to pojedyncza, 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 dane o 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 zasobów w interfejsie Google Ads API, takie jak 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 udostępnia informacje potrzebne do utworzenia zapytania do GoogleAdsService. Dla wygody informacje zwracane przez GoogleAdsFieldService są też dostępne w dokumentacji referencyjnej pól.