Zaawansowane usługi Google

Zaawansowane usługi w Apps Script umożliwiają doświadczonym programistom łączenie się z niektórymi publicznymi interfejsami API Google bez konieczności ich konfigurowania niż przy użyciu interfejsów HTTP. Usługi zaawansowane to zasadniczo „cienkie opakowania” tych interfejsów API Google. Działają one podobnie jak usługi wbudowane w Apps Script – na przykład oferują autouzupełnianie, a Apps Script automatycznie obsługuje proces autoryzacji. Musisz jednak włączyć usługę zaawansowaną, zanim użyjesz jej w skrypcie.

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 skorzystać z interfejsu API Google, który nie jest dostępny jako usługa zaawansowana, po prostu 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 po prostu wysyłając żądania do interfejsu API bezpośrednio w UrlFetch.

Jeśli korzystasz z zaawansowanej metody usługi, Apps Script obsługuje proces autoryzacji i oferuje obsługę autouzupełniania. Aby jednak móc korzystać z tej usługi, musisz ją włączyć. Poza tym niektóre usługi zaawansowane oferują tylko część funkcji dostępnych w interfejsie API.

Jeśli używasz metody UrlFetch, aby bezpośrednio uzyskać dostęp do interfejsu API, traktujesz go jako zewnętrzny interfejs API. Ta metoda umożliwia korzystanie ze wszystkich aspektów interfejsu API. Wymaga to jednak samodzielnego wykonania autoryzacji interfejsu API. Musisz też utworzyć potrzebne nagłówki i przeanalizować odpowiedzi interfejsu API.

Ogólnie rzecz biorąc, najłatwiej jest korzystać z usługi zaawansowanej, gdy tylko jest to możliwe. Z metody UrlFetch należy korzystać tylko wtedy, gdy usługa zaawansowana nie obejmuje funkcji, których potrzebujesz.

Wymagania

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

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

  2. Musisz sprawdzić, czy 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 pojawić się prośba o zaakceptowanie Warunków korzystania z usług 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 odpowiedniej usługi zaawansowanej w projekcie GCP. Aby wprowadzić tę zmianę, musisz mieć uprawnienia do edycji projektu GCP.

Więcej informacji znajdziesz na stronie o projektach Cloud Platform.

Włącz usługi zaawansowane

Aby skorzystać 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 na potrzeby użycia w języku Apps Script. Funkcja autouzupełniania w edytorze skryptów zwykle zapewnia wystarczającą ilość informacji, aby rozpocząć, ale reguły poniżej wyjaśniają, jak 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żek, parametry zapytań, treść żądania i/lub załączniki do przesłanych plików multimedialnych. Niektóre usługi zaawansowane mogą też akceptować określone nagłówki żądań HTTP (np. zaawansowana usługa Kalendarz).

Odpowiedni podpis metody w skrypcie Google Apps Script ma te argumenty:

  1. Treść żądania (zwykle zasób) w postaci obiektu JavaScript.
  2. Ścieżka lub wymagane parametry jako poszczególne argumenty.
  3. Załącznik do przesłania pliku multimedialnego jako argument Blob.
  4. Parametry opcjonalne, używane jako nazwy parametrów mapowania 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ć obiekt JavaScript parametrów opcjonalnych (jeśli nie używasz parametrów opcjonalnych, na pusty obiekt).

Pomoc dotycząca usług zaawansowanych

Usługi zaawansowane to cienkie kody umożliwiające korzystanie z interfejsów API Google w obrębie Apps Script. W związku z tym każdy problem, który występuje podczas ich używania, jest zwykle związany 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ącej odpowiedniego interfejsu API. Linki do tych instrukcji pomocy można znaleźć w każdym zaawansowanym przewodniku po usłudze w sekcji Dokumentacja Apps Script.