Zaawansowane usługi Google

Zaawansowane usługi w Apps Script umożliwiają doświadczonym deweloperom nawiązywanie połączeń z określonymi publicznymi interfejsami API Google z mniejszymi wymaganiami dotyczącymi konfiguracji niż w przypadku korzystania z ich interfejsów HTTP. Usługi zaawansowane to w podstawie cienka powłoka otaczająca te interfejsy API Google. Działa ona podobnie jak wbudowane usługi w Apps Script. Oferuje na przykład autouzupełnianie, a Apps Script automatycznie obsługuje przepływ autoryzacji. Zanim jednak użyjesz usługi zaawansowanej, musisz ją włączyć.

Aby sprawdzić, które interfejsy API Google są dostępne jako usługi zaawansowane, przejdź do sekcji Usługi zaawansowane Google w dokumentacji. Jeśli chcesz używać interfejsu API Google, który nie jest dostępny jako usługa zaawansowana, po prostu połącz się z nim jak z dowolnym 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ą zaawansowanych usług lub wysyłając żądania interfejsu API bezpośrednio za pomocą UrlFetch.

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

Jeśli używasz metody UrlFetch, aby uzyskać bezpośredni dostęp do interfejsu API, w podstawie traktujesz interfejs Google API jako zewnętrzny interfejs API. W ramach tej metody można korzystać ze wszystkich aspektów interfejsu API. Wymaga to jednak samodzielnego zarządzania autoryzacją interfejsu API. Musisz też utworzyć wszystkie niezbędne nagłówki i przeanalizować odpowiedzi interfejsu API.

Zazwyczaj najłatwiej jest korzystać z usługi zaawansowanej, a metodę UrlFetch stosować tylko wtedy, gdy usługa zaawansowana nie zapewnia wymaganej funkcjonalności.

Wymagania

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

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

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

    Jeśli 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 zaawansowanej usługi i zapisaniu projektu skryptu. Jeśli jeszcze tego nie zrobiono, możesz też zostać poproszony(-a) o zaakceptowanie Warunków korzystania z usług Google Cloud i interfejsów Google API.

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

Więcej informacji znajdziesz w artykule 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 opcji 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.

Jak określane są sygnatury metod

Zaawansowane usługi korzystają z tych samych obiektów, nazw metod i parametrów co odpowiadające im publiczne interfejsy API, ale sygnatury metod są przekształcane na potrzeby Apps Script. Funkcja autouzupełniania w edytorze skryptu zwykle zawiera wystarczającą ilość informacji, aby można było zacząć, ale podane niżej reguły opisują, jak Apps Script generuje sygnaturę metody z publicznego interfejsu Google API.

Żądania 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 usługa zaawansowana Kalendarz).

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 osobne argumenty.
  3. Załącznik przesyłanych multimediów jako argument Blob.
  4. Parametry opcjonalne jako obiekt JavaScriptu mapujący nazwy parametrów na wartości.
  5. Nagłówki żądań HTTP jako obiekt JavaScriptu mapujący nazwy nagłówków na wartości nagłówków.

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

Pamiętaj o tych wyjątkach:

  • 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 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, a Ty ustawisz obiekt JavaScript nagłówków żądań, musisz też ustawić obiekt JavaScript parametrów opcjonalnych (na pusty obiekt, jeśli nie używasz parametrów opcjonalnych).

Obsługa zaawansowanych usług

Usługi zaawansowane to tylko cienkie obudowy, które umożliwiają korzystanie z interfejsów API Google w ramach Apps Script. Dlatego wszelkie problemy występujące podczas ich używania są zwykle związane 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ć, korzystając z instrukcji pomocy dotyczących odpowiedniego interfejsu API. Linki do tych instrukcji znajdziesz w pomocy do poszczególnych zaawansowanych usług w sekcji Przewodnik dotyczącej Apps Script.