Zaawansowane usługi Google

Usługi zaawansowane w Apps Script umożliwiają doświadczonym programistom łączenie się z niektórymi publicznymi interfejsami API Google przy mniejszej liczbie czynności konfiguracyjnych niż w przypadku korzystania z interfejsów HTTP. Usługi zaawansowane to w zasadzie cienkie otoki otaczające te interfejsy API Google. Działają one podobnie jak wbudowane usługi Apps Script – na przykład oferują autouzupełnianie, a Apps Script automatycznie obsługuje proces autoryzacji. Aby jednak używać usługi zaawansowanej w skrypcie, musisz ją najpierw włączyć.

Aby sprawdzić, które interfejsy API Google są dostępne jako usługi zaawansowane, poszukaj sekcji Usługi zaawansowane Google w dokumentacji. Jeśli chcesz użyć interfejsu API Google, który nie jest dostępny jako usługa zaawansowana, połącz się z nim tak jak z każdym innym zewnętrznym interfejsem API.

Usługi zaawansowane czy HTTP?

Każda zaawansowana usługa Google jest powiązana z publicznym interfejsem API Google. W Apps Script możesz uzyskać dostęp do tych interfejsów API za pomocą usług zaawansowanych lub po prostu wysyłając żądania API bezpośrednio za pomocą UrlFetch.

Jeśli używasz metody zaawansowanej usługi, Apps Script obsługuje proces autoryzacji i oferuje obsługę autouzupełniania. Aby z niej korzystać, musisz jednak włączyć usługę zaawansowaną. Niektóre usługi zaawansowane udostępniają tylko podzbiór funkcji dostępnych w interfejsie API.

Jeśli do bezpośredniego dostępu do interfejsu API używasz metody UrlFetch, traktujesz interfejs API Google jako zewnętrzny interfejs API. Ta metoda umożliwia korzystanie ze wszystkich aspektów interfejsu API. Wymaga to jednak samodzielnego zarządzania autoryzacją interfejsu API. Musisz też utworzyć wszystkie potrzebne nagłówki i przeanalizować odpowiedzi interfejsu API.

Zwykle najłatwiej jest używać usług zaawansowanych, a metody UrlFetch używać tylko wtedy, gdy usługa zaawansowana nie zapewnia potrzebnej funkcjonalności.

Wymagania

Aby korzystać z usługi zaawansowanej, musisz spełnić te wymagania:

  1. Musisz włączyć usługę zaawansowaną w projekcie skryptu.

  2. Musisz się upewnić, że interfejs API odpowiadający usłudze zaawansowanej jest włączony w projekcie Cloud Platform (GCP), którego używa Twój skrypt.

    Jeśli Twój projekt skryptu korzysta z domyślnego projektu GCP utworzonego 8 kwietnia 2019 r. lub później, interfejs API zostanie włączony automatycznie po włączeniu usługi zaawansowanej i zapisaniu projektu skryptu. Jeśli nie zostało to jeszcze zrobione, możesz też zostać poproszony(-a) o zaakceptowanie Warunków korzystania z usług Google Cloud i interfejsów API Google.

    Jeśli projekt skryptu korzysta ze standardowego projektu GCP lub starszego domyślnego projektu GCP, musisz ręcznie włączyć w projekcie GCP odpowiedni interfejs API usługi. Aby wprowadzić tę zmianę, musisz mieć uprawnienia do edycji projektu GCP.

Więcej informacji znajdziesz w sekcji Projekty Cloud Platform.

Włączanie usług zaawansowanych

Aby korzystać z zaawansowanej usługi Google, wykonaj te czynności:

  1. Otwórz projekt Apps Script.
  2. Po lewej stronie kliknij Edytor .
  3. Po lewej stronie obok pozycji Usługi kliknij Dodaj usługę .
  4. Wybierz zaawansowaną usługę Google i kliknij Dodaj.

Po włączeniu usługi zaawansowanej będzie ona dostępna w autouzupełnianiu.

Sposób określania sygnatur metod

Usługi zaawansowane zwykle używają tych samych obiektów, nazw metod i parametrów co odpowiednie publiczne interfejsy API, chociaż sygnatury metod są tłumaczone na potrzeby Apps Script. Funkcja autouzupełniania w edytorze skryptów zwykle zawiera wystarczająco dużo informacji, aby można było zacząć pracę, ale poniższe reguły wyjaśniają, jak Apps Script generuje sygnaturę metody z publicznego interfejsu API Google.

Żądania do interfejsów API Google mogą akceptować różne typy danych, w tym parametry ścieżki, parametry zapytania, treść żądania lub załącznik przesyłania multimediów. Niektóre usługi zaawansowane mogą też akceptować określone nagłówki żądań HTTP (np. usługa zaawansowana Kalendarza).

Odpowiednia sygnatura metody w Google Apps Script ma te argumenty:

  1. Treść żądania (zwykle zasób) jako obiekt JavaScript.
  2. ścieżkę lub wymagane parametry jako poszczególne argumenty;
  3. Załącznik przesyłania multimediów jako argument Blob.
  4. Parametry opcjonalne w formie obiektu JavaScriptu, który mapuje nazwy parametrów na wartości.
  5. Nagłówki żądań HTTP jako obiekt JavaScriptu, który mapuje nazwy nagłówków na ich wartości.

Jeśli metoda nie zawiera żadnych elementów w danej kategorii, ta część podpisu jest pomijana.

Istnieją jednak pewne wyjątki:

  • W przypadku metod, które akceptują przesyłanie multimediów, parametr uploadType jest ustawiany automatycznie.
  • Metody o nazwie delete w interfejsie Google API mają w Apps Scripcie nazwę remove, ponieważ delete jest słowem zastrzeżonym w JavaScript.
  • Jeśli usługa zaawansowana jest skonfigurowana tak, aby akceptować nagłówki żądań HTTP, a Ty ustawisz obiekt JavaScript nagłówków żądań, musisz też ustawić opcjonalny obiekt JavaScript parametrów (na pusty obiekt, jeśli nie używasz parametrów opcjonalnych).

Obsługa usług zaawansowanych

Usługi zaawansowane to tylko cienkie otoki, które umożliwiają korzystanie z interfejsów API Google w Apps Script. Dlatego każdy problem napotkany podczas korzystania z nich jest zwykle związany z interfejsem API, a nie z samym Apps Script.

Jeśli podczas korzystania z usługi zaawansowanej wystąpi problem, należy go zgłosić, postępując zgodnie z instrukcjami pomocy dotyczącymi interfejsu API, na którym opiera się usługa. Linki do tych instrukcji pomocy znajdziesz w każdym przewodniku po usługach zaawansowanych w sekcji Dokumentacja Apps Script.