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ż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.
Identyfikator obiektu | Zakres unikalności | Produkt unikalny globalnie? |
---|---|---|
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 globalnie |
Identyfikator kryterium grupy reklam | Grupa reklam | Nie, ale para (AdGroupId , CriterionId ) jest unikalna globalnie |
Identyfikator kryterium Campaignkryterium | Kampania | Nie, ale para (CampaignId , CriterionId ) jest unikalna globalnie |
Rozszerzenia reklam | Kampania | Nie, ale para (CampaignId , AdExtensionId ) jest unikalna globalnie |
Identyfikator kanału RSS | Cały świat | Tak |
Identyfikator elementu kanału RSS | Cały świat | Tak |
Identyfikator atrybutu kanału | 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 |
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.