Layanan lanjutan Google

Layanan lanjutan di Apps Script memungkinkan developer berpengalaman terhubung ke Google API publik tertentu dengan lebih sedikit penyiapan daripada menggunakan antarmuka HTTP mereka. Layanan lanjutan pada dasarnya adalah wrapper tipis di seputar Google API tersebut. Mereka bekerja seperti {i>Apps Script<i} layanan bawaan—misalnya, mereka menawarkan pelengkapan otomatis, dan Apps Script menangani alur otorisasi secara otomatis. Namun, Anda harus mengaktifkan layanan lanjutan sebelum Anda dapat menggunakannya dalam suatu skrip.

Untuk melihat Google API mana yang tersedia sebagai layanan lanjutan, cari atribut Layanan Google Lanjutan di Referensi. Jika Anda ingin menggunakan Google API yang tidak tersedia sebagai layanan lanjutan, cukup sambungkan API eksternal.

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 cukup membuat permintaan API secara langsung menggunakan UrlFetch

Jika Anda menggunakan metode layanan lanjutan, Apps Script akan menangani alur otorisasi dan penawaran dukungan pelengkapan otomatis. Namun, Anda harus aktifkan layanan lanjutan sebelum Anda dapat menggunakan anotasi. Selain itu, beberapa layanan lanjutan hanya menyediakan subset fungsi yang tersedia di API.

Jika menggunakan metode UrlFetch untuk mengakses API secara langsung, berarti Anda pada dasarnya memperlakukan Google API sebagai API eksternal. Dengan metode ini, semua aspek API dapat digunakan. Namun, Anda harus menangani API otorisasi sendiri. Anda juga harus membuat {i>header<i} apa pun yang dibutuhkan dan mengurai respons API.

Secara umum, cara paling mudah adalah menggunakan layanan lanjutan jika memungkinkan dan hanya gunakan metode UrlFetch jika layanan lanjutan tidak menyediakan fungsionalitas yang Anda butuhkan.

Persyaratan

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

  1. Anda harus mengaktifkan layanan lanjutan dalam proyek skrip Anda.

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

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

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

Lihat Project Cloud Platform untuk 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.

Setelah diaktifkan, layanan lanjutan akan tersedia di pelengkapan otomatis.

Cara tanda tangan metode ditentukan

Layanan lanjutan umumnya menggunakan objek, nama metode, dan parameter yang sama sebagai API publik yang sesuai, meskipun tanda tangan metode diterjemahkan untuk gunakan di Apps Script. fungsi pelengkapan otomatis biasanya memberikan informasi yang cukup untuk memulai, tetapi aturan di bawah ini menjelaskan cara Apps Script menghasilkan 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 media upload lampiran. Beberapa layanan lanjutan juga dapat menerima permintaan HTTP tertentu {i>header<i} (misalnya, Layanan lanjutan Kalender).

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

  1. Isi permintaan (biasanya resource), sebagai objek JavaScript.
  2. Jalur atau parameter yang diperlukan, sebagai argumen individual.
  3. Lampiran upload media, sebagai Blob argumen.
  4. Parameter opsional, sebagai objek JavaScript yang memetakan nama parameter ke masing-masing.
  5. Header permintaan HTTP, sebagai objek JavaScript yang memetakan nama header ke header masing-masing.

Jika metode tidak memiliki item apa pun di kategori tertentu, maka bagian dari tanda tangan dihilangkan.

Ada beberapa pengecualian khusus yang harus 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 sudah digunakan dalam JavaScript.
  • Jika layanan lanjutan dikonfigurasi untuk menerima header permintaan HTTP, dan Anda menyetel objek JavaScript header permintaan, maka Anda juga harus menetapkan parameter objek JavaScript (ke objek kosong jika Anda tidak menggunakan parameter opsional).

Dukungan untuk layanan lanjutan

Layanan lanjutan hanyalah wrapper tipis yang memungkinkan penggunaan API dalam Apps Script. Dengan demikian, setiap masalah yang ditemui ketika menggunakannya adalah biasanya masalah dengan API dasar, bukan dengan Apps Script itu sendiri.

Jika Anda mengalami masalah saat menggunakan layanan lanjutan, seharusnya dilaporkan menggunakan petunjuk dukungan untuk API dasar. Tautan ke petunjuk dukungan teknis tersedia di setiap panduan layanan lanjutan dalam Bagian Referensi Apps Script.