Film: Obejrzyj prezentację na temat usług i zasobów z warsztatów w 2019 r.
W tym przewodniku omawiamy główne komponenty, które składają się na interfejs 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 manipulują nimi.
Hierarchia obiektów
Konto Google Ads można traktować jako hierarchię obiektów.
Zasób najwyższego poziomu konta to klient.
Każdy klient ma co najmniej jedną aktywną kampanię.
Każda kampania zawiera co najmniej jedną grupę reklam, która łączy reklamy w logiczne kolekcje.
Reklama z grupy reklam to aktywna reklama. Wyjątkiem są kampanie promujące aplikacje, w których w danej grupie reklam może znajdować się tylko 1 reklama, a każda grupa zawiera co najmniej 1 reklamę.
Do grupy reklam lub kampanii możesz dołączyć 1 lub więcej elementów AdGroupCriterion bądź CampaignCriterion. Są to kryteria określające sposób wyświetlania reklam.
Jest wiele typów kryteriów, np. słowa kluczowe, przedziały wiekowe i lokalizacje. Kryteria zdefiniowane na poziomie kampanii mają wpływ na wszystkie jej zasoby. Możesz też określić budżety i daty na poziomie całej kampanii.
Możesz też dołączać rozszerzenia na poziomie konta, kampanii lub grupy reklam. Rozszerzenia pozwalają na dodawanie do reklam dodatkowych informacji, takich jak numer telefonu, adres lub promocje.
Zasoby
Zasoby reprezentują elementy na Twoim koncie Google Ads. Przykłady zasobów to Campaign i AdGroup.
Identyfikatory obiektów
Każdy obiekt w Google Ads ma własny identyfikator. Niektóre z tych identyfikatorów są unikalne globalnie na wszystkich kontach Google Ads, a inne tylko w ograniczonym zakresie.
| Identyfikator obiektu | Zakres unikalności | Produkt unikalny globalnie? |
|---|---|---|
| Identyfikator budżetu | Globalne | Tak |
| Identyfikator kampanii | Globalne | Tak |
| Identyfikator grupy reklam | Globalne | Tak |
| Identyfikator reklamy | Grupa reklam | Nie, ale para (AdGroupId, AdId) jest unikalna globalnie |
| Identyfikator kryterium grupy reklam | Grupa reklam | Nie, ale para (AdGroupId, CriterionId) jest unikalna globalnie |
| Identyfikator kryterium Campaignkryterium | Priorytet | Nie, ale para (CampaignId, CriterionId) jest unikalna globalnie |
| Rozszerzenia reklam | Priorytet | Nie, ale para (CampaignId, AdExtensionId) jest unikalna globalnie |
| Identyfikator kanału RSS | Globalne | Tak |
| Identyfikator elementu kanału RSS | Globalne | Tak |
| Identyfikator atrybutu kanału | Kanał | Nie |
| Identyfikator mapowania kanału | Globalne | Tak |
| Identyfikator etykiety | Globalne | Tak |
| Identyfikator listy użytkowników | Globalne | Tak |
Reguły te mogą być przydatne przy projektowaniu pamięci lokalnej dla obiektów Google Ads.
Niektórych obiektów można używać na potrzeby 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 reklama tekstowa, reklama hotelu lub reklama lokalna. Dostęp do tej wartości można uzyskać przez pole AdGroupAd.ad.type. Zwraca ona wartość w wyliczeniu AdType.
Nazwy zasobów
Każdy zasób jest jednoznacznie identyfikowany przez ciąg tekstowy resource_name, który łączy zasób i jego elementy nadrzędne w ścieżkę. Nazwy zasobów kampanii mają np. taką postać:
customers/customer_id/campaigns/campaign_id
Zatem w przypadku kampanii o identyfikatorze 987654 na koncie Google Ads z identyfikatorem klienta 1234567 resource_name będzie mieć postać:
customers/1234567/campaigns/987654
Usługi
Usługi umożliwiają pobieranie i modyfikowanie elementów Google Ads. Istnieją 3 typy usług: usługi modyfikacji, pobierania obiektów i statystyk oraz usługi pobierania metadanych.
Modyfikowanie (mutacji) obiektów
Te usługi modyfikują instancje powiązanego typu zasobów za pomocą żądania mutate. Dostarczają też żądanie get, które pobiera pojedynczą instancję zasobu, co może być przydatne przy badaniu struktury zasobu.
Przykłady usług:
CustomerService– do 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 wymaga wystąpienia co najmniej 1 instancji CampaignOperation. Szczegółowe informacje o operacjach znajdziesz w artykule Zmienianie i sprawdzanie obiektów.
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ć występowanie błędów w przypadku, gdy wielu użytkowników aktualizuje ten sam obiekt w aplikacji lub gdy wprowadzasz mutacje obiektów Google Ads równolegle w wielu wątkach. Obejmuje to aktualizowanie obiektu z wielu wątków w tej samej aplikacji lub z różnych aplikacji (np. aplikacji i jednoczesnej sesji interfejsu Google Ads).
Interfejs API nie umożliwia zablokowania obiektu przed aktualizacją. Jeśli dwa źródła próbują jednocześnie wprowadzić mutację do obiektu, interfejs API zgłosi DatabaseError.CONCURRENT_MODIFICATION_ERROR.
Mutacje asynchroniczne i synchroniczne
Metody mutacji interfejsu Google Ads API są synchroniczne. Wywołania interfejsu API zwracają odpowiedź dopiero po wprowadzeniu mutacji do obiektów, co wymaga oczekiwania na odpowiedź na każde żądanie. To podejście jest stosunkowo proste w tworzeniu kodu, ale może negatywnie wpłynąć na równoważenie obciążenia i marnowanie zasobów, jeśli procesy będą musiały czekać na zakończenie wywołań.
Alternatywnym podejściem jest asynchroniczne mutowanie obiektów za pomocą metody BatchJobService, która wykonuje partie operacji na wielu usługach bez oczekiwania na ich zakończenie. Po przesłaniu zadania zbiorczego serwery interfejsu Google Ads API wykonują operacje asynchronicznie, co pozwala zwolnić procesy do wykonywania innych operacji. Możesz okresowo sprawdzać stan zadania, aby je ukończyć.
Więcej informacji o przetwarzaniu asynchronicznym znajdziesz w przewodniku dotyczącym przetwarzania wsadowego.
Weryfikacja mutacji
Większość żądań mutacji można zweryfikować bez wykonywania wywołania względem danych rzeczywistych. Możesz przetestować żądanie pod kątem brakujących parametrów i nieprawidłowych wartości pól bez konieczności wykonywania tej operacji.
Aby użyć tej funkcji, ustaw opcjonalne pole wartości logicznej validate_only żądania na true. Następnie żądanie zostanie w pełni zweryfikowane tak, jakby miało zostać wykonane, ale ostatnie wykonanie jest pomijane. Jeśli nie zostaną wykryte żadne błędy, zwracana jest
pusta odpowiedź. Jeśli weryfikacja się nie powiedzie, komunikaty o błędach w odpowiedzi będą wskazywać punkty błędu.
validate_only jest szczególnie przydatny do testowania reklam pod kątem częstych naruszeń zasad. Reklamy są automatycznie odrzucane, jeśli naruszają zasady dotyczące np. stosowania określonych słów, interpunkcji, wielkości liter lub długości. Pojedyncza nieprawidłowa reklama
mogłaby spowodować błąd całej partii. Testowanie nowej reklamy w odpowiedzi na żądanie validate_only może ujawnić takie naruszenia. Zapoznaj się z przykładowym kodem do obsługi błędów związanych z naruszeniem zasad, aby zobaczyć, jak to wygląda w praktyce.
Pobieranie statystyk obiektów i wydajności
GoogleAdsService to ujednolicona usługa do pobierania obiektów i statystyk wydajności.
Wszystkie żądania Search i SearchStream dotyczące GoogleAdsService wymagają zapytania, które wskazuje zasób, do którego należy zapytanie, atrybuty zasobów i dane o wydajności do pobrania, predykaty używane do filtrowania żądań oraz segmenty, które mają służyć do dalszego podziału statystyk skuteczności. Więcej informacji o formacie zapytania znajdziesz w przewodniku po języku zapytań w Google Ads.
Pobieranie metadanych
GoogleAdsFieldService pobiera metadane dotyczące zasobów w interfejsie Google Ads API, takie jak dostępne atrybuty zasobu i jego typ danych.
Ta usługa dostarcza informacji potrzebnych do tworzenia zapytania do GoogleAdsService. Dla wygody informacje zwracane przez funkcję GoogleAdsFieldService są też dostępne w dokumentacji pól.