Film: obejrzyj prezentację „Usługi i zasoby” z warsztatów w 2019 roku
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 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 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. Każda grupa reklam zawiera co najmniej 1 reklamę w grupie reklam, z wyjątkiem kampanii promujących aplikacje, które mogą zawierać tylko 1 reklamę w grupie reklam.
Do grupy reklam lub kampanii możesz dołączyć co najmniej 1 AdGroupCriterion lub CampaignCriterion. Są to kryteria określające, 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 wpływają na wszystkie inne zasoby w kampanii. Możesz też określić budżety i daty dla całej kampanii.
Komponenty możesz dodawać na poziomie konta, kampanii lub grupy reklam. Komponenty umożliwiają dodawanie do reklam dodatkowych informacji, takich jak numery telefonów, adresy lub promocje. Zobacz Przegląd komponentów.
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 w skali globalnej na wszystkich kontach Google Ads, a inne są unikalne tylko w określonym zakresie.
| Identyfikator obiektu | Zakres unikalności | Unikalny na całym świecie? |
|---|---|---|
| Identyfikator budżetu | Cały świat | Tak |
| Identyfikator kampanii | Cały świat | Tak |
| Identyfikator grupy reklam | Cały świat | Tak |
| Identyfikator reklamy | Grupa reklam | Nie, ale para (AdGroupId, AdId) jest unikalna na całym świecie |
| 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 | Cały świat | Tak |
| Identyfikator zasobu | Cały świat | Tak |
Te reguły identyfikatorów mogą być przydatne podczas projektowania lokalnego miejsca na dane dla obiektów Google Ads.
Niektóre obiekty mogą być używane w przypadku wielu typów podmiotó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. Dostęp do tej wartości można uzyskać 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 z identyfikatorem klienta 1234567 wartość resource_name będzie następująca:
customers/1234567/campaigns/987654
Usługi
Usługi umożliwiają pobieranie i modyfikowanie elementów Google Ads. Istnieją 3 rodzaje usług: modyfikowanie, pobieranie obiektów i statystyk oraz pobieranie metadanych.
Modyfikowanie obiektów
Te usługi modyfikują instancje powiązanego typu zasobu za pomocą mutateżądania. Dostarczają też getzapytanie, które pobiera pojedynczą instancję zasobuget. Może to być przydatne do zbadania struktury zasobu.
Przykłady usług:
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 jednej instancji CampaignOperation. Szczegółowe omówienie operacji znajdziesz w artykule Zmiana i sprawdzanie obiektów.
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 równolegle zmieniasz obiekty Google Ads 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 jednocześnie 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 modyfikacji 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ż takie 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 czekać 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, 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 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 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, zwracana jest pusta odpowiedź. Jeśli weryfikacja się nie powiedzie, komunikaty o błędach w odpowiedzi wskażą punkty, w których wystąpił problem.
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łej partii. Testowanie nowej reklamy w ramach validate_only
żądania może ujawnić takie naruszenia. Aby zobaczyć to w praktyce, zapoznaj się z przykładem kodu dotyczącym obsługi błędów naruszenia 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.
Ta usługa udostępnia informacje potrzebne do utworzenia zapytania do GoogleAdsService. Dla Twojej wygody informacje zwracane przez GoogleAdsFieldService są też dostępne w dokumentacji pól.