Halaman ini diterjemahkan oleh Cloud Translation API.

Layanan lanjutan Google

Layanan lanjutan di Apps Script memungkinkan Anda terhubung ke API Google publik tertentu dengan lebih sedikit penyiapan dibandingkan menggunakan antarmuka HTTP-nya. Layanan lanjutan adalah wrapper tipis di seputar Google API tersebut. Layanan ini berfungsi seperti layanan bawaan Apps Script—misalnya, layanan ini menawarkan pelengkapan otomatis, dan Apps Script menangani alur otorisasi secara otomatis. Namun, Anda harus mengaktifkan layanan lanjutan sebelum dapat menggunakannya dalam skrip.

Mengaktifkan layanan lanjutan

Untuk menggunakan layanan Google lanjutan, ikuti petunjuk berikut:

Langkah 1: Aktifkan layanan lanjutan

Anda dapat mengaktifkan layanan lanjutan menggunakan editor Apps Script atau dengan mengedit manifes.

Metode A: Menggunakan Editor

Buka project Apps Script.
Di sebelah kiri, klik Editor .
Di sebelah kiri, di samping Layanan, klik Tambahkan layanan .
Pilih layanan Google lanjutan, lalu klik Tambahkan.

Metode B: Menggunakan manifes

Anda dapat mengaktifkan layanan lanjutan dengan mengedit file manifes. Misalnya, untuk mengaktifkan layanan lanjutan Google Drive, tambahkan kolom enabledAdvancedServices ke objek dependencies:

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

Setelah Anda mengaktifkan layanan lanjutan, layanan tersebut akan tersedia di pelengkapan otomatis.

Langkah 2: Aktifkan Google Cloud API (Khusus project Google Cloud standar)

Jika Anda menggunakan project Google Cloud default (dibuat secara otomatis oleh Apps Script), Anda dapat melewati langkah ini. API diaktifkan secara otomatis saat Anda menambahkan layanan di Langkah 1.

Jika Anda menggunakan project Google Cloud standar, Anda juga harus mengaktifkan API yang sesuai dengan layanan lanjutan secara manual. Untuk mengaktifkan API secara manual:

Buka project Cloud yang terkait dengan skrip Anda di **Konsol Google Cloud**
Di bagian atas konsol, klik kotak penelusuran dan ketik sebagian nama API (misalnya, "Calendar"), lalu klik nama setelah Anda melihatnya.
Klik Enable API.
Tutup konsol Google Cloud dan kembali ke editor skrip.

Cara penentuan tanda tangan metode

Layanan lanjutan umumnya menggunakan objek, nama metode, dan parameter yang sama dengan API publik yang sesuai, meskipun tanda tangan metode diterjemahkan untuk digunakan di Apps Script. Fungsi pelengkapan otomatis editor skrip biasanya memberikan informasi yang cukup untuk memulai, tetapi aturan berikut menjelaskan cara Apps Script membuat tanda tangan metode dari Google API publik.

Permintaan ke Google API dapat menerima berbagai jenis data yang berbeda, termasuk parameter jalur, parameter kueri, isi permintaan, atau lampiran upload media. Beberapa layanan lanjutan juga dapat menerima header permintaan HTTP tertentu (misalnya, layanan lanjutan Kalender).

Tanda tangan metode yang sesuai di Google Apps Script memiliki argumen berikut:

Isi permintaan (biasanya resource), sebagai objek JavaScript.
Jalur atau parameter yang diperlukan, sebagai argumen individual. Jika metode memerlukan beberapa parameter jalur, parameter tersebut akan muncul sesuai urutan yang tercantum di URL endpoint API.
Lampiran upload media, sebagai argumen Blob.
Parameter opsional (biasanya parameter kueri), sebagai objek JavaScript yang memetakan nama parameter ke nilai.
Header permintaan HTTP, sebagai objek JavaScript yang memetakan nama header ke nilai header.

Jika metode tidak memiliki item dalam kategori tertentu, bagian tanda tangan tersebut akan dihilangkan.

Ada beberapa pengecualian khusus yang perlu diketahui:

Untuk metode yang menerima upload media, parameter uploadType ditetapkan secara otomatis.
Metode yang bernama delete di Google API diberi nama remove di Apps Script, karena delete adalah kata yang dicadangkan di JavaScript.
Jika layanan lanjutan dikonfigurasi untuk menerima header permintaan HTTP, dan Anda menetapkan objek JavaScript header permintaan, Anda juga harus menetapkan objek JavaScript parameter opsional (ke objek kosong jika Anda tidak menggunakan parameter opsional).

Contoh: Calendar.Events.insert

Misalnya, Anda ingin membuat acara Kalender. Dokumentasi Google Calendar API menunjukkan struktur permintaan HTTP yang sesuai:

HTTP Verb: POST
URL Permintaan: https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events
Isi Permintaan: Resource Event.
Parameter Kueri: sendUpdates, supportsAttachments, dll.

Di Apps Script, tanda tangan metode ditentukan dengan menyusun ulang input ini:

Body: Resource acara (objek JavaScript).
Jalur: calendarId (string).
Parameter opsional: Parameter kueri (objek JavaScript).

Panggilan metode yang dihasilkan akan terlihat seperti ini:

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

Layanan lanjutan atau HTTP?

Setiap layanan Google lanjutan dikaitkan dengan Google API publik. Di Apps Script, Anda dapat mengakses API ini menggunakan layanan lanjutan atau dengan membuat permintaan API secara langsung menggunakan UrlFetch.

Jika Anda menggunakan metode layanan lanjutan, Apps Script akan menangani alur otorisasi dan menawarkan dukungan isi otomatis. Namun, Anda harus mengaktifkan layanan lanjutan sebelum dapat menggunakannya.

Jika Anda menggunakan metode UrlFetch untuk mengakses API secara langsung, pada dasarnya Anda memperlakukan Google API sebagai API eksternal. Dengan metode ini, semua aspek API dapat digunakan. Namun, Anda harus menangani otorisasi API.

Tabel berikut membandingkan kedua metode tersebut:

Fitur	Layanan Lanjutan	UrlFetch (HTTP)
Otorisasi	Ditangani secara otomatis	Memerlukan penanganan manual
Pelengkapan Otomatis	Tersedia	Tidak tersedia
Cakupan Fungsi	Mungkin merupakan subset API	Akses penuh ke semua fitur API
Kompleksitas	Lebih mudah	Lebih kompleks (memerlukan pembuatan header dan parsing respons)

Perbandingan kode

Contoh kode menunjukkan perbedaan kompleksitas antara membuat acara Kalender menggunakan layanan lanjutan dan menggunakan UrlFetchApp.

Layanan Lanjutan:

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

Sebaiknya gunakan layanan lanjutan jika memungkinkan dan hanya gunakan metode UrlFetch jika layanan lanjutan tidak tersedia atau tidak menyediakan fungsi yang Anda butuhkan.

Dukungan untuk layanan lanjutan

Karena layanan lanjutan adalah wrapper tipis di sekitar Google API, masalah apa pun yang terjadi saat menggunakannya biasanya merupakan masalah pada API yang mendasarinya, bukan pada Apps Script.

Jika Anda mengalami masalah saat menggunakan layanan lanjutan, masalah tersebut harus dilaporkan menggunakan petunjuk dukungan untuk API yang mendasarinya.