Struktura interfejsu API

Film: zobacz prezentację na temat usług i zasobów z warsztatów w 2019 roku

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 encję 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.

Model kampanii

  • Zasobem najwyższego poziomu konta jest klient.

  • Każdy klient zawiera co najmniej jedną aktywną kampanię.

  • Każda kampania zawiera co najmniej 1 grupę reklam, która służy do grupowania reklam w logiczne zbiory.

  • Reklama z grupy reklam odpowiada obecnie wyświetlanej reklamie. Oprócz kampanii promujących aplikacje, które mogą zawierać tylko 1 reklamę z grupy reklam na grupę reklam, każda grupa reklam zawiera co najmniej 1 reklamę z grupy reklam.

Do grupy reklam lub kampanii możesz dołączyć 1 lub więcej elementów AdGroupCriterion lub CampaignCriterion. Reprezentują one kryteria wyświetlania reklam.

Istnieje wiele typów kryteriów, takich jak słowa kluczowe, przedziały wiekowe i lokalizacje. Kryteria zdefiniowane na poziomie kampanii wpływają na wszystkie pozostałe zasoby w tej kampanii. Możesz też określać budżety i daty w całej kampanii.

Możesz też dołączać rozszerzenia na poziomie konta, kampanii lub grupy reklam. Dzięki rozszerzeniom możesz umieścić w reklamach dodatkowe informacje, takie jak numer telefonu, adres czy informacje o promocjach.

Zasoby

Zasoby reprezentują elementy powiązane z Twoim kontem 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 nich są unikalne globalnie na wszystkich kontach Google Ads, a inne tylko w obrębie danego zakresu.

Identyfikator obiektu Zakres niepowtarzalności Niepowtarzalny na całym świecie?
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 CampaignCriterion Priorytet Nie, ale para (CampaignId, CriterionId) jest unikalna globalnie
Rozszerzenia reklam Priorytet 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 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 identyfikatora mogą być przydatne podczas projektowania pamięci lokalnej obiektów Google Ads.

Niektórych obiektów można używać z wieloma typami 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ć z poziomu pola AdGroupAd.ad.type i zwraca ona wartość w wyliczeniu 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żce. 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 pole resource_name będzie wyglądać tak:

customers/1234567/campaigns/987654

Usługi

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

Modyfikowanie (mutacje) 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:

Każde żądanie mutate musi zawierać odpowiednie obiekty operation. Na przykład metoda CampaignService.MutateCampaigns wymaga co najmniej 1 wystąpienia obiektu CampaignOperation. Szczegółowe omówienie operacji znajdziesz w artykule Zmienianie i sprawdzanie obiektów.

Równoczesne mutacje

Obiekt Google Ads nie może być modyfikowany równocześnie przez więcej niż jedno źródło. Mogą wystąpić błędy, jeśli wielu użytkowników aktualizuje ten sam obiekt w aplikacji lub gdy równocześnie mutujesz obiekty Google Ads przy użyciu wielu wątków. Obejmuje to aktualizowanie obiektu z poziomu 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 2 źródła spróbują jednocześnie wprowadzić mutacje w obiekcie, interfejs API zwróci DatabaseError.CONCURRENT_MODIFICATION_ERROR.

Mutacje asynchroniczne i synchroniczne

Metody przekształcania w interfejsie Google Ads API są synchroniczne. Wywołania interfejsu API zwracają odpowiedź dopiero po zmodyfikowaniu obiektów, co wymaga oczekiwania na odpowiedź na każde żądanie. Chociaż takie podejście jest stosunkowo łatwe do kodowania, może negatywnie wpłynąć na równoważenie obciążenia i marnotrawstwo zasobów, jeśli procesy będą musiały czekać na zakończenie wywołań.

Możesz też asynchronicznie mutować obiekty za pomocą narzędzia BatchJobService, które 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 im na wykonywanie innych operacji. Możesz okresowo sprawdzać stan zadania.

Więcej informacji o przetwarzaniu asynchronicznego znajdziesz w Przewodniku przetwarzania wsadowego.

Weryfikacja mutacji

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

Aby użyć tej funkcji, ustaw opcjonalne pole wartości logicznej validate_only żądania na true. Żądanie zostaje wtedy w pełni zweryfikowane, tak jakby miało zostać wykonane, ale ostateczne wykonanie jest pomijane. Jeśli nie zostaną znalezione żadne błędy, zwracana jest pusta odpowiedź. Jeśli weryfikacja się nie powiedzie, komunikaty o błędach w odpowiedzi będą wskazywać na te błędy.

Narzędzie validate_only jest szczególnie przydatne do testowania reklam pod kątem częstych naruszeń zasad. Reklamy naruszające zasady, np. zawierające określone słowa, znaki interpunkcyjne, wielkie litery lub długość, są automatycznie odrzucane. Pojedyncza nieprawidłowa reklama może spowodować błąd całej grupy. Testowanie nowej reklamy w ramach żądania validate_only może ujawnić wszelkie takie naruszenia. Aby zobaczyć, jak to działa, zapoznaj się z przykładowym kodem dotyczącym postępowania z błędami naruszenia zasad.

Otrzymuj statystyki dotyczące obiektów i wydajności

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

Wszystkie żądania Search i SearchStream dotyczące GoogleAdsService wymagają zapytania określającego zasób, do którego ma zostać wysłane zapytanie, atrybuty zasobu i wskaźniki wydajności do pobrania, predykaty używane do filtrowania żądania oraz segmenty używane do dalszej analizy statystyk wydajności. Więcej informacji o formacie zapytań 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 dostarcza informacji potrzebnych do utworzenia zapytania do GoogleAdsService. Dla wygody informacje zwracane przez metodę GoogleAdsFieldService są też dostępne w dokumentacji referencyjnej dotyczącej pól.

Wstecz
Przegląd
Dalej
Relacje z elementem