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 istocie cienkie obudowy dla tych interfejsów API Google. Działają one podobnie do wbudowanych usług Apps Script, np. oferują autouzupełnianie, a Apps Script automatycznie obsługuje proces 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. Dzięki tej metodzie 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łnić te wymagania:

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

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

    Jeśli projekt skryptu korzysta z domyślnego projektu GCP utworzonego 8 kwietnia 2019 r. lub później, interfejs API jest włączany 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 ze standardowego projektu GCP lub starszego projektu domyślnego 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 artykule Projekty Cloud Platform.

Włączanie usług zaawansowanych

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 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 metod i parametrów co odpowiednie publiczne interfejsy API, ale podpisy metod są przetłumaczone 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 do przesyłania 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 napotkane podczas ich używania są zwykle związane z bazowym interfejsem API, a nie z samym skryptem 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 Informacje referencyjne dotyczące Apps Script.