Zaawansowane usługi Google

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Zaawansowane usługi w języku Apps Script umożliwiają doświadczonym deweloperom łączenie się z określonymi publicznymi interfejsami API Google przy użyciu mniej konfiguracji niż interfejsów API. Usługi zaawansowane to zasadniczo cienkie otoki tych interfejsów API Google. Działają one podobnie jak wbudowane usługi Apps Script, oferują na przykład autouzupełnianie, a Apps Script automatycznie obsługuje proces autoryzacji. Musisz jednak włączyć usługę zaawansowaną, aby używać 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 użyć interfejsu Google API, który nie jest dostępny jako usługa zaawansowana, połącz się z nim jak ze wszystkimi zewnętrznymi interfejsami 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 zapewnia obsługę autouzupełniania. Musisz jednak włączyć usługę zaawansowaną, aby z niej korzystać. Ponadto 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, musisz traktować interfejs Google API jako zewnętrzny interfejs API. Dzięki tej metodzie można wykorzystać wszystkie aspekty interfejsu API. Wymaga to jednak samodzielnego obsługi autoryzacji interfejsu API. Musisz też utworzyć potrzebne nagłówki i przeanalizować odpowiedzi interfejsu API.

Z reguły najłatwiej jest korzystać z usługi zaawansowanej tam, gdzie to możliwe i używać metody UrlFetch tylko wtedy, gdy usługa zaawansowana nie udostępnia potrzebnych funkcji.

Wymagania

Przed skorzystaniem z usługi zaawansowanej musisz spełnić te wymagania:

  1. Musisz włączyć usługę zaawansowaną w projekcie skryptu.
  2. Musisz upewnić się, że interfejs API odpowiadający usłudze zaawansowanej jest włączony w projekcie Cloud Platform (GCP) używanym przez 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, musisz też zaakceptować Warunki korzystania z Google Cloud Platform 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 w GCP. Aby wprowadzić tę zmianę, musisz mieć uprawnienia do edycji projektu GCP.

Więcej informacji znajdziesz w artykule o projektach Cloud Platform.

Włącz usługi zaawansowane

Aby użyć 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.

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

Jak określane są podpisy metod

Usługi zaawansowane zwykle używają tych samych obiektów, nazw metod 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 zawiera wystarczającą ilość informacji, ale poniższe reguły wyjaśniają, jak 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 lub załącznik do przesyłania multimediów. Niektóre usługi zaawansowane mogą akceptować określone nagłówki żądań HTTP (na przykład usługa zaawansowana Kalendarza).

Odpowiedni podpis metody w Google Apps Script zawiera te argumenty:

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

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

Oto kilka wyjątków:

  • W przypadku metod, które akceptują przesyłanie multimediów, parametr uploadType jest ustawiany automatycznie.
  • Metody o nazwie delete w interfejsie API Google mają nazwę remove w Apps Script, ponieważ delete jest słowem zarezerwowanym w języku JavaScript.
  • Jeśli usługa zaawansowana jest skonfigurowana do akceptowania nagłówków HTTP, a ustawisz obiekt JavaScript nagłówków żądań, musisz też ustawić obiekt JavaScript parametrów opcjonalnych (lub 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ą używanie interfejsów API Google w Apps Script. Podczas korzystania z nich zwykle występuje problem z podstawowym interfejsem API, a nie z Apps Script.

Jeśli podczas korzystania z usługi zaawansowanej wystąpi problem, należy go zgłosić, korzystając z instrukcji dotyczących pomocy dla danego interfejsu API. Linki do tych instrukcji znajdziesz w każdym przewodniku po zaawansowanych usługach w sekcji Informacje o Apps Script.