Tugas Apps Script

Tugas Apps Script memungkinkan Anda menjalankan Google Apps Script dari integrasi. Google Apps Script adalah platform pengembangan aplikasi cepat yang memudahkan dan mempercepat pembuatan aplikasi bisnis. Untuk mengetahui informasi selengkapnya, lihat Google Apps Script. Tugas ini berguna saat Anda ingin menjalankan skrip kustom atau menggunakan kembali skrip yang ada dalam integrasi Anda.

Catatan: Tugas Apps Script adalah layanan global non-regional.

Sebelum memulai

Sebelum menggunakan tugas Apps Script, pastikan Anda menyelesaikan langkah-langkah berikut:

• Aktifkan Apps Script API
• Buat Client ID OAuth 2.0
• Menyiapkan profil autentikasi
• Pastikan Kontrol Layanan VPC TIDAK disiapkan untuk Integrasi Aplikasi di project Google Cloud Anda.
  Peringatan: Cloud Function tidak berfungsi atau berhenti berfungsi jika VPC Service Controls disiapkan untuk Integrasi Aplikasi di project Google Cloud Anda.

Aktifkan Apps Script API

Anda harus mengaktifkan Apps Script API di project Google Cloud dan akun pengguna Apps Script Anda untuk menggunakan tugas ini. Untuk mengetahui informasi tentang cara mengaktifkan Apps Script API di project Google Cloud Anda, lihat Mengaktifkan API di project Google Cloud standar. Untuk mengaktifkan API di akun pengguna Anda, klik Setelan dan tetapkan Google Apps Script API ke On.

Buat client ID OAuth 2.0

Jika memiliki ID klien OAuth 2.0, Anda dapat melewati langkah ini dan melanjutkan ke Menyiapkan profil autentikasi.

Untuk mengetahui informasi tentang cara membuat client ID OAuth baru, lihat Membuat client ID OAuth.

Menyiapkan profil autentikasi

Application Integration menggunakan profil autentikasi untuk terhubung ke Google Cloud guna men-deploy dan menjalankan project Apps Script. Untuk menyiapkan profil autentikasi, lakukan langkah-langkah berikut:

Menambahkan tugas Apps Script

1. Di konsol Google Cloud , buka halaman Application Integration.

   Buka Application Integration

2. Di menu navigasi, klik Integrasi.

   Halaman Integrasi akan muncul dan mencantumkan semua integrasi yang tersedia di project Google Cloud.

3. Pilih integrasi yang ada atau klik Buat integrasi untuk membuat integrasi baru.

   Jika Anda membuat integrasi baru:

   1. Masukkan nama dan deskripsi di panel Buat Integrasi.
   2. Pilih region untuk integrasi.
      Catatan: Dropdown Regions hanya mencantumkan region yang disediakan di project Google Cloud Anda. Untuk menyediakan wilayah baru, klik Aktifkan Wilayah. Lihat Mengaktifkan region baru untuk mengetahui informasi selengkapnya.
   3. Pilih akun layanan untuk integrasi. Anda dapat mengubah atau memperbarui detail akun layanan integrasi kapan saja dari panel Ringkasan integrasi di toolbar integrasi.
      Catatan: Opsi untuk memilih akun layanan hanya ditampilkan jika Anda telah mengaktifkan tata kelola integrasi untuk wilayah yang dipilih.
   4. Klik Buat. Integrasi yang baru dibuat akan terbuka di editor integrasi.

4. Di menu navigasi editor integrasi, klik Tugas untuk melihat daftar tugas dan konektor yang tersedia.
5. Klik dan tempatkan elemen Apps Script di editor integrasi.

Membuat profil autentikasi

1. Klik elemen Apps Script di perancang untuk melihat panel konfigurasi tugas Apps Script.
2. Di panel konfigurasi tugas pada tugas Apps Script, klik +New authentication profile.
3. Dalam dialog Authentication profile, masukkan nama dan deskripsi untuk profil, lalu tetapkan properti berikut:
   • Jenis autentikasi: Pilih Kode otorisasi OAuth 2.0
   • Endpoint autentikasi: Masukkan https://accounts.google.com/o/oauth2/auth
   • Endpoint token: Masukkan https://oauth2.googleapis.com/token
   • Client ID: Masukkan client ID.

     Client ID tersedia di dasbor project Google Cloud Anda di bagian Credentials > OAuth 2.0 Client IDs.

   • Secret: Masukkan rahasia klien

     Rahasia klien tersedia di dasbor project Google Cloud Anda di bagian Credentials > OAuth 2.0 Client IDs.

   • Cakupan: Masukkan berikut ini:

     https://www.googleapis.com/auth/script.projects https://www.googleapis.com/auth/script.deployments https://www.googleapis.com/auth/script.deployments.readonly https://www.googleapis.com/auth/drive.scripts https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/script.external_request https://www.googleapis.com/auth/userinfo.email

     Catatan: Beberapa cakupan dapat dipisahkan dengan satu karakter spasi (" ").

4. Klik Generate Access Token and Save.

   Anda akan dialihkan ke layar otorisasi. Login dan berikan izin untuk izin yang tercantum di layar untuk membuat token akses Anda. Jika pembuatan token akses berhasil, profil autentikasi Anda akan disimpan, dan Anda dapat melanjutkan pengeditan integrasi.

Catatan: Pengguna yang sama harus membuat profil autentikasi dan men-deploy Apps Script. Jika pengguna berbeda, Apps Script tidak berjalan.

Mengonfigurasi tugas Apps Script

Untuk mengonfigurasi project Apps Script dalam tugas Apps Script, lakukan langkah-langkah berikut:

1. Di panel konfigurasi tugas, klik Configure Apps Script Project.

   Dialog Konfigurasi Apps Script akan muncul.

2. Anda dapat memilih untuk menautkan ke project Apps Script yang ada atau membuat project Apps Script baru.

   Mengonfigurasi project Apps Script akan mengaitkan project Apps Script dengan integrasi Anda di Application Integration.

3. Klik Simpan.
4. Klik Open Apps Script Project.

   Di editor Apps Script, Anda dapat melihat file berikut:

   • Run.gs: Berisi kode yang dapat dieksekusi. Tulis skrip Anda di dalam fungsi run. Fungsi ini dipanggil saat tugas Apps Script dijalankan. Dalam skrip, Anda dapat menggunakan variabel yang ditentukan di tingkat integrasi. Untuk mengetahui informasi tentang penggunaan variabel integrasi, lihat Menggunakan variabel integrasi.
   • Main.gs: Berisi kode inisialisasi untuk menjalankan Apps Script dari integrasi Anda. Jangan mengedit atau mengubah file ini.
   • Test.gs: Berisi kode yang dapat dieksekusi untuk menjalankan pengujian. Anda dapat menulis skrip di dalam fungsi testRun untuk menguji skrip.

   Pastikan untuk men-deploy project dalam format Web apps. Untuk mengetahui informasi selengkapnya tentang berbagai mode deployment, lihat Membuat dan mengelola deployment.

Mengakses variabel integrasi

Tugas Apps Script menggunakan library AppsScriptTask, yang memungkinkan Anda menggunakan variabel integrasi dalam skrip. Library AppsScriptTask diimpor secara otomatis dan tersedia untuk digunakan dalam fungsi run.

Untuk mengakses variabel integrasi di Apps Script, Anda harus meneruskan variabel dalam bentuk parameter tugas ke tugas Apps Script. Parameter tugas adalah key-value pair dengan Kunci adalah nama variabel dalam tugas Apps Script Anda dan Nilai adalah nama variabel integrasi yang sesuai. Anda dapat menambahkan satu atau beberapa parameter tugas di bagian Parameter Tugas pada panel konfigurasi tugas.

Misalnya, jika Anda memiliki variabel integrasi bernama Product yang ingin digunakan di Apps Script, Anda dapat menentukan Key sebagai ProductKey dan nilai sebagai Product. Di Apps Script, Anda kemudian dapat menggunakan AppsScriptTask.getTaskParameter('ProductKey') untuk membaca variabel Product.

Catatan: Untuk menggunakan variabel integrasi di Apps Script, variabel harus ditambahkan sebagai parameter tugas ke tugas Apps Script.

Library AppsScriptTask menyediakan metode berikut untuk mengakses variabel integrasi:

• setIntegrationVariable
• getTaskParameter

Nama fungsi	Deskripsi	Penggunaan
setIntegrationVariable	Menetapkan nilai yang diberikan ke variabel.	Sintaksis: setIntegrationVariable(value,value) Contoh: // Write to an Integer variable AppsScriptTask.setIntegrationVariable('EmployeeIDKey','456');
getTaskParameter	Mendapatkan nilai variabel.	Sintaksis: getTaskParameter(value) Contoh: // Read an integration variable AppsScriptTask.getTaskParameter('EmployeeIDKey');

Untuk melihat semua fungsi yang tersedia di library AppsScriptTask, arahkan kursor ke item menu AppsScriptTask di editor Apps Script, klik Lainnya > Buka di tab baru.

Menguji Apps Script

Sebelum memublikasikan integrasi, Anda dapat menguji skrip menggunakan fungsi testRun yang tersedia di file Test.gs. Tulis kode pengujian Anda dalam fungsi testRun, menggunakan library AppsScriptTaskTest. Library ini memungkinkan Anda menjalankan kasus pengujian berbasis pernyataan dan diimpor secara otomatis untuk digunakan dalam fungsi testRun.

Untuk melihat semua fungsi yang tersedia di library AppsScriptTaskTest, arahkan kursor ke item menu AppsScriptTaskTest di editor Apps Script, klik Lainnya > Buka di tab baru.

Contoh berikut menunjukkan penggunaan fungsi library AppsScriptTaskTest.

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('myCustomTest');

  // Add a task parameter that references an integration variable with the value 5
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, 'input', '$input$', 5);

  // Add a task parameter that references an integration variable
  AppsScriptTaskTest.createReference(req, 'output', '$output$');

  // Run the task(assuming the task increments the input by 1) and get the response
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.containsIntegrationVariable(res, 'output', true);
  AppsScriptTaskTest.containsIntegrationVariable(res, 'someOtherIntegrtionVariable', false);
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, 'output', 6);
}

Contoh berikut menunjukkan cara mengakses variabel JSON dan array dalam metode testRun:

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('json-test');

  // Add a task parameter that references a JSON integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "emp", "employee", {name:"snape", age:35});

  // Add a task parameter that references an array integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "arr", "array", ["A", "B", "C"]);


  // Run the task and get the response
  // Assume that the run method increases the age of the employee by 5 and appends a new element in the array
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, "employee", {name:"snape", age:40});
  AppsScriptTaskTest.containsIntegrationVariable(res, "array", true);
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, "array", ["A", "B", "C", "D"]);
}

Setelah menjalankan kasus pengujian, Anda dapat melihat pernyataan di Log eksekusi. Untuk melihat log, klik Log eksekusi dari menu.

Praktik terbaik

Sebaiknya jangan gunakan tugas Apps Script jika Anda memerlukan latensi kurang dari 1 hingga 2 detik untuk tugas dalam integrasi Anda.

Selain itu, sebaiknya kode semua logika Anda dalam satu tugas Apps Script, bukan merangkai beberapa tugas Apps Script, untuk meminimalkan hambatan performa.

Untuk mengetahui informasi tentang batas penggunaan yang berlaku untuk tugas Apps Script, lihat Batas penggunaan.

Pertimbangan

Saat menyertakan tugas Apps Script dalam desain integrasi, pertimbangkan batasan sistem berikut:

• Deployment aktif maksimum untuk AppsScript: 50
• Kueri per detik (QPS) untuk file yang dapat dieksekusi API: 5000/mnt
• Kueri per detik (QPS) untuk deployment Webapp: 5.000/menit
• Latensi untuk file yang dapat dieksekusi API: 1,5 dtk
• Latensi untuk Aplikasi Web: 2,5 dtk
• Ukuran kumulatif maksimum semua variabel integrasi di AppsScript: 15 MB

Strategi penanganan error

Strategi penanganan error untuk tugas menentukan tindakan yang harus dilakukan jika tugas gagal karena error sementara. Untuk mengetahui informasi tentang cara menggunakan strategi penanganan error, dan untuk mengetahui berbagai jenis strategi penanganan error, lihat Strategi penanganan error.

Pengecualian SLA

Tugas Apps Script memiliki dependensi pada produk Google Apps Script. Karena dependensi ini bersifat eksternal terhadap Integrasi Aplikasi, semua eksekusi integrasi active yang gagal karena kegagalan dalam tugas Apps Script, dikecualikan dari persyaratan dan ketentuan Perjanjian Tingkat Layanan (SLA) Integrasi Aplikasi.

Kuota dan batas

Untuk mengetahui informasi tentang kuota dan batas, lihat Kuota dan batas.

Langkah berikutnya

• Pelajari semua tugas dan pemicu.
• Pelajari cara menguji dan memublikasikan integrasi.
• Pelajari penanganan error.
• Pelajari log eksekusi integrasi.