Layanan lanjutan Google

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

Untuk melihat Google API mana yang tersedia sebagai layanan lanjutan, cari bagian Layanan Google Lanjutan di Referensi. Jika Anda ingin menggunakan Google API yang tidak tersedia sebagai layanan lanjutan, cukup hubungkan ke API tersebut seperti API eksternal lainnya.

Layanan lanjutan atau HTTP?

Setiap layanan Google lanjutan dikaitkan dengan Google API publik. Di Apps Script, Anda dapat mengakses API ini melalui 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 pelengkapan otomatis. Namun, Anda harus mengaktifkan layanan lanjutan sebelum dapat menggunakannya. Selain itu, beberapa layanan lanjutan hanya menyediakan sebagian dari fungsi yang tersedia di API.

Jika menggunakan metode UrlFetch untuk mengakses API secara langsung, Anda pada dasarnya memperlakukan Google API sebagai API eksternal. Dengan metode ini, semua aspek API dapat digunakan. Namun, Anda harus menangani otorisasi API sendiri. Anda juga harus membuat header yang diperlukan dan mengurai respons API.

Secara umum, sebaiknya gunakan layanan lanjutan jika memungkinkan dan hanya gunakan metode UrlFetch jika layanan lanjutan tidak menyediakan fungsi yang Anda butuhkan.

Persyaratan

Sebelum dapat menggunakan layanan lanjutan, Anda harus memenuhi persyaratan berikut:

1. Anda harus mengaktifkan layanan lanjutan di project skrip Anda.

2. Anda harus memastikan API yang sesuai dengan layanan lanjutan diaktifkan di project Cloud Platform (GCP) yang digunakan skrip Anda.

   Jika project skrip Anda menggunakan project GCP default yang dibuat pada atau setelah 8 April 2019, API akan otomatis diaktifkan setelah Anda mengaktifkan layanan lanjutan dan menyimpan project skrip. Jika belum melakukannya, Anda mungkin juga diminta untuk menyetujui Persyaratan Layanan Google Cloud dan Google API.

   Jika project skrip Anda menggunakan project GCP standar atau project GCP default yang lebih lama, Anda harus mengaktifkan API yang sesuai untuk layanan lanjutan di project GCP secara manual. Anda harus memiliki akses edit ke project GCP untuk melakukan perubahan ini.

Lihat Project Cloud Platform untuk mengetahui informasi selengkapnya.

Mengaktifkan layanan lanjutan

Untuk menggunakan layanan Google lanjutan, ikuti petunjuk berikut:

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

Catatan: Jika menggunakan project GCP standar (atau project GCP default lama yang dibuat sebelum 8 April 2019), Anda juga harus mengaktifkan API yang sesuai dengan layanan lanjutan secara manual. Aktifkan API dengan melakukan tindakan berikut:

1. Buka project GCP yang terkait dengan skrip Anda di konsol Google Cloud.
2. Di bagian atas konsol, klik kotak penelusuran dan ketik bagian nama API (misalnya, "Kalender"), lalu klik nama tersebut setelah Anda melihatnya.
3. Di layar berikutnya, klik Enable API.
4. Tutup konsol Google Cloud dan kembali ke editor skrip. Klik OK di dialog.

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

Cara tanda tangan metode ditentukan

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 di bawah menjelaskan cara Apps Script membuat tanda tangan metode dari Google API publik.

Permintaan ke Google API dapat menerima berbagai jenis data, termasuk parameter jalur, parameter kueri, isi permintaan, dan/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:

1. Isi permintaan (biasanya resource), sebagai objek JavaScript.
2. Jalur atau parameter yang diperlukan, sebagai argumen individual.
3. Lampiran upload media, sebagai argumen Blob.
4. Parameter opsional, sebagai objek JavaScript yang memetakan nama parameter ke nilai.
5. 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 diperhatikan:

• Untuk metode yang menerima upload media, parameter uploadType ditetapkan secara otomatis.
• Metode bernama delete di Google API diberi nama remove di Apps Script, karena delete adalah kata yang direservasi 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).

Dukungan untuk layanan lanjutan

Layanan lanjutan hanyalah wrapper tipis yang memungkinkan penggunaan Google API dalam Apps Script. Dengan demikian, masalah apa pun yang dialami saat menggunakannya biasanya merupakan masalah pada API yang mendasarinya, bukan pada Apps Script itu sendiri.

Jika Anda mengalami masalah saat menggunakan layanan lanjutan, masalah tersebut harus dilaporkan menggunakan petunjuk dukungan untuk API yang mendasarinya. Link ke petunjuk dukungan ini disediakan di setiap panduan layanan lanjutan di bagian Referensi Skrip Aplikasi.