Ten przewodnik przedstawia główne komponenty interfejsu Google Ads API. Interfejs Google Ads API składa się z zasobów i usług. Zasób reprezentuje encję Google Ads, a usługi służą do pobierania encji Google Ads i manipulowania nimi.
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 reprezentuje reklamę wyświetlaną w grupie reklam. 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.
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 łączysz z grupą komponentów za pomocą
AssetGroupAsset, a sygnały dotyczące odbiorców lub tematów wyszukiwania
– za pomocą AssetGroupSignal.
Do grupy reklam lub kampanii możesz dołączyć co najmniej 1 zasób AdGroupCriterion
lub CampaignCriterion. Reprezentują one kryteria określające, jak mają być wywoływane reklamy.
Istnieje wiele typó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ślić budżety oraz daty i godziny rozpoczęcia i zakończenia kampanii lub poszczególnych reklam za pomocą pól AdGroupAd.start_date_time i AdGroupAd.end_date_time.
Na koniec możesz dołączyć komponenty na poziomie konta, kampanii, grupy reklam lub grupy komponentów. Komponenty umożliwiają podawanie w reklamach dodatkowych informacji, takich jak numery telefonów, adresy lub promocje. Więcej informacji znajdziesz w artykule Omówienie komponentów.
Zasoby
Zasoby reprezentują encje 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ą globalnie unikalne we wszystkich kontach Google Ads, a inne są unikalne tylko w ograniczonym 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 globalnie unikalna. Udostępnianie AdId w wielu grupach reklam jest zabronione. |
| Identyfikator kryterium grupy reklam | Grupa reklam | Nie, ale para (AdGroupId, CriterionId) jest globalnie unikalna. |
| Identyfikator kryterium kampanii | Kampania | Nie, ale para (CampaignId, CriterionId) jest globalnie unikalna. |
| Identyfikator etykiety | Klient | Nie, ale para (CustomerId, LabelId) jest globalnie unikalna. |
| Identyfikator listy użytkowników | Globalny | Tak |
| Identyfikator zasobu | Globalny | Tak |
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 encji. 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. Do tej wartości można uzyskać dostęp za pomocą pola AdGroupAd.ad.type, które zwraca wartość z typu wyliczeniowego 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 encji Google Ads. Istnieją 3 typy usług: modyfikacji, pobierania obiektów i statystyk oraz pobierania metadanych.
Modyfikowanie (zmienianie) obiektów
Usługi specyficzne dla zasobów modyfikują instancje powiązanego typu zasobu za pomocą żądania mutate. Możesz też użyć
GoogleAdsService.Mutate, aby wykonywać niepodzielne
modyfikacje w przypadku wielu typów zasobów w jednym żądaniu (np. utworzyć
budżet kampanii, kampanię i grupę reklam).
Przykłady usług specyficznych dla zasobów:
CustomerServicedo modyfikowania klientów.CampaignServicedo modyfikowania kampanii.AdGroupServicedo 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 obiektów.
Równoczesne modyfikacje
Obiektu Google Ads nie może modyfikować jednocześnie więcej niż 1 ź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 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ą jednocześnie zmodyfikować obiekt, interfejs API zgłasza błąd
DatabaseError.CONCURRENT_MODIFICATION_ERROR.
Asynchroniczne i synchroniczne modyfikacje
Metody modyfikacji interfejsu Google Ads API są synchroniczne. Wywołania interfejsu API zwracają odpowiedź dopiero po zmodyfikowaniu 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 modyfikowanie obiektów za pomocą
BatchJobService, która 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 umożliwia procesom wykonywanie innych operacji. Możesz okresowo sprawdzać stan zadania, aby sprawdzić, czy zostało zakończone.
Więcej informacji o przetwarzaniu asynchronicznym znajdziesz w przewodniku Przetwarzanie wsadowe.
Weryfikacja modyfikacji
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 wykonywania operacji.
Aby użyć tej funkcji, ustaw opcjonalne pole logiczne validate_only żądania na true. Żądanie jest w pełni weryfikowane tak, jakby miało zostać wykonane, ale pomijane jest jego ostateczne wykonanie. Jeśli nie zostaną znalezione żadne błędy, odpowiedź zostanie zwrócona bez wypełnionych wyników modyfikacji (results jest puste). Jeśli weryfikacja się nie powiedzie, żądanie zakończy się niepowodzeniem z powodu błędu RPC GoogleAdsFailure (domyślnie partial_failure = false) lub zwróci normalną 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, 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, o który 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 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. Szczegółowe informacje o wysyłaniu zapytań do tej usługi znajdziesz w przewodniku po metadanych zasobów.
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.