Struktura interfejsu API

Film: wykład na temat usług i zasobów z warsztatów z 2019 roku

W tym przewodniku przedstawiamy główne komponenty interfejsu Google Ads API. Interfejs Google Ads API składa się z zasobów i usług. Zasoby reprezentują elementy Google Ads, a usługi umożliwiają pobieranie elementów Google Ads i manipulowanie nimi.

Hierarchia obiektów

Konto Google Ads można traktować jako hierarchię obiektów.

Model kampanii

  • Zasób najwyższego poziomu na koncie to 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 kolekcje.

  • Reklama grupy reklam to reklama, którą wyświetlasz. Każda grupa reklam zawiera co najmniej 1 reklamę, z wyjątkiem kampanii promujących aplikacje, które mogą zawierać tylko 1 reklamę na grupę reklam.

Do grupy reklam lub kampanii możesz dołączyć co najmniej 1 element AdGroupCriterion lub CampaignCriterion. Są to kryteria określające, jak wyświetlają się reklamy.

Istnieje wiele typów kryteriów, np. słowa kluczowe, przedziały wiekowe i lokalizacje. Kryteria zdefiniowane na poziomie kampanii wpływają na wszystkie inne zasoby w ramach kampanii. Możesz też określić budżety i daty dotyczące całej kampanii.

Możesz też dołączyć rozszerzenia na poziomie konta, kampanii lub grupy reklam. Rozszerzenia umożliwiają dodawanie do reklam dodatkowych informacji, np. numeru telefonu, adresu ulicznego lub promocji.

Zasoby

Zasoby to elementy 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ą globalnie unikalne na wszystkich kontach Google Ads, a inne są unikalne tylko w określonym zakresie.

Identyfikator obiektu Zakres unikalności Globally Unique?
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 globalnie unikalna
Identyfikator kryterium w grupie reklam Grupa reklam Nie, ale para (AdGroupId, CriterionId) jest globalnie unikalna
CampaignCriterion ID Kampania Nie, ale para (CampaignId, CriterionId) jest globalnie unikalna
Rozszerzenia reklam Kampania Nie, ale para (CampaignId, AdExtensionId) jest globalnie unikalna
Identyfikator kanału RSS Cały świat Tak
Identyfikator elementu kanału Cały świat Tak
Identyfikator atrybutu w pliku danych Kanał Nie
Identyfikator mapowania kanału Cały świat Tak
Identyfikator etykiety Cały świat Tak
Identyfikator listy użytkowników Cały świat Tak

Te reguły identyfikatorów mogą być przydatne podczas projektowania lokalnego miejsca na dane obiektów Google Ads.

Niektóre obiekty mogą służyć do różnych typów obiektó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 enumeracji AdType.

Nazwy zasobów

Każdy zasób jest jednoznacznie identyfikowany za pomocą ciągu resource_name, który łączy zasób i jego 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 wynosić:

customers/1234567/campaigns/987654

Usługi

Usługi umożliwiają pobieranie i modyfikowanie elementów Google Ads. Istnieją 3 rodzaje usług: modyfikacji, pobierania obiektów i statystyk oraz pobierania metadanych.

modyfikować (mutować) obiekty;

Te usługi modyfikują wystąpienia powiązanego typu zasobu za pomocą żądania mutate. Dostarczają też get, które zwraca pojedynczy zasób. Może to być przydatne do sprawdzenia struktury zasobu.

Przykłady usług:

Każde żądanie mutate musi zawierać odpowiednie obiekty operation. Na przykład metoda CampaignService.MutateCampaigns oczekuje co najmniej jednej instancji CampaignOperation. Więcej informacji o operacjach znajdziesz w artykule Zmienianie i sprawdzanie obiektów.

Równoczesne operacje zmiany

Obiekt Google Ads nie może być modyfikowany jednocześnie przez więcej niż 1 źródło. Może to powodować występowanie błędów, jeśli wielu użytkowników aktualizuje ten sam obiekt za pomocą aplikacji lub jeśli zmieniasz obiekty Google Ads równolegle za pomocą wielu wątków. Obejmuje to aktualizowanie obiektu z różnych wątków w tej samej aplikacji lub z różnych aplikacji (np. z Twojej aplikacji i jednoczesnej sesji interfejsu Google Ads).

Interfejs API nie umożliwia zablokowania 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.

Mutacje asynchroniczne a mutacje synchroniczne

Metody mutate interfejsu Google Ads API są synchroniczne. Wywołania interfejsu API zwracają odpowiedź dopiero po zmutowaniu obiektów, dlatego musisz czekać na odpowiedź na każde żądanie. Chociaż takie podejście jest stosunkowo proste do zaimplementowania w kodzie, 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 mutowanie obiektów asynchronicznie za pomocą funkcji 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 procesom wykonywać inne operacje. 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 zbiorczym.

Weryfikacja mutacji

Większość żądań zmiany można sprawdzić bez faktycznego wykonania wywołania z użyciem rzeczywistych danych. Możesz przetestować żądanie pod kątem brakujących parametrów i nieprawidłowych wartości pól bez faktycznego wykonania operacji.

Aby korzystać z tej funkcji, ustaw opcjonalne pole logiczne validate_only na true. Prośba zostanie wtedy w pełni zweryfikowana, tak jakby miała zostać wykonana, ale jej ostateczne wykonanie zostanie pominięte. Jeśli nie znaleziono żadnych błędów, zwracana jest pusta odpowiedź. Jeśli weryfikacja się nie powiedzie, komunikaty o błędach w odpowiedzi będą wskazywać punkty, w których wystąpiły błędy.

validate_only jest szczególnie przydatny 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, wielkość liter lub długość. Jedna nieodpowiednia reklama może spowodować niepowodzenie całego zbioru. Testowanie nowej reklamy w ramach validate_onlymoże ujawnić takie naruszenia. Aby zobaczyć, jak to działa, zapoznaj się z przykładem kodu dotyczącego obsługi błędów związanych z naruszeniem zasad.

Pobieranie statystyk dotyczących obiektów i wydajności

GoogleAdsService to jedna, zintegrowana 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, atrybuty zasobu i dane dotyczące skuteczności do pobrania, predykaty do użycia do filtrowania żądania oraz segmenty do użycia do dalszego podziału statystyk skuteczności. Więcej informacji o formacie zapytania znajdziesz w przewodniku po języku zapytań Google Ads.

Pobieranie metadanych

GoogleAdsFieldService pobiera metadane dotyczące zasobów w interfejsie Google Ads API, np. dostępne atrybuty zasobu i jego typ danych.

Ta usługa udostępnia informacje potrzebne do tworzenia zapytań do usługi GoogleAdsService. Dla wygody informacje zwracane przez funkcję GoogleAdsFieldService znajdziesz też w dokumentacji dotyczącej pól.

Wstecz
Przegląd
Dalej
Obsługa wersji