Zaawansowane usługi Google

Usługi zaawansowane w Apps Script umożliwiają łączenie się z niektórymi publicznymi interfejsami API Google z mniejszymi wymaganiami dotyczącymi konfiguracji niż w przypadku korzystania z interfejsów HTTP. Usługi zaawansowane to cienkie otoki otaczające te interfejsy API Google. Działają one podobnie do wbudowanych usług Apps Script – na przykład oferują autouzupełnianie, a Apps Script automatycznie obsługuje proces autoryzacji. Zanim jednak użyjesz jej w skrypcie, musisz włączyć usługę zaawansowaną.

Włączanie usług zaawansowanych

Aby korzystać z zaawansowanej usługi Google, wykonaj te czynności:

Krok 1. Włącz usługę zaawansowaną

Usługę zaawansowaną możesz włączyć w edytorze Apps Script lub edytując plik manifestu.

Metoda A. Korzystanie z edytora

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

Metoda B. Używanie pliku manifestu

Usługi zaawansowane możesz włączyć, edytując plik manifestu. Aby na przykład włączyć usługę zaawansowaną Dysk Google, dodaj pole enabledAdvancedServices do obiektu dependencies:

{
  "timeZone": "America/Denver",
  "dependencies": {
    "enabledAdvancedServices": [
      {
        "userSymbol": "Drive",
        "version": "v3",
        "serviceId": "drive"
      }
    ]
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8"
}

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

Krok 2. Włącz interfejs Google Cloud API (tylko w przypadku standardowych projektów Google Cloud)

Jeśli używasz domyślnego projektu Google Cloud (utworzonego automatycznie przez Apps Script), możesz pominąć ten krok. Interfejs API jest włączany automatycznie po dodaniu usługi w kroku 1.

Jeśli używasz standardowego projektu Google Cloud, musisz też ręcznie włączyć interfejs API odpowiadający usłudze zaawansowanej. Aby ręcznie włączyć interfejs API:

  1. Otwórz projekt w Cloud powiązany ze skryptem w ** konsoli Google Cloud**.

  2. U góry konsoli kliknij pasek wyszukiwania i wpisz część nazwy interfejsu API (np. „Kalendarz”), a potem kliknij nazwę, gdy się pojawi.

  3. Kliknij Włącz API.

  4. Zamknij konsolę Google Cloud i wróć do edytora skryptów.

Sposób określania sygnatur metod

Usługi zaawansowane używają zwykle tych samych obiektów, nazw metod i parametrów co odpowiednie publiczne interfejsy API, chociaż sygnatury metod są tłumaczone na potrzeby Apps Script. Funkcja autouzupełniania w edytorze skryptów zwykle zawiera wystarczająco dużo informacji, aby rozpocząć pracę, ale poniższe reguły wyjaśniają, jak Apps Script generuje sygnaturę metody z publicznego interfejsu Google API.

Żądania do interfejsów API Google mogą akceptować różne typy danych, w tym parametry ścieżki, parametry zapytania, treść żądania lub załącznik przesyłania multimediów. Niektóre usługi zaawansowane mogą też akceptować określone nagłówki żądań HTTP (np. 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 poszczególne argumenty; Jeśli metoda wymaga wielu parametrów ścieżki, pojawiają się one w kolejności, w jakiej są wymienione w adresie URL punktu końcowego interfejsu API.
  3. Załącznik przesyłania multimediów jako argument Blob.
  4. Parametry opcjonalne (zwykle parametry zapytania) jako obiekt JavaScript mapujący nazwy parametrów na wartości.
  5. Nagłówki żądań HTTP jako obiekt JavaScriptu, który mapuje nazwy nagłówków na ich wartości.

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

Istnieją pewne wyjątki, o których warto pamiętać:

  • 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 Scripcie nazwę remove, ponieważ delete jest słowem zastrzeżonym w 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ć opcjonalny obiekt JavaScript parametrów (na pusty obiekt, jeśli nie używasz parametrów opcjonalnych).

Przykład: Calendar.Events.insert

Załóżmy, że chcesz utworzyć wydarzenie w Kalendarzu. Dokumentacja interfejsu Google Calendar API zawiera odpowiednią strukturę żądania HTTP:

  • HTTP Verb (Metoda HTTP): POST
  • Adres URL żądania: https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events

  • Treść żądania: zasób Event.

  • Parametry zapytania: sendUpdates, supportsAttachments itp.

W Apps Script sygnatura metody jest określana przez zmianę kolejności tych danych wejściowych:

  1. Body: zasób zdarzenia (obiekt JavaScript).
  2. Ścieżka: calendarId (ciąg znaków).
  3. Parametry opcjonalne: parametry zapytania (obiekt JavaScript).

Wynikowe wywołanie metody wygląda tak:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: {
    dateTime: '2026-01-01T12:00:00-05:00'
  },
  end: {
    dateTime: '2026-01-01T13:00:00-05:00'
  }
};
const calendarId = 'primary';
const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, calendarId, optionalArgs);

Usługi zaawansowane czy HTTP?

Każda zaawansowana usługa 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 wysyłając żądania interfejsu API bezpośrednio za pomocą UrlFetch.

Jeśli używasz metody zaawansowanej usługi, Apps Script obsługuje proces autoryzacji i oferuje funkcję autouzupełniania. Aby z niej korzystać, musisz jednak włączyć usługę zaawansowaną.

Jeśli do bezpośredniego dostępu do interfejsu API używasz metody UrlFetch, traktujesz interfejs API Google jako zewnętrzny interfejs API. Ta metoda umożliwia korzystanie ze wszystkich aspektów interfejsu API. Wymaga to jednak obsługi autoryzacji interfejsu API.

Poniższa tabela zawiera porównanie tych dwóch metod:

Funkcja Usługa zaawansowana UrlFetch (HTTP)
Autoryzacja Obsługiwane automatycznie Wymaga ręcznej obsługi
Autouzupełnianie Dostępna Niedostępne
Zakres funkcji Może być podzbiorem interfejsu API. Pełny dostęp do wszystkich funkcji interfejsu API
Złożoność Łatwiejszy Bardziej złożone (wymaga tworzenia nagłówków i analizowania odpowiedzi)

Porównanie kodu

Przykłady kodu pokazują różnicę w złożoności tworzenia wydarzenia w Kalendarzu za pomocą usługi zaawansowanej i za pomocą UrlFetchApp.

Usługa zaawansowana:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};

const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, 'primary', optionalArgs);

UrlFetch (HTTP):

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};
const url = 'https://www.googleapis.com/calendar/v3/calendars/primary/events?sendUpdates=all';
const options = {
  method: 'post',
  contentType: 'application/json',
  headers: {
    Authorization: `Bearer ${ScriptApp.getOAuthToken()}`
  },
  payload: JSON.stringify(event)
};

UrlFetchApp.fetch(url, options);

Jeśli to możliwe, zalecamy korzystanie z usługi zaawansowanej. Metody UrlFetch używaj tylko wtedy, gdy usługa zaawansowana jest niedostępna lub nie zapewnia potrzebnych funkcji.

Obsługa usług zaawansowanych

Usługi zaawansowane to cienkie otoki interfejsów API Google, więc każdy problem napotkany podczas korzystania z nich jest zwykle problemem z bazowym interfejsem API, a nie z Apps Script.

Jeśli podczas korzystania z usługi zaawansowanej wystąpi problem, należy go zgłosić, postępując zgodnie z instrukcjami pomocy dotyczącymi interfejsu API, na którym opiera się usługa.