Zaawansowane usługi Google

Zaawansowane usługi w Apps Script umożliwiają doświadczonym programistom łączenie się z określonymi publicznymi interfejsami API Google przy mniej skomplikowanych konfiguracjach niż korzystanie z ich interfejsów HTTP. Usługi zaawansowane to tak naprawdę cienkie otoczenie tych interfejsów API Google. Działają one podobnie do usług wbudowanych w Apps Script – oferują na przykład autouzupełnianie, a Apps Script obsługuje proces autoryzacji automatycznie. Jednak zanim użyjesz usługi w skrypcie, musisz włączyć ją.

Aby sprawdzić, które interfejsy API Google są dostępne jako usługi zaawansowane, zapoznaj się z sekcją Zaawansowane usługi Google w dokumentacji. Jeśli chcesz korzystać z 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 z zaawansowanych usług 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 bezpośrednio przez UrlFetch.

Jeśli używasz usługi zaawansowanej, Apps Script obsługuje proces autoryzacji i oferuje pomoc dotyczącą autouzupełniania. Aby z niej korzystać, musisz jednak włączyć usługę zaawansowaną. Poza tym niektóre usługi zaawansowane oferują tylko część funkcji dostępnych w interfejsie API.

Jeśli używasz metody UrlFetch, aby uzyskać bezpośredni dostęp do interfejsu API, zasadniczo interfejs Google API jest traktowany jako zewnętrzny interfejs API. Umożliwia ona wykorzystanie wszystkich aspektów API. Wymaga jednak samodzielnej obsługi autoryzacji interfejsu API. Musisz też utworzyć niezbędne nagłówki i przeanalizować odpowiedzi interfejsu API.

Ogólnie rzecz biorąc, w miarę możliwości najprościej jest korzystać z usługi zaawansowanej, a metody UrlFetch używaj tylko wtedy, gdy usługa zaawansowana nie zapewnia potrzebnych funkcji.

Wymagania

Zanim zaczniesz 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 w projekcie Cloud Platform (GCP) używany przez skrypt jest włączony interfejs API odpowiadający usłudze zaawansowanej.

    Jeśli projekt skryptu używa 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. Może też pojawić się prośba o zaakceptowanie warunków korzystania z Google Cloud i interfejsów API Google.

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

Więcej informacji znajdziesz w sekcji Projekty Cloud Platform.

Włącz usługi zaawansowane

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 opcji Usługi kliknij Dodaj usługę .
  4. Wybierz zaawansowaną usługę Google i kliknij Dodaj.

Gdy włączysz usługę zaawansowaną, będzie ona dostępna w autouzupełnianiu.

Sposób określania podpisów metod

Usługi zaawansowane korzystają zwykle z tych samych obiektów, nazw i parametrów co odpowiednie publiczne interfejsy API, ale podpisy metod są tłumaczone do użytku w Apps Script. Funkcja autouzupełniania w edytorze skryptów zwykle dostarcza wystarczającą ilość informacji, aby rozpocząć pracę, ale poniższe reguły wyjaśniają, w jaki sposób Apps Script generuje podpis metody z publicznego interfejsu API Google.

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

Odpowiedni podpis metody w skrypcie Google Apps Script ma następujące argumenty:

  1. Treść żądania (zwykle zasób) jako obiekt JavaScript.
  2. Ścieżka lub wymagane parametry jako poszczególne argumenty.
  3. Załącznik do przesłania multimediów jako argument Blob.
  4. Parametry opcjonalne, służące do mapowania nazw parametrów obiektów JavaScript na wartości.
  5. nagłówki żądań HTTP, czyli mapowanie nazw nagłówków na wartości nagłówków obiektów JavaScript;

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

Istnieją pewne wyjątki, o których warto pamiętać:

  • W przypadku metod, które akceptują przesyłanie multimediów, parametr uploadType jest ustawiany automatycznie.
  • Metody o nazwie delete w interfejsie Google API noszą w języku Apps Script nazwę remove, ponieważ delete to słowo zarezerwowane w języku JavaScript.
  • Jeśli usługa zaawansowana jest skonfigurowana tak, aby akceptować nagłówki żądań HTTP, i ustawisz obiekt JavaScript nagłówków żądań, musisz też ustawić opcjonalne parametry obiekt JavaScript (jeśli nie używasz parametrów opcjonalnych, na pusty obiekt).

Pomoc dotycząca usług zaawansowanych

Usługi zaawansowane to po prostu cienkie kody, które umożliwiają korzystanie z interfejsów API Google w obrębie Apps Script. W związku z tym wszelkie problemy związane z korzystaniem z nich są zwykle związane z interfejsem API, a nie z samym Apps Script.

Jeśli podczas korzystania z usługi zaawansowanej napotkasz problem, zgłoś go, korzystając z instrukcji pomocy dotyczących odpowiedniego interfejsu API. Linki do tych instrukcji znajdziesz w każdym zaawansowanym przewodniku po usłudze w sekcji Dokumentacja Apps Script.