Sprawdzone metody

Na tej stronie opisujemy różne sprawdzone metody, które należy wziąć pod uwagę podczas tworzenia aplikacji przy użyciu interfejsu API Google Ad Managera.

Ponowne wykorzystywanie klientów/skróconych usług podczas wykonywania

Utworzenie nowego klienta lub nowego kodu usługi wiąże się z niewielkim kosztem związanym z pobieraniem WSDL i przydzielaniem zasobów. Jeśli to możliwe, utwórz klienta lub fragment usługi na początku wykonywania jeden raz i udostępnij go klasom i funkcjom w razie potrzeby.

Użyj stronicowania podczas pobierania obiektów

Wszystkie usługi obsługują metodę get*ByStatement(), która umożliwia filtrowanie wyników za pomocą składni PQL. Klauzule LIMIT i OFFSET można używać do dzielenia dużych zestawów wyników na strony, co pozwala uniknąć przekroczenia czasu i zachować rozsądny rozmiar strony odpowiedzi. Sugerowany rozmiar strony to 200–500 znaków w zależności od złożoności obiektów.

Zbiorcze żądania aktualizacji

Zmieniając wiele obiektów tego samego typu, możesz poprawić wydajność, wysyłając wszystkie obiekty w tym samym żądaniu update*(). Każde żądanie po stronie klienta i serwera jest minimalne, a grupowanie żądań może być skutecznym sposobem zmniejszenia ich liczby. Możesz np. użyć funkcji updateOrders, aby zaktualizować grupę zamówień zamiast jednego zamówienia w każdym wywołaniu.

Użyj parametrów powiązania w PQL

Parametry powiązań umożliwiają umieszczanie zmiennych w instrukcji zapytania PQL. PQL odnosi się do zmiennej powiązania za pomocą nazwy bez spacji rozpoczynających się dwukropkiem, np. :name. Przykładowy kod znajdziesz na stronie składni PQL.

Zalecamy korzystanie ze zmiennych powiązań, ponieważ poprawiają one czytelność kodu przez eliminowanie konieczności łączenia ciągów i zmiennych w instrukcję zapytania. Ułatwiają też ponowne używanie instrukcji PQL, ponieważ nowe zapytania można tworzyć przez podstawianie wartości parametrów powiązania.

Nie nadużywaj uprawnień użytkowników

Gdy używasz usługi UserService do tworzenia lub aktualizowania ról użytkowników, pamiętaj, aby nie przyznawać użytkownikom uprawnień, których nie potrzebują. Wiele funkcji interfejsu API jest dostępnych dzięki kombinacji ról zamiast przypisywania użytkownikowi roli administratora. Zanim zdecydujesz, które role przypisać użytkownikowi, zapoznaj się z dokumentacją uprawnień. Poza tym, jeśli jesteś deweloperem aplikacji zewnętrznej, zastanów się, jaki poziom dostępu potrzebuje Twoja aplikacja, gdy prosisz sieć o utworzenie użytkownika. Rola z mniejszymi uprawnieniami niż administrator może wystarczyć.

Nie przekraczaj limitów

Aby zachować niezawodność, interfejs API Ad Managera narzuca kilka limitów. Ważne jest, aby utrzymywać aplikacje poniżej tych limitów oraz wiedzieć, jak reagować na błędy limitów, które interfejs API może zwrócić.

Limit interfejsu API

Pierwszy limit stosowany do żądań do interfejsu API jest limitem na poziomie sieci. W przypadku kont Ad Managera 360 limit wynosi 8 żądań na sekundę, a w przypadku kont Ad Managera – 2 żądania na sekundę. Przekroczenie tego limitu spowoduje wystąpienie błędu QuotaError.EXCEEDED_QUOTA. Do tego limitu mają zastosowanie wszystkie żądania do interfejsu API wysyłane w Twojej sieci. Dotyczy to także aplikacji innych firm, którym przyznałeś(-aś) dostęp do interfejsu API Twojej sieci przez Ciebie lub kogoś z Twojej firmy.

Limity systemowe

Sam limit interfejsu API nie wystarcza do ochrony niektórych systemów zużywających dużo zasobów w usłudze Ad Manager. Systemy raportowania i prognozowania definiują własne limity, które mogą powodować błędy interfejsu API: odpowiednio QuotaError.REPORT_JOB_LIMIT i ForecastError.EXCEEDED_QUOTA.

Obsługa błędów limitu

Jeśli aplikacja napotka jeden z powyższych błędów limitu, zastosuj strategię ponawiania żądań do interfejsu API. Zalecamy odczekanie co najmniej 5 sekund, a jeśli błąd będzie się powtarzał, użyj wykładniczego ponowienia, aby wydłużyć czas między kolejnymi próbami. Jeśli ponowna próba się nie powiedzie, skontroluj aplikacje interfejsu API, aby sprawdzić, czy użytkownicy w sieci nie zużywają limitu.