Zaawansowane usługi Google

Zaawansowane usługi Apps Script pozwalają doświadczonym programistom na łączenie się z niektórymi publicznymi interfejsami API Google przy mniejszej liczbie konfiguracji niż przy użyciu interfejsów HTTP. Usługi zaawansowane to w zasadzie ciasne kody otaczające te interfejsy API Google. Działają one podobnie jak wbudowane usługi Apps Script – na przykład umożliwiają autouzupełnianie, które automatycznie obsługuje proces autoryzacji. Musisz jednak włączyć usługę zaawansowaną, zanim będzie można używać jej w skrypcie.

Aby dowiedzieć się, 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 Google API, który nie jest dostępny jako usługa zaawansowana, połącz się z nim jak każdy inny zewnętrzny interfejs 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 za pomocą UrlFetch.

Jeśli korzystasz z zaawansowanej metody usługi, Apps Script obsługuje proces autoryzacji i oferuje pomoc w zakresie autouzupełniania. Musisz jednak włączyć usługę zaawansowaną, aby móc z niej korzystać. Ponadto niektóre usługi zaawansowane zapewniają tylko część funkcji dostępnych w interfejsie API.

Jeśli użyjesz metody UrlFetch, aby uzyskać bezpośredni dostęp do interfejsu API, będziesz traktować API Google jako zewnętrzny interfejs API. Dzięki tej metodzie można stosować wszystkie aspekty interfejsu API. Wymaga to jednak samodzielnego zarządzania autoryzacją interfejsu API. Musisz też utworzyć potrzebne nagłówki i przeanalizować odpowiedzi interfejsu API.

Zwykle najprościej jest korzystać z usługi zaawansowanej i korzystać z metody UrlFetch tylko wtedy, gdy usługa zaawansowana nie zapewnia funkcji, których potrzebujesz.

Wymagania

Aby móc korzystać z usługi zaawansowanej, musisz spełniać 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 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żesz też otrzymać prośbę o zaakceptowanie warunków korzystania z Google Cloud i interfejsów API Google, jeśli jeszcze ich nie masz.

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

Więcej informacji znajdziesz na stronie Projekty Cloud Platform.

Włącz usługi zaawansowane

Aby użyć zaawansowanej usługi Google, postępuj zgodnie z tymi instrukcjami:

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

Będzie ona dostępna w autouzupełnianiu po włączeniu usługi zaawansowanej.

Sposób określania podpisów metod

Usługi zaawansowane zazwyczaj używają tych samych obiektów, nazw metod i parametrów co odpowiednie publiczne interfejsy API, ale podpisy metod są tłumaczone na potrzeby Apps Script. Funkcja autouzupełniania edytora skryptów zawiera zwykle wystarczającą ilość informacji na początek, ale reguły poniżej wyjaśniają, w jaki sposób Apps Script generuje podpis 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 i załącznik do przesyłania multimediów. Niektóre usługi zaawansowane mogą też akceptować określone nagłówki żądań HTTP (na przykład usługa zaawansowana Kalendarza).

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

  1. Treść żądania (zwykle zasób) jako obiekt JavaScript.
  2. Ścieżka lub wymagane parametry jako argumenty.
  3. Załącznik do przesyłania multimediów jako argument Blob.
  4. Parametry opcjonalne, które stanowią nazwy parametrów mapowania obiektów JavaScript na wartości.
  5. Nagłówki żądania HTTP jako nazwy nagłówków obiektów JavaScript mapowane na wartości nagłówków.

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

Istnieją pewne wyjątki, o których należy pamiętać:

  • W przypadku metod, które akceptują przesyłanie multimediów, parametr uploadType jest ustawiany automatycznie.
  • Metody delete nazywane w interfejsie API Google mają nazwę remove w Apps Script, ponieważ delete jest zarezerwowanym słowem w języku JavaScript.
  • Jeśli usługa zaawansowana jest skonfigurowana tak, aby przyjmować nagłówki żądań HTTP i masz ustawiony obiekt JavaScript nagłówków żądań, musisz też ustawić opcjonalny parametr JavaScript (pusty obiekt, jeśli nie używasz parametrów opcjonalnych).

Pomoc dla usług zaawansowanych

Usługi zaawansowane to cienkie kody, 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 skryptem Apps Script.

Jeśli podczas korzystania z usługi zaawansowanej wystąpią problemy, należy je zgłosić, korzystając z instrukcji pomocy dotyczących używanego interfejsu API. Linki do tych instrukcji znajdziesz w każdym przewodniku dotyczącym usług zaawansowanych w sekcji Dokumentacja Apps Script.