Struktura interfejsu API

Film: Prezentacja usług i zasobów na warsztatach w 2019 roku

W tym przewodniku opisujemy 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ą i modyfikują jednostki Google Ads.

Hierarchia obiektów

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

  • Głównym kontem konta jest klient.

  • Każde konto zawiera co najmniej jedną aktywną kampanię.

  • Każdy element Campaign zawiera co najmniej 1 grupę reklam, służącą do grupowania reklam w logiczne zbiory.

  • Każdy element AdGroup zawiera co najmniej jedną reklamę z grupy reklam. AdGroupAd reprezentuje reklamę, która jest wyświetlana.

Do grupy reklam lub kampanii możesz dołączyć co najmniej 1 element AdGroupCriterion lub CampaignCriterion. Są to kryteria określające sposób wyświetlania reklam.

Istnieje wiele typów kryteriów, takich jak słowa kluczowe, przedziały wiekowe i lokalizacje. Kryteria zdefiniowane na poziomie kampanii mają wpływ na wszystkie pozostałe zasoby w kampanii. Możesz też określić budżety i daty obejmujące całą kampanię.

Na koniec możesz dodać rozszerzenia na poziomie konta, kampanii lub grupy reklam. Dzięki rozszerzeniom możesz wyświetlać w reklamach dodatkowe informacje, np. numer telefonu, adres czy promocje.

Zasoby

Zasoby reprezentują jednostki na koncie Google Ads. Dwa przykłady zasobów: Campaign i AdGroup.

Identyfikatory obiektów

Każdy obiekt w Google Ads jest identyfikowany na podstawie własnego identyfikatora. Niektóre z nich są globalnie unikalne na wszystkich kontach Google Ads, a inne w ograniczonym zakresie.

Identyfikator obiektu Zakres unikalności Niepowtarzalny globalnie?
Identyfikator budżetu Globalny Tak
Identyfikator kampanii Globalny Tak
Identyfikator grupy reklam Globalny Tak
Identyfikator reklamy Ad Group Nie, ale para (AdGroupId, AdId) jest globalnie niepowtarzalna
Identyfikator kryterium grupy reklam Ad Group Nie, ale para (AdGroupId, CriterionId) jest globalnie niepowtarzalna
Identyfikator kryterium kryterium Kampania Nie, ale para (CampaignId, CriterionId) jest globalnie niepowtarzalna
Rozszerzenia reklam Kampania Nie, ale para (CampaignId, AdExtensionId) jest globalnie niepowtarzalna
Identyfikator kanału RSS Globalny Tak
Identyfikator elementu kanału RSS Globalny Tak
Identyfikator atrybutu kanału Plik danych Nie
Identyfikator mapowania kanału Globalny Tak
Identyfikator etykiety Globalny Tak
Identyfikator listy użytkowników Globalny Tak

Te reguły identyfikatora mogą być przydatne podczas projektowania pamięci lokalnej dla obiektów Google Ads.

Niektórych obiektów można użyć dla wielu typów encji. W takich przypadkach obiekt zawiera pole type z opisem jego zawartości. Na przykład AdGroupAd może się odnosić do reklamy tekstowej, reklamy hotelu, reklamy lokalnej itp. Ta wartość jest dostępna w polu AdGroupAd.ad.type i zwraca wartość w wartości AdType.

Nazwy zasobów

Każdy zasób jest jednoznacznie identyfikowany przez ciąg 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 wyniesie:

customers/1234567/campaigns/987654

Usługi

Usługi umożliwiają pobieranie i modyfikowanie jednostek Google Ads. Wyróżniamy 3 typy usług: modyfikowanie, pobieranie danych obiektów i statystyk oraz usługi pobierania metadanych.

Modyfikowanie (mutacja) obiektów

Te usługi modyfikują wystąpienia powiązanego typu zasobu za pomocą żądania mutate. Dostarczają też żądanie get, które pobiera pojedynczą instancję zasobu, co może być pomocne przy analizie struktury zasobu.

Przykłady usług:

Każde żądanie mutate musi zawierać odpowiednie obiekty operation. Na przykład metoda CampaignService.MutateCampaigns oczekuje co najmniej jednego wystąpienia CampaignOperation. Szczegółowe omówienie operacji znajdziesz w artykule o zmienianiu i sprawdzaniu obiektów.

Jednoczesne mutacje

Obiektu Google Ads nie można modyfikować jednocześnie dla więcej niż jednego źródła. Może to powodować błędy, jeśli wielu użytkowników aktualizuje ten sam obiekt w Twojej aplikacji lub jeśli zmieniasz obiekty 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. 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 wprowadzić mutację obiektu, interfejs API zwraca wartość DatabaseError.CONCURRENT_MODIFICATION_ERROR.

Mutacje asynchroniczne i synchroniczne

Metody mutacji interfejsu Google Ads API są synchroniczne. Wywołania interfejsu API zwracają odpowiedź po mutacjach obiektów, co wymaga oczekiwania na odpowiedź na każde żądanie. Takie podejście jest stosunkowo proste do kodowania, ale może negatywnie wpłynąć na równoważenie obciążenia i marnowanie zasobów, jeśli proces musi czekać na zakończenie wywołań.

Alternatywnym podejściem jest asynchroniczne obiekty za pomocą usługi BatchJobService, która wykonuje partie operacji w wielu usługach bez oczekiwania na ich zakończenie. Po przesłaniu zadania zbiorczego serwery API Google Ads wykonują asynchroniczne działania, co pozwala wykonywać inne działania. Możesz co jakiś czas sprawdzać stan zadania.

Więcej informacji o przetwarzaniu asynchronicznym znajdziesz w przewodniku przetwarzania wsadowego.

Weryfikowanie mutacji

Większość żądań mutacji może być weryfikowana bez wykonywania wywołania w odniesieniu do rzeczywistych danych. Możesz przetestować żądanie brakujących parametrów i nieprawidłowych wartości pól, nie wykonując operacji.

Aby użyć tej funkcji, ustaw opcjonalne pole wartości logicznej żądania validate_only na true. W trakcie tego żądania żądanie jest w pełni weryfikowane tak, jakby miało zostać wykonane, ale ostateczne wykonanie zostało pominięte. W przypadku braku błędów zwracana jest pusta odpowiedź. Jeśli weryfikacja się nie powiedzie, komunikaty o błędzie będą wskazywać punkty niepowodzenia.

validate_only jest szczególnie przydatna do testowania reklam pod kątem częstych naruszeń zasad. Reklamy są automatycznie odrzucane, jeśli naruszają zasady, np. zawierają określone słowa, znaki interpunkcyjne, wielkie litery lub długość. Pojedyncza zła reklama może spowodować niepowodzenie całej grupy. Testowanie nowej reklamy w żądaniu validate_only może wykryć takie naruszenia. Zobacz przykładowy kod dotyczący postępowania w przypadku naruszenia zasad, aby zobaczyć, jak to działa.

Pobieranie statystyk obiektów i wydajności

GoogleAdsService to pojedyncza, ujednolicona usługa do pobierania statystyk obiektów i statystyk wydajności.

Wszystkie żądania Search i SearchStream dla GoogleAdsService wymagają zapytania określającego zasób, do którego chcesz wysłać zapytanie, atrybutów zasobów i wskaźników wydajności, które mają zostać użyte do filtrowania żądania, oraz segmentów, które posłużą 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 o zasobach w interfejsie API Google Ads, w tym atrybuty dostępne dla zasobu i jego typu danych.

Ta usługa dostarcza informacje potrzebne do utworzenia zapytania do strony GoogleAdsService. Dla wygody użytkowników informacje zwracane przez GoogleAdsFieldService są też dostępne w dokumentacji referencyjnej pól.