Zaawansowane usługi Google

Usługi zaawansowane w Google 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 tych interfejsów 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. Przed użyciem usługi zaawansowanej w skrypcie musisz ją włączyć.

Włączanie usług zaawansowanych

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

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

Włącz usługę zaawansowaną w edytorze skryptów Apps Script lub edytując plik manifestu.

Metoda A: korzystanie z edytora

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

Metoda B. Używanie pliku manifestu

Włącz usługi zaawansowane, 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 w chmurze Google (utworzonego automatycznie przez Apps Script), pomiń ten krok. Interfejs API jest włączany automatycznie po dodaniu usługi w kroku 1.

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

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

2. U góry konsoli kliknij pasek wyszukiwania i wpisz część nazwy interfejsu API (np. „Calendar”), 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 zwykle używają tych samych obiektów, nazw metod i parametrów co odpowiednie publiczne interfejsy API, chociaż sygnatury metod są tłumaczone na potrzeby użycia w Apps Script. Funkcja autouzupełniania w edytorze skryptów zwykle zawiera wystarczająco dużo informacji, aby można było zacząć. 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).

Odpowiedni podpis metody w 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 do przesyłania multimediów jako argument Blob.
4. Parametry opcjonalne (zwykle parametry zapytania) jako obiekt JavaScript, który mapuje 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.

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 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

Aby utworzyć wydarzenie w Kalendarzu:

Dokumentacja interfejsu Kalendarza Google 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. Zanim zaczniesz korzystać z usługi zaawansowanej, musisz ją włączyć.

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. Musisz jednak zarządzać autoryzacją interfejsu API.

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

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);

W przypadku metody UrlFetchApp ręcznie określ wymagane zakresy OAuth w pliku manifestu skryptu.

W miarę możliwości korzystaj z usługi zaawansowanej, a metodyUrlFetch 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 napotkasz problem, zgłoś go, postępując zgodnie z instrukcjami pomocy dotyczącymi interfejsu API, na którym opiera się ta usługa.