Struktura interfejsu API

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Film: Zapoznaj się z warsztatami z 2019 r. dotyczącymi usług i zasobów

W tym przewodniku znajdziesz podstawowe 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 podmiot Google Ads, a usługi pobierają dane i manipulują nimi.

Hierarchia obiektów

Konto Google Ads można wyświetlać jako hierarchię obiektów.

  • Zasóbem najwyższego poziomu konta jest klient.

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

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

  • Każda AdGroup zawiera co najmniej 1 reklamę z grupy reklam. AdGroupAd oznacza reklamę, którą wyświetlasz.

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

Jest 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 kampanii. Możesz też określić budżety i daty dla całej kampanii.

Na koniec możesz dodać rozszerzenia na poziomie konta, kampanii lub grupy reklam. Rozszerzenia pozwalają wyświetlać w reklamach dodatkowe informacje, np. numer telefonu, adres lub promocje.

Zasoby

Zasoby reprezentują podmioty 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 inne tylko w ograniczonym zakresie.

Identyfikator obiektu Zakres unikalności Na całym świecie?
Identyfikator budżetu Globalne Tak
Identyfikator kampanii Globalne Tak
Identyfikator grupy reklam Globalne Tak
Identyfikator reklamy Grupa reklam Nie, ale para (AdGroupId, AdId) jest globalnie unikalna
Identyfikator kryterium grupy reklam Grupa reklam Nie, ale para (AdGroupId, CriterionId) jest globalnie unikalna
Identyfikator kryterium kryterium Kampania Nie, ale para (CampaignId, CriterionId) jest globalnie unikalna
Rozszerzenia reklam Kampania Nie, ale para (CampaignId, AdExtensionId) jest globalnie unikalna
Identyfikator kanału RSS Globalne Tak
Identyfikator elementu kanału RSS Globalne Tak
Identyfikator atrybutu kanału Plik danych Nie
Identyfikator mapowania kanału Globalne Tak
Identyfikator etykiety Globalne Tak
Identyfikator na liście użytkowników Globalne Tak

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

Niektóre obiekty mogą być używane w przypadku wielu typów encji. W takich sytuacjach obiekt zawiera pole type, które opisuje jego zawartość. Na przykład AdGroupAd może odnosić się do reklamy tekstowej, reklamy hotelu, reklamy lokalnej itp. Ta wartość jest dostępna w polu AdGroupAd.ad.type i zwraca wartość wyliczoną w AdType.

Nazwy zasobów

Każdy zasób jest jednoznacznie oznaczony przez ciąg znaków 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 o identyfikatorze klienta 1234567 fragment resource_name będzie taki:

customers/1234567/campaigns/987654

Usługi

Usługi pozwalają pobierać i modyfikować encje Google Ads. Dostępne są 3 typy usług: modyfikowanie, pobieranie obiektów i statystyk oraz pobieranie metadanych.

Modyfikowanie (mutowanie) obiektów

Te usługi modyfikują instancje powiązanego typu zasobu za pomocą żądania mutate. Zawierają też żądanie get, które pobiera pojedynczą instancję zasobu, co może być przydatne do badania 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 Zmienianie i sprawdzanie obiektów.

Równoległe 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 aplikacji lub jeśli równocześnie zmieniasz obiekty Google Ads za pomocą wielu wątków. Obejmuje to aktualizowanie obiektu z wielu wątków w tej samej aplikacji lub z różnych aplikacji (np. aplikację i jednoczesną sesję interfejsu Google Ads).

Interfejs API nie umożliwia zablokowania obiektu przed aktualizacją. Jeśli 2 źródła próbują jednocześnie wprowadzić zmiany w obiekcie, interfejs API przesyła wartość DatabaseError.CONCURRENT_MODIFICATION_ERROR.

Mutacje synchroniczne i synchroniczne

Metody mutacji w interfejsie Google Ads API są synchroniczne. Wywołania interfejsu API zwracają odpowiedź dopiero po zmodyfikowaniu obiektów, przez co trzeba czekać na odpowiedź na każde żądanie. Takie podejście jest stosunkowo proste w kodowaniu, ale może negatywnie wpłynąć na równoważenie obciążenia i marnować zasoby, jeśli proces jest wymuszany na czekaniu na zakończenie wywołań.

Alternatywnym sposobem jest mutacja asynchroniczna za pomocą BatchJobService, która wykonuje partie operacji w wielu usługach bez oczekiwania na ich zakończenie. Po przesłaniu zadania wsadowego serwery interfejsów Google Ads API wykonują asynchronicznie operacje, dzięki czemu procesy mogą wykonywać inne operacje. Możesz okresowo sprawdzać stan zadania.

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

Zmiana weryfikacji

Większość żądań mutacji można zweryfikować bez wykonania wywołania w odniesieniu do prawdziwych danych. Możesz przetestować żądanie dotyczące brakujących parametrów i nieprawidłowych wartości pól bez wykonania operacji.

Aby użyć tej funkcji, ustaw opcjonalne pole wartości logicznej żądania validate_only na true. Żądanie zostanie wtedy w pełni zweryfikowane tak, jakby miało być 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łędach będą zawierać punkty niepowodzenia.

validate_only jest szczególnie przydatny do testowania reklam pod kątem częstych naruszeń zasad. Reklamy są automatycznie odrzucane, jeśli naruszają zasady, takie jak użycie określonych słów, znaków interpunkcyjnych, wielkich liter lub długości. Jedna zła reklama może spowodować awarię całej grupy. Testowanie nowej reklamy w żądaniu validate_only może wykryć takie naruszenia. Zobacz przykład kodu, aby dowiedzieć się, jak radzić sobie z naruszeniami zasad.

Pobieranie statystyk 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, atrybutów zasobów i wskaźników wydajności do pobrania, prognozujących zastosowanie filtra i segmentów używanych 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 lub jego typ danych.

Ta usługa zapewnia informacje, których potrzebujesz do tworzenia zapytań kierowanych do GoogleAdsService. Dla ułatwienia informacje zwracane przez GoogleAdsFieldService są też dostępne w dokumentacji referencyjnej pól.