Struktura interfejsu API

ondemand_video 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 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 customer.

• Każdy klient zawiera co najmniej 1 aktywną usługę .

• Każda kampania zawiera co najmniej jedną grupę reklam, aby grupować reklamy w logiczne kolekcje.

• Reklama w grupie reklam to reklama, której w domu. Wyjątkiem są kampanie promujące aplikacje, które mogą zawierać tylko jedną reklamę z grupy reklam na reklamę. grupa reklam zawiera co najmniej jedną reklamę z grupy reklam.

Możesz dołączyć co najmniej 1 AdGroupCriterion lub CampaignCriterion do grupy reklam lub kampanii. 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 w kampanii a także na wszystkie inne zasoby w kampanii. Możesz też określić budżety i daty kampanii.

Na koniec możesz dołączyć rozszerzenia na stronie na poziomie konta, kampanii lub grupy reklam. Rozszerzenia pozwalają udostępniać użytkownikom informacje zawarte w reklamach, takie jak numer telefonu, adres lub promocje.

Zasoby

Zasoby reprezentują elementy na Twoim koncie Google Ads. Campaign i AdGroup to 2 przykłady zasobów.

Identyfikatory obiektów

Każdy obiekt w Google Ads ma własny identyfikator. Niektóre z tych identyfikatorów są globalnie unikalne na wszystkich kontach Google Ads, a pozostałe są unikalne tylko w obrębie do ograniczonego zakresu.

Reguły te mogą być przydatne podczas projektowania pamięci lokalnej na potrzeby Google Ads obiektów.

Niektórych obiektów można używać na potrzeby wielu typów encji. W takich przypadkach obiekt zawiera pole type opisujące jego zawartość. Przykład: AdGroupAd może odnosić się do obiektu, takiego jak reklama tekstowa, reklama hotelu czy reklama lokalna. Dostęp do tej wartości można uzyskać za pomocą AdGroupAd.ad.type i zwraca wartość w polu Wyliczenie 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 kampania nazwy zasobów mają postać:

customers/customer_id/campaigns/campaign_id

Dlatego w przypadku kampanii o identyfikatorze 987654 na koncie Google Ads z identyfikatorem klienta. 1234567, resource_name to:

customers/1234567/campaigns/987654

Usługi

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

Modyfikowanie (mutacji) obiektów

Te usługi modyfikują instancje powiązanego typu zasobów za pomocą interfejsu mutate użytkownika. Dostarczają również żądanie get, które pobiera 1 zasób które mogą być przydatne podczas badania struktury zasobu.

Przykłady usług:

• CustomerService do modyfikacji klientach.

• CampaignService do modyfikacji kampaniami.

• AdGroupService do modyfikowania grup reklam.

Każde żądanie mutate musi zawierać odpowiednie obiekty operation. Dla: np. metoda CampaignService.MutateCampaigns wymaga co najmniej jednego instancji CampaignOperation. Zobacz Zmienianie i sprawdzanie obiektów dla szczegółowe omówienie działalności.

Równoczesne mutacje

Obiekt Google Ads nie może być modyfikowany jednocześnie przez więcej niż jedno źródło. Ten może powodować błędy w przypadku, gdy wielu użytkowników aktualizuje ten sam obiekt lub gdy wprowadzasz mutacje obiektów Google Ads równolegle przy użyciu . Obejmuje to aktualizację obiektu z wielu wątków w tym samym 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 dwa źródła próbuje jednocześnie wprowadzić mutację do obiektu, interfejs API generuje DatabaseError.CONCURRENT_MODIFICATION_ERROR

Mutacje asynchroniczne i synchroniczne

Metody mutacji interfejsu Google Ads API są synchroniczne. Wywołania interfejsu API zwracają tylko odpowiedź po zmutowaniu obiektów, co wymaga oczekiwania na odpowiedź użytkownika. To podejście jest stosunkowo proste do kodowania, negatywnie wpływają na równoważenie obciążenia i marnowanie zasobów, jeśli procesy są zmuszone do i poczekać na zakończenie połączenia.

Innym sposobem jest asynchroniczne mutowanie obiektów za pomocą BatchJobService, który wykonuje partie na wielu usługach bez czekania na ich zakończenie. Raz przesyłanie zadania wsadowego, serwery interfejsu Google Ads API asynchronicznie wykonują operacje, zwalniania procesów do wykonania innych operacji. Od czasu do czasu możesz sprawdzać stanie zadania na koniec.

Więcej informacji znajdziesz w przewodniku dotyczącym przetwarzania wsadowego. asynchroniczne.

Weryfikacja mutacji

Większość żądań mutacji można zweryfikować bez rzeczywistego wykonania wywołania w porównaniu z rzeczywistymi danymi. Możesz przetestować żądanie pod kątem brakujących parametrów i nieprawidłowych parametrów wartości pól bez faktycznego wykonania operacji.

Aby użyć tej funkcji, ustaw opcjonalne pole wartości logicznej validate_only żądania na true Żądanie będzie wtedy w pełni zweryfikowane tak, jakby miało być ale ostatnie wykonanie jest pomijane. Jeśli nie znaleziono błędów, zostanie wyświetlone pole puste . Jeśli weryfikacja się nie powiedzie, komunikaty o błędach w odpowiedzi będą wskazują punkty awarii.

validate_only jest szczególnie przydatny do testowania reklam pod kątem zgodności z zasadami naruszenia zasad. Reklamy są automatycznie odrzucane, jeśli naruszają zasady, takie jak: zawierające konkretne słowa, znaki interpunkcyjne, wielkie litery lub długość. Pojedyncza niewłaściwa reklama może spowodować błąd całej partii. Testowanie nowej reklamy w validate_only może ujawnić takie naruszenia. Zapoznaj się z przykładowym kodem dla obsługi błędy związane z naruszeniem zasad, aby zobaczyć, jak to działa.

Pobieranie statystyk obiektów i wydajności

GoogleAdsService to jedyny, spójny służy do pobierania obiektów i statystyk wydajności.

Wszystkie żądania Search i SearchStream dotyczące GoogleAdsService wymagają zapytania, które wskazuje zasób do zapytania, atrybuty zasobów i dane dotyczące wydajności do pobrania, predykaty do filtrowania żądań oraz segmenty używane do dalszego analizować statystyki skuteczności. Więcej informacji o formacie zapytania zapoznaj się z przewodnikiem Google Ads po języku zapytań.

Pobieranie metadanych

Pobiera: GoogleAdsFieldService metadanych zasobów w interfejsie Google Ads API, takich jak atrybuty dostępne dla i typu danych tego zasobu.

Ta usługa dostarcza informacji potrzebnych do tworzenia zapytania, aby: GoogleAdsService Dla wygody informacje zwrócone przez GoogleAdsFieldService również jest dostępny w dokumentacji pól.