Zaawansowane usługi Google

Zaawansowane usługi Apps Script umożliwiają doświadczonym programistom łączenie się z określonymi publicznymi interfejsami API Google w mniej skomplikowany sposób niż przy użyciu interfejsów HTTP. Usługi zaawansowane to w zasadzie cienkie otoczenie obejmujące te interfejsy API Google. Działają one podobnie do wbudowanych usług Apps Script, np. oferują autouzupełnianie, a Apps Script automatycznie obsługuje proces autoryzacji. Musisz jednak włączyć usługę zaawansowaną, by móc jej używać w skrypcie.

Aby sprawdzić, które interfejsy API Google są dostępne jako usługi zaawansowane, zajrzyj do sekcji Zaawansowane usługi Google w materiałach referencyjnych. Jeśli chcesz użyć interfejsu API Google, który nie jest dostępny jako usługa zaawansowana, 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, korzystając z usług zaawansowanych lub po prostu wykonując żądania do interfejsu API bezpośrednio za pomocą UrlFetch.

W przypadku korzystania z metody usługi zaawansowanej Apps Script obsługuje proces autoryzacji i oferuje pomoc w zakresie autouzupełniania. Aby z niej korzystać, musisz jednak włączyć usługę zaawansowaną. Oprócz tego niektóre usługi zaawansowane obejmują tylko część funkcji dostępnych w interfejsie API.

Jeśli używasz metody UrlFetch, aby bezpośrednio uzyskiwać dostęp do interfejsu API, musisz w zasadzie traktować ten interfejs API jako zewnętrzny interfejs API. Dzięki tej metodzie można korzystać ze wszystkich aspektów interfejsu API. Wymaga to jednak samodzielnego przeprowadzenia autoryzacji interfejsu API. Musisz też utworzyć potrzebne nagłówki i przeanalizować odpowiedzi interfejsu API.

Ogólnie najłatwiej jest korzystać z usług zaawansowanych, gdy jest to możliwe, i metody UrlFetch używać tylko wtedy, gdy usługa zaawansowana nie zapewnia potrzebnych funkcji.

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 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 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. Możemy również poprosić Cię 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 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 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.

Gdy włączysz usługę zaawansowaną, jest 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. Dostępna w edytorze skryptów funkcja autouzupełniania zwykle zapewnia wystarczającą ilość informacji na początek, 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ą przyjmować różne rodzaje danych, w tym parametry ścieżek, 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 zaawansowana usługa Kalendarz).

Odpowiednie argumenty metody w Google Apps Script zawierają te argumenty:

  1. Treść żądania (zwykle zasób) jako obiekt JavaScriptu.
  2. Ścieżka lub wymagane parametry jako pojedyncze argumenty.
  3. Załącznik do przesyłania multimediów jako argument Blob.
  4. Parametry opcjonalne jako nazwy parametrów mapowania obiektów JavaScript na wartości.
  5. Nagłówki żądań HTTP jako nazwy nagłówków mapowanych obiektów JavaScript 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 o nazwie delete w interfejsie API Google mają w Apps Script nazwę remove, ponieważ delete jest słowem zarezerwowanym w języku JavaScript.
  • Jeśli usługa zaawansowana jest skonfigurowana tak, aby akceptowała nagłówki żądań HTTP, i ustawisz obiekt JavaScript z nagłówkami żądań, musisz też ustawić obiekt JavaScript parametrów opcjonalnych (na pusty obiekt, jeśli nie używasz parametrów opcjonalnych).

Pomoc do usług zaawansowanych

Usługi zaawansowane to cienkie opakowania, które umożliwiają korzystanie z interfejsów API Google w Apps Script. W związku z tym wszelkie problemy napotkane podczas korzystania z nich są zwykle związane z interfejsem API, a nie z interfejsem Apps Script.

Jeśli napotkasz problem podczas korzystania z usługi zaawansowanej, musisz go zgłosić, postępując zgodnie z instrukcjami pomocy dla bazowego interfejsu API. Linki do tych instrukcji znajdziesz w każdym zaawansowanym przewodniku po usłudze w sekcji Informacje o Apps Script.