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.
Możesz też dodawać rozszerzenia na poziomie konta, kampanii lub grupy reklam. Rozszerzenia umożliwiają wyświetlanie w reklamach dodatkowych informacji, takich jak numer telefonu, adres lub promocje.
Zasoby
Zasoby reprezentują jednostki 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 globalnie na wszystkich kontach Google Ads, a inne 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 w skali globalnej |
| Identyfikator kryterium w grupie reklam | Grupa reklam | Nie, ale para (AdGroupId, CriterionId) jest unikalna w skali globalnej |
| Identyfikator CampaignCriterion | Kampania | Nie, ale para (CampaignId, CriterionId) jest unikalna w skali globalnej |
| Rozszerzenia reklam | Kampania | Nie, ale para (CampaignId, AdExtensionId) jest unikalna w skali globalnej |
| Identyfikator etykiety | Cały świat | Tak |
| 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 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: modyfikacja, 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 zmiany
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 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 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 przydatny do testowania reklam pod kątem typowych naruszeń zasad. Reklamy są automatycznie odrzucane, jeśli naruszają zasady dotyczące np. określonych słów, znaków interpunkcyjnych, wielkich liter lub długości. Jedna nieprawidłowa reklama może spowodować odrzucenie 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 skutecznoś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 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.