Tugas Apps Script

Pengumuman: Application Integration kini tersedia untuk project Google Cloud Anda. Anda kini dapat menggunakan Apigee Integration dan Application Integration dalam project Google Cloud yang sama. Pelajari lebih lanjut

Tugas Apps Script memungkinkan Anda menjalankan Google Apps Script dari integrasi Anda. Google Apps Script adalah platform pengembangan aplikasi cepat yang membuatnya cepat dan aplikasi bisnis yang mudah dibuat. Untuk 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:

• Mengaktifkan AppsScript API
• Membuat Client ID OAuth 2.0
• Menyiapkan profil autentikasi
• Pastikan Kontrol Layanan VPC BUKAN disiapkan untuk Integrasi Apigee di project Google Cloud.
  Peringatan: Cloud Function tidak berfungsi atau berhenti berfungsi jika Kontrol Layanan VPC disiapkan untuk Integrasi Apigee di project Google Cloud.

Mengaktifkan AppsScript API

Anda harus mengaktifkan AppsScript API di project Google Cloud dan akun pengguna AppsScript untuk menggunakan tugas ini. Untuk mengetahui informasi tentang cara mengaktifkan AppsScript API di project Google Cloud Anda, lihat Mengaktifkan API dalam project Google Cloud standar. Untuk mengaktifkan API di akun pengguna Anda, klik Settings dan setel Google Apps Script API sampai On.

Membuat client ID OAuth 2.0

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

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

Siapkan profil autentikasi

Integrasi Apigee 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 UI Apigee, pilih Organisasi Apigee Anda.
2. Klik Develop > Integrasi.
3. Pilih integrasi yang ada atau buat integrasi baru dengan mengklik Buat Integrasi.

   Jika Anda membuat integrasi baru:

   1. Masukkan nama dan deskripsi dalam dialog Create Integration.
   2. Pilih Region untuk integrasi dari daftar wilayah yang didukung.
   3. Klik Create.

   Tindakan ini akan membuka integrasi di desainer integrasi.

4. Di menu navigasi desainer integrasi, klik +Tambahkan tugas/pemicu > Tasks untuk melihat daftar tugas yang tersedia.
5. Klik dan tempatkan elemen Apps Script di editor integrasi.

Membuat profil autentikasi

1. Klik elemen Apps Script pada desainer untuk melihat Apps Script panel konfigurasi tugas.
2. Di panel konfigurasi tugas pada tugas Apps Script, klik +New authentication profile.
3. Pada dialog Authentication profile, masukkan nama dan deskripsi untuk profil, lalu tetapkan properti berikut:
   • Jenis autentikasi: Pilih Kode otorisasi OAuth 2.0
   • Endpoint Authentication: 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 > Client ID OAuth 2.0.

   • Secret: Masukkan rahasia klien

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

   • Cakupan: Masukkan:

     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 otentikasi Anda disimpan, dan Anda dapat terus mengedit integrasi Anda.

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

Mengonfigurasi tugas Apps Script

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

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

   Dialog Apps Script Configuration akan muncul.

2. Anda dapat memilih untuk menautkan project Apps Script yang sudah ada atau buat project Apps Script baru.

   Mengonfigurasi project Apps Script akan mengaitkan project Apps Script dengan integrasi Anda di Integrasi Apigee.

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

   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 dieksekusi. Dalam skrip, Anda dapat menggunakan variabel yang ditentukan di tingkat integrasi. Untuk informasi tentang cara menggunakan variabel integrasi, lihat Menggunakan variabel integrasi.
   • Main.gs: Berisi kode inisialisasi yang akan dijalankan Apps Script dari integrasi Anda. Jangan edit atau ubah file ini.
   • Test.gs: Berisi kode yang dapat dieksekusi untuk pengujian yang dijalankan. Anda dapat menulis skrip di dalam fungsi testRun untuk menguji skrip.

   Pastikan untuk men-deploy project dalam format Aplikasi web. Sebagai informasi selengkapnya tentang beragam mode deployment, Membuat dan mengelola deployment.

Mengakses variabel integrasi

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

Untuk mengakses variabel integrasi di Apps Script, Anda harus meneruskan variabel dalam bentuk parameter tugas ke tugas Apps Script. Parameter tugasnya pasangan nilai kunci dengan Kunci adalah nama variabelnya di tugas AppsScript Anda dan Nilai adalah nama variabel integrasi yang sesuai. Anda dapat menambahkan satu atau beberapa parameter tugas di bagian Parameter Tugas pada tugas panel konfigurasi.

Misalnya, jika Anda memiliki variabel integrasi bernama Product yang 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 AppsScript, variabel harus ditambahkan sebagai parameter tugas ke tugas Apps Script.

Library AppsScriptTask menyediakan metode berikut untuk variabel integrasi akses (AP):

• setIntegrationVariable
• getTaskParameter

Nama fungsi	Deskripsi	Penggunaan
setIntegrationVariable	Menetapkan nilai yang disediakan 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 pernyataan berbasis pernyataan kasus pengujian dan secara otomatis diimpor 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 Execution log dari menu.

Praktik terbaik

Kami tidak menyarankan penggunaan tugas Apps Script jika Anda memerlukan latensi kurang dari 1 hingga 2 detik untuk tugas tersebut dalam integrasi Anda.

Selain itu, sebaiknya Anda melakukan coding semua logika dalam satu tugas Apps Script, daripada membuat rantai lebih dari satu tugas Apps Script, untuk meminimalkan bottleneck performa.

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

Pertimbangan

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

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

Strategi penanganan error

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