Dasar-Dasar Apps Script dengan Google Spreadsheet #1: Makro & Fungsi Kustom

1. Selamat datang di Apps Script

Apa itu Apps Script?

Apps Script adalah platform pengembangan aplikasi cepat yang memberi Anda kemampuan untuk mengotomatiskan, menyesuaikan, dan memperluas pengalaman Google Workspace Anda. Dengan Apps Script, Anda dapat menghemat waktu dan tenaga dengan menyederhanakan pekerjaan yang sulit atau kompleks dalam Google Workspace.

Fitur Apps Script mencakup hal berikut:

• Layanan bawaan Apps Script memungkinkan Anda membaca, memperbarui, dan memanipulasi data aplikasi Google Workspace dengan skrip.
• Anda dapat membuat skrip menggunakan editor kode dalam browser Apps Script—tidak perlu menginstal atau menjalankan perangkat lunak pengembangan kode.
• Anda dapat mendesain antarmuka pengguna untuk editor Google Workspace yang memungkinkan Anda mengaktifkan skrip secara langsung dari editor tersebut menggunakan item menu, dialog, dan sidebar.

Playlist codelab Dasar-Dasar Aplikasi dengan Google Spreadsheet ini mengajarkan dasar-dasar Apps Script dan cara menggunakannya untuk meningkatkan pengalaman Google Spreadsheet Anda. Codelab ini berfokus pada pengajaran dasar-dasar Apps Script.

Layanan Spreadsheet

Anda dapat menggunakan Apps Script untuk memperluas Google Spreadsheet guna menghemat waktu dan upaya. Apps Script menyediakan layanan Spreadsheet yang memungkinkan skrip untuk berinteraksi dengan file Spreadsheet Google Anda dan data di dalamnya. Anda dapat menggunakan layanan ini untuk mengotomatiskan tugas spreadsheet umum berikut:

• Buat atau ubah spreadsheet.
• Membaca dan mengupdate data, formula, dan format sel.
• Membuat tombol dan menu kustom.
• Impor dan ekspor data dari aplikasi Google lain atau sumber pihak ketiga.
• Berbagi dan mengontrol akses ke spreadsheet.

Yang akan Anda pelajari

Playlist ini mencakup semua topik yang Anda perlukan untuk mulai menggunakan Apps Script dengan Google Spreadsheet:

1. Makro dan Fungsi Kustom
2. Spreadsheet, Spreadsheet, dan Rentang
3. Bekerja dengan data
4. Format data
5. Membuat diagram dan menyajikan data di Slide

Codelab dalam playlist ini dimaksudkan untuk dibaca secara berurutan, jadi mulailah dengan codelab ini dan selesaikan secara berurutan untuk mendapatkan pengalaman pembelajaran terbaik.

Pindah ke bagian berikutnya untuk mempelajari lebih lanjut konten codelab ini.

2. Pengantar

Selamat datang di codelab pertama playlist ini. Dalam codelab ini, Anda akan mempelajari dasar-dasar penggunaan Apps Script dengan Google Spreadsheet. Secara khusus, codelab ini berfokus pada dua konsep utama: makro dan fungsi kustom.

Makro adalah serangkaian tindakan yang direkam dalam Google Spreadsheet. Setelah direkam, Anda dapat mengaktifkan makro untuk mengulangi tindakan tersebut nanti dengan item menu atau tombol pintasan. Anda dapat membuat dan memperbarui makro Anda sendiri di Google Spreadsheet dan editor kode Apps Script.

Di editor kode Apps Script, Anda juga dapat membuat fungsi kustom. Serupa dengan yang ditawarkan oleh penawaran fungsi bawaan Spreadsheet (seperti SUM atau AVERAGE), Anda dapat menggunakan Apps Script untuk menulis fungsi kustom sendiri untuk operasi sederhana dan khusus (seperti konversi atau penyambungan string). Setelah dibuat, Anda dapat memanggil fungsi ini di Spreadsheet seperti yang dilakukan pada fungsi bawaan. Fungsi kustom juga dapat digunakan dalam formula sel yang Anda tulis, menggabungkannya dengan fungsi lain sesuai kebutuhan.

Baca di bawah ini untuk mempelajari konsep dan persyaratan yang tercakup dalam codelab ini.

Yang akan Anda pelajari

• Cara membuat skrip untuk Google Spreadsheet.
• Cara menavigasi editor Apps Script.
• Cara membuat dan mengupdate makro.
• Cara membuat fungsi kustom Spreadsheet pertama Anda.

Yang Anda butuhkan

• Pemahaman dasar tentang JavaScript
• Pemahaman dasar tentang Google Spreadsheet
• Kemampuan untuk membaca Notasi A1 Spreadsheet

Catatan: Apps Script didasarkan pada JavaScript. Jika Anda baru mengenal JavaScript, Codecademy menawarkan kursus JavaScript Pengantar secara gratis. Meskipun tidak dibuat oleh Google, kursus ini harus membahas semua hal yang perlu Anda ketahui.

Anda sudah selesai dengan pengantar. Buka bagian berikutnya untuk mulai menggunakan makro.

3. Membuat makro di Spreadsheet

Biasanya, saat bekerja dalam spreadsheet, Anda dapat memasukkan tindakan berulang yang berulang—menyalin nilai sel, memformat, membuat formula, dan sebagainya—yang dapat membosankan dan menyebabkan kesalahan. Untuk mengotomatiskan tindakan berulang, Google Spreadsheet menyediakan makro. Makro memungkinkan Anda ‘merekam' serangkaian tindakan dalam sheet. Dengan makro yang direkam, Anda dapat mengulangi tindakan yang sama di tempat lain dalam spreadsheet dengan menekan hotkey sederhana.

Pada bagian ini, Anda akan mempelajari cara membuat makro di Spreadsheet. Di bagian berikutnya, Anda akan melihat cara makro dibuat menggunakan Apps Script.

Sebelum memulai

Sebelum melanjutkan, Anda memerlukan spreadsheet yang berisi beberapa data. Kami telah menyediakannya untuk Anda: klik link ini untuk menyalin sheet data, lalu klik Buat salinan.

Salinan contoh spreadsheet yang dapat Anda gunakan ditempatkan di folder Google Drive Anda dan diberi nama "Salinan dari 10 Film Terlaris Teratas (2018)."

Membuat makro

Setelah memiliki spreadsheet untuk dikerjakan, Anda dapat merekam makro di Google Spreadsheet. Untuk contoh ini, Anda akan membuat makro yang memformat baris header untuk data Anda. Cukup ikuti langkah-langkah berikut:

1. Klik sel A1 untuk menempatkan kursor di baris. Ini adalah baris header Anda.
2. Di menu, pilih Ekstensi > Makro > Rekam Makro.

Setelah Anda mulai merekam, Google Spreadsheet akan mengingat setiap tindakan yang dilakukan dalam spreadsheet: menandai sel, menambahkan data, beralih ke sheet, pemformatan, dan lainnya yang berbeda. Tindakan ini menjadi ‘skrip' yang berulang setelah Anda menyimpan dan mengaktifkan makro nanti.

3. Pada dialog Makro, pilih Referensi relatif.

Istilah Penting: Makro dapat menggunakan dua jenis referensi di Spreadsheet untuk merujuk ke sel tertentu. Referensi absolut ditetapkan ke lokasi persis yang direkam (misalnya, sel A5), sementara referensi relatif diterapkan menggunakan pilihan pengguna saat ini sebagai titik awal (misalnya, sel keempat turun dari pilihan saat ini).

Codelab ini meminta Anda untuk menggunakan referensi relatif untuk makro Anda.

4. Pilih baris 1.

5. Warnai ulang baris atas Isi Warna dari putih menjadi magenta gelap 3.

6. Ubah Warna Teks baris atas dari hitam menjadi putih.

7. Untuk menebalkan teks, tekan Ctrl+B (atau Cmd+B pada macOS).
8. Untuk membekukan baris teratas, pilih Lihat > Bekukan > 1 baris

9. Klik Simpan dalam dialog makro. Dialog baru akan meminta Anda memberi nama makro. Masukkan nama "Header" dan klik Simpan.

Dengan menggunakan antarmuka pengguna Spreadsheet, Anda telah membuat makro khusus untuk memformat header.

Mengaktifkan makro Anda

Anda dapat menerapkan makro baru di Spreadsheet dengan mengikuti petunjuk ini:

1. Untuk membuat sheet, klik Tambahkan Sheet .

2. Di sheet baru, tambahkan teks ke A1:C2. Jangan ragu untuk mengikuti contoh input di bawah:

3. Tandai baris pertama.

4. Untuk menerapkan makro ke area yang dipilih, klik Ekstensi> Makro> Header.
5. Otorisasi makro dengan mengikuti petunjuk di layar.

Catatan: Jika menggunakan akun gmail.com, Anda mungkin juga mendapatkan dialog aplikasi yang belum diverifikasi saat pertama kali menggunakan skrip. Google menggunakan ini untuk memperingatkan pengguna yang mungkin menggunakan kode dari penulis yang tidak dikenal atau tidak tepercaya. Jika Anda melihat dialog ini, tidak apa-apa untuk melanjutkan karena Anda adalah penulis skripnya. Ikuti petunjuk di layar untuk terus mengotorisasi skrip. Proses mendapatkan izin ini disebut otorisasi.

6. Ulangi Langkah 4 untuk menjalankan makro lagi (mengotorisasinya akan menghentikan eksekusi pertama).

Selamat, Anda telah mempelajari cara menerapkan makro di Spreadsheet. Spreadsheet Anda akan terlihat seperti ini:

Makro memungkinkan Anda membuat spreadsheet secara efisien, dan di bagian berikutnya dari codelab ini, Anda akan mempelajari cara membuat makro menjadi lebih canggih. Ini rahasianya: saat Anda merekam makro, yang sebenarnya Anda lakukan adalah menulis kode Apps Script. Di balik layar, Spreadsheet membuat kode yang cocok dengan tindakan makro. Di bagian berikutnya, Anda akan mempelajari cara memodifikasi kode secara langsung menggunakan editor dalam aplikasi Apps Script.

4. Makro di editor skrip

Saat Anda membuat makro, Google Spreadsheet akan menyimpan tindakan Anda sebagai fungsi Apps Script. Saat Anda mengaktifkan makro, Google Spreadsheet akan memanggil fungsi Apps Script untuk menerapkan tindakan tersebut dalam urutan yang sama.

Editor skrip

Setelah membuat makro, Anda dapat melihat kodenya. Untuk melihat skrip makro, klik Ekstensi > Apps Script untuk membuka editor kode browser untuk Apps Script.

Editor skrip memungkinkan Anda menulis kode di Apps Script dan menjalankan skrip tersebut di server Google.

Catatan: Makro dan skrip yang Anda buat di codelab ini dilampirkan pada file Google Spreadsheet yang dioperasikan, dan dapat diakses kapan saja dari menu Ekstensi > Apps Script di Spreadsheet. Skrip yang dilampirkan ke Google Spreadsheet seperti ini disebut penampung terikat.

Analisis macro.gs

Tinjau skrip saat ini. Spreadsheet membuat file skrip macros.gs saat Anda merekam makro Header, mengisinya dengan fungsi Apps Script yang sesuai yang disebut Header. Saat Anda mengaktifkan makro Header, Spreadsheet akan menjalankan fungsi ini.

Lihat gambar di bawah ini untuk memahami struktur fungsi makro di Apps Script. Jika Anda mencatat langkah dalam urutan yang berbeda, atau mengklik di sekitar spreadsheet saat merekam, kode Anda mungkin terlihat sedikit berbeda dari ini.

Baris pertama adalah komentar anotasi yang memengaruhi otorisasi:

/** @OnlyCurrentDoc */

Sebagian besar skrip meminta izin kepada pengguna sebelum dapat berjalan. Izin ini mengontrol tindakan yang diizinkan oleh pengguna untuk melakukan skrip. Jika komentar @OnlyCurrentDoc ada dalam project skrip, Apps Script hanya meminta izin untuk mengakses dan memperbarui spreadsheet saat ini. Tanpa komentar ini, Apps Script akan meminta izin untuk mengakses dan memperbarui semua spreadsheet pengguna. Praktik terbaiknya adalah selalu menyertakan anotasi ini saat Anda hanya menggunakan satu file. Perekam makro menambahkan komentar ini secara otomatis untuk Anda.

Untuk memahami cara Apps Script merepresentasikan petunjuk makro, Anda dapat melihat fungsinya:

function Header(){
  var spreadsheet = SpreadsheetApp.getActive();
  var sheet = spreadsheet.getActiveSheet();
  sheet.getRange(
    spreadsheet.getCurrentCell().getRow(),
    1, 1, sheet.getMaxColumns()).activate();
  spreadsheet.getActiveRangeList().setBackground('#4c1130')
  .setFontColor('#ffffff')
  .setFontWeight('bold');
  spreadsheet.getActiveSheet().setFrozenRows(1);
};

Kode ini berjalan saat Anda mengaktifkan makro Header. Setelah function, label Header() akan menentukan nama fungsi dan parameternya. Perlu diketahui bahwa Header() tidak memerlukan parameter karena fungsi makro di Apps Script tidak memerlukan input. Kurung kurawal selalu menyertakan isi fungsi dalam Apps Script.

Codelab berikutnya dalam playlist ini menjelaskan class dan konsep yang diperlukan dalam membuat makro. Untuk saat ini, Anda dapat melihat deskripsi kode berikut untuk mendapatkan gambaran umum tentang komponen dan perannya dalam membuat makro. Perhatikan baris pertama:

var spreadsheet = SpreadsheetApp.getActive();

Di sini, getActive() menampilkan objek yang merepresentasikan file spreadsheet aktif saat ini di Spreadsheet dan menetapkannya ke variabel baru spreadsheet.

var sheet = spreadsheet.getActiveSheet();
sheet.getRange(
    spreadsheet.getCurrentCell().getRow(),
    1, 1, sheet.getMaxColumns()).activate();

Baris ini sesuai dengan tindakan mengklik baris pertama untuk menandainya. Hal ini disebut aktivasi. Baris pertama menyimpan sheet saat ini di variabel sheet, sedangkan baris kedua mendapatkan seluruh baris pertama menggunakan metode getRange(), lalu memanggil activate() untuk mengaktifkannya. Baris pertama ditentukan menggunakan nomor baris dan kolom tertentu. Panggilan spreadsheet.getCurrentCell().getRow() menampilkan jumlah baris saat ini, sementara sheet.getMaxColumns() menampilkan jumlah maksimum kolom dalam sheet.

spreadsheet.getActiveRangeList().setBackground('#4c1130')
.setFontColor('#ffffff')
.setFontWeight('bold');

Bagian kode ini menjadi lebih kompleks. Untuk memanggil metode dengan efisien menggunakan spreadsheet, kode menumpuk tiga metode ke getActiveRangeList() untuk mencegah kode memanggil metode spreadsheet ini secara berlebihan lebih dari sekali. Saat Anda lebih sering membuat kode menggunakan Apps Script, Anda akan lebih memahami konvensi pemanggilan beberapa metode ini di satu kelas (juga dikenal sebagai perantaian metode). Untuk saat ini, Anda dapat membaca penjelasan berikut untuk penjelasan singkat tentang setiap metode dalam blok kode:

• getActiveRangeList() menampilkan RangeList aktif saat ini di spreadsheet. Dalam kasus ini, hanya baris pertama yang diaktifkan baris sebelumnya.
• Baik metode setBackground(color) maupun setFontColor(color) mengubah atribut warna sel dalam rentang aktif.
• setFontWeight(fontWeight) menyesuaikan ketebalan font untuk sel dalam rentang aktif.

Terakhir, baris terakhir membekukan baris pertama makro:

spreadsheet.getActiveSheet().setFrozenRows(1);

Dan itulah skrip yang Anda buat saat merekam makro. Jangan khawatir tentang istilah atau metode yang tidak dikenal di atas. Deskripsi ini dimaksudkan untuk membantu Anda memikirkan beberapa ide yang menjadi fokus Apps Script dalam fungsi makro umum, dan topik yang akan dibahas oleh codelab di masa mendatang.

Bagian berikutnya berfokus pada memanipulasi kode fungsi Header() untuk menunjukkan bagaimana Anda dapat menggunakan editor skrip untuk mempersonalisasi makro lebih lanjut.

Menyesuaikan makro dengan Apps Script

Editor Apps Script menampilkan makro yang sebelumnya Anda buat di Google Spreadsheet. Dengan menyesuaikan konten bagian fungsi, Anda dapat menyesuaikan lebih lanjut petunjuk makro untuk melakukan berbagai tindakan atau tindakan tambahan. Latihan berikut menunjukkan berbagai cara untuk memanipulasi makro dengan editor skrip.

Mengubah sel yang terpengaruh

Misalnya, Anda ingin mengubah makro sehingga hanya memengaruhi 10 kolom pertama baris pertama, bukan seluruh baris. Anda dapat menghapus makro ini dan merekamnya ulang. Namun, dengan menggunakan editor Apps Script, Anda dapat membuat perubahan tersebut secara langsung. Berikut salah satu cara melakukannya:

1. Di editor skrip, ganti sheet.getMaxColumns() dengan 10. Pengeditan ini mengubah rentang sel yang dipengaruhi makro di spreadsheet.

/** @OnlyCurrentDoc */

function Header(){
  var spreadsheet = SpreadsheetApp.getActive();
  var sheet = spreadsheet.getActiveSheet();
  sheet.getRange(
    spreadsheet.getCurrentCell().getRow(),
    1, 1, 10).activate();
    /* sheet.getMaxColumns() replaced with 10.*/
  spreadsheet.getActiveRangeList().setBackground('#4c1130')
  .setFontColor('#ffffff')
  .setFontWeight('bold');
  spreadsheet.getActiveSheet().setFrozenRows(1);
}

2. Untuk menyimpan skrip, klik Simpan .
3. Untuk mengganti nama project Anda, masukkan "Makro dan Fungsi Kustom" sebagai nama project baru dan klik Ganti nama.
4. Untuk membuat sheet, klik Tambahkan Spreadsheet di Spreadsheet.

5. Di editor skrip, dari daftar fungsi, pilih Header lalu klik Jalankan.

Di sheet baru, Anda akan melihat hasil berikut:

Dengan mengubah rentang aktif atau target, makro Anda kini hanya memengaruhi sebagian baris pertama. Banyak metode Apps Script yang menggunakan rentang atau notasi A1 sebagai parameter untuk menentukan sel yang akan ditindaklanjuti.

Berikutnya, mari kita pelajari cara menyesuaikan warna makro Anda.

Mengubah warna makro Anda

Untuk membantu Anda mendesain skema warna makro atau elemen lain di Spreadsheet, Apps Script dapat mengubah warna isi atau teks rentang. Ikuti petunjuk berikut untuk mempelajari cara menyesuaikan warna makro Anda.

Petunjuk ini berfokus pada cara mengubah warna latar belakang makro Anda:

1. Di Spreadsheet, beralihlah kembali ke sheet yang berisi data asli (Sheet 1).
2. Klik baris pertama untuk menandainya.
3. Di editor skrip, ganti warna latar belakang #4c1130 dengan #afeeee. Nilai ini mewakili warna yang berbeda menggunakan notasi triplet hex.

/** @OnlyCurrentDoc */

function Header(){
  var spreadsheet = SpreadsheetApp.getActive();
  var sheet = spreadsheet.getActiveSheet();
  sheet.getRange(
    spreadsheet.getCurrentCell().getRow(),
    1, 1, 10).activate();
  spreadsheet.getActiveRangeList().setBackground('#afeeee')
    /* #4c1130 replaced with #afeeee.*/
  .setFontColor('#ffffff')
  .setFontWeight('bold');
  spreadsheet.getActiveSheet().setFrozenRows(1);
}

4. Untuk menyimpan skrip, klik Simpan .
5. Dari daftar fungsi, pilih Header lalu klik Run.

Di Spreadsheet, pengisian latar 10 kolom pertama di baris pertama diwarnai ulang menjadi warna biru kehijauan khusus:

Dengan mengalihkan notasi warna hex di parameter setBackground(color) dari #4c1130 (magenta gelap 3) ke #afeeee (pirus pucat, opsi yang tidak dapat diakses di menu warna default Spreadsheet), Anda mengubah atribut warna makro warna latar belakang.

Anda sekarang telah mengubah warna latar belakang yang ditetapkan oleh makro Anda. Jika Anda juga ingin mengubah warna teks, ubah kode warna kedua.

1. Di Spreadsheet, klik baris pertama untuk memastikan baris tersebut masih ditandai.
2. Di editor skrip, ganti warna font #ffffff dengan #191970. Ini akan menyebabkan makro menetapkan warna font biru laut.

/** @OnlyCurrentDoc */

function Header(){
  var spreadsheet = SpreadsheetApp.getActive();
  var sheet = spreadsheet.getActiveSheet();
  sheet.getRange(
    spreadsheet.getCurrentCell().getRow(),
    1, 1, 10).activate();
  spreadsheet.getActiveRangeList().setBackground('#afeeee')
  .setFontColor('#191970')/* #ffffff replaced with #191970.*/
  .setFontWeight('bold');
  spreadsheet.getActiveSheet().setFrozenRows(1);
}

3. Untuk menyimpan skrip, klik Simpan .
4. Dari daftar fungsi, pilih Header lalu klik Run.

Kembali ke Spreadsheet untuk melihat warna teks baris header kini berwarna biru dongker.

Sekarang Anda telah melihat bagaimana makro sebenarnya tindakan Spreadsheet dicatat sebagai kode Apps Script. Di bagian berikutnya, Anda dapat melihat cara lain Apps Script dapat membantu Anda bekerja dengan Google Spreadsheet: fungsi kustom.

5. Membuat kode skrip pertama: Fungsi kustom

Seperti sebagian besar aplikasi spreadsheet, Google Spreadsheet memiliki beberapa fungsi formula bawaan seperti =SUM() yang memungkinkan penghitungan cepat pada data spreadsheet. Fungsi khusus hanyalah fungsi yang Anda tentukan menggunakan Apps Script. Setelah menentukan fungsi khusus, Anda dapat menggunakannya di mana pun di spreadsheet, seperti fungsi bawaan.

Bagian ini menunjukkan cara membuat fungsi kustom di Apps Script yang melakukan konversi uang.

Membuat file skrip

Menggunakan spreadsheet dan project skrip yang sama dari bagian Makro, ikuti petunjuk ini untuk mempelajari cara membuat skrip baru (yang pada akhirnya dapat Anda gunakan untuk membuat fungsi kustom pertama Anda):

1. Untuk membuat file Apps Script, kembali ke editor skrip.
2. Di samping File, klik Tambahkan file > Skrip.
3. Beri nama file skrip baru customFunctions lalu tekan Enter. (Apps Script secara otomatis menambahkan ekstensi .gs ke nama file skrip.)

Tab baru bernama customFunctions.gs akan muncul dalam editor.

Setelah membuat skrip khusus untuk fungsi khusus, Anda dapat mengisinya dengan kode.

Mengonversi dolar AS ke franc Swiss

Misalkan Anda ingin mengubah data untuk '10 Film Terlaris Teratas 2018' untuk menunjukkan tidak hanya nilai kotor di seluruh dunia dalam dolar AS tetapi juga dalam franc Swiss. Dengan fungsi khusus, Anda dapat melakukannya dengan mudah. Latihan berikut menunjukkan cara membuat fungsi khusus untuk mengonversi nilai dolar Anda menjadi nilai franc.

Sebelum Anda dapat menulis fungsi kustom pertama, ubah set data untuk mengizinkan fungsi tersebut mendemonstrasikan output yang tepat. Untuk melakukan ini:

1. Di Spreadsheet, klik kanan kolom H.
2. Pada menu yang dihasilkan, klik Sisipkan 1 di kanan.

3. Beri label kolom "Worldwide_Gross (Franc Swiss)" dalam sel I1.

Sekarang Anda memiliki kolom yang dapat menyimpan hasil fungsi kustom konversi Anda. Selanjutnya, Anda dapat menggunakan editor skrip untuk membuat fungsi khusus pertama.

4. Di customFunctions.gs, ganti kode untuk myFunction() dengan kode berikut:

/**
 * Converts US dollars to Swiss francs.
 *
 * @param {number} dollars The total number of dollars.
 * @return {number} swissFrancs The converted total of Swiss francs.
 * @customfunction
 */
function USDTOCHF(dollars){
  var swissFrancs = dollars * .99; 
  return swissFrancs;
}

Ini adalah kode yang akan mengonversi dolar AS ke franc Swiss. Coba petunjuk di bawah, dan lihat cara menjalankan fungsi kustom di spreadsheet.

5. Untuk menyimpan skrip, klik Simpan .
6. Di Spreadsheet, pilih sel I2.
7. Di panel fungsi, masukkan =USDTOCHF(H2).

Untuk menerapkan formula ke sel lainnya di kolom:

8. Arahkan kursor ke pojok kanan bawah sel I2, lalu pilih kotak biru kecil (kursor akan berubah menjadi saat menunjuk ke kotak biru).
9. Tarik kotak biru ke bawah untuk menandai rentang I3:I11.

Kolom I kini mencantumkan konversi franc Swiss dari nilai dolar AS ke Kolom H.

Selamat, Anda telah membuat fungsi kustom pertama Anda. Bagian berikutnya menjelaskan kode yang terdiri dari USDTOCHF().

Analisis USDTOCHF()

Komentar awal menjelaskan tujuan kode tersebut:

/**
 * Converts US dollars to Swiss francs.
 *
 * @param {number} dollars The total number of dollars.
 * @return {number} swissFrancs The provided value in Swiss francs.
 * @customfunction
 */

Blok komentar seperti ini sering digunakan dalam pemrograman untuk menjelaskan fungsi fungsi tersebut.

Dalam komentar ini, Anda dapat mengidentifikasi dua bagian: deskripsi fungsi (untuk mengonversi dolar ke franc) dan anotasi yang menjelaskan parameter fungsi serta jenis nilai yang ditampilkan.

Dengan anotasi, Apps Script menggunakan JSDoc untuk membantu Anda mendokumentasikan dan membuat petunjuk pelengkapan otomatis untuk kode Anda. Di bawah, Anda dapat membaca bagaimana setiap anotasi yang digunakan dalam USDTOCHF() membantu Anda mengembangkan Apps Script:

• @param: Anda dapat menggunakan anotasi @param untuk mendeskripsikan setiap parameter yang diteruskan ke fungsi.
• @return: Anda dapat menggunakan anotasi @return untuk mendeskripsikan fungsi yang ditampilkan fungsi.
• @customfunction: Anda harus selalu menambahkan @customfunction dalam komentar dokumen fungsi kustom apa pun. Anotasi ini memberi tahu Spreadsheet untuk melengkapi otomatis fungsi kustom Anda seperti Spreadsheet melengkapi fungsi bawaan saat Anda memasukkan nama fungsi dalam sel seperti yang terlihat di bawah ini:

Perhatikan bahwa teks yang muncul di pop-up pelengkapan otomatis sama persis dengan teks deskripsi yang Anda tempatkan di blok komentar. Anda dapat mempermudah fungsi kustom Anda dengan memastikan deskripsi yang Anda buat ditulis dengan baik dan lengkap.

Selanjutnya, fokuskan pada kode dalam fungsi USDTOCHF():

function USDTOCHF(dollars){
  var swissFrancs = dollars * .99; 
  return swissFrancs;
}

Seperti yang disebutkan sebelumnya, USDTOCHF() mengambil dolar variabel numerik, mengalikannya dengan nilai tukar tetap, dan menampilkan nilai yang dikonversi ke franc Swiss dalam variabel numerik swissFrancs. Parameter input adalah nilai yang terdapat dalam sel yang ditentukan saat menambahkan fungsi kustom ke sel. Dalam contoh ini, jumlah dolar input berasal dari kolom H. Nilai output swissFrancs ditempatkan dalam sel fungsi (kolom I dalam contoh ini).

Fungsi khusus dapat berfungsi dengan nilai numerik atau string, seperti yang akan Anda lihat di bagian berikutnya.

Menggabungkan awalan string

Misalnya Anda ingin output numerik fungsi USDTOCHF() menyertakan awalan franc Swiss CHF. Anda dapat melakukannya dengan Apps Script menggunakan operator penyambungan (+), seperti yang ditunjukkan di petunjuk berikut:

1. Di editor skrip, perbarui anotasi @return untuk menampilkan string, bukan angka.
2. Ubah return swissFrancs menjadi return 'CHF' + swissFrancs.

Operator + menambahkan string CHF ke depan nilai yang ada di swissFrancs. Sekarang kode akan terlihat seperti ini:

/**
 * Converts US dollars to Swiss francs.
 *
 * @param {number} dollars The total number of dollars.
 * @return {string} swissFrancs The provided value in Swiss francs.
 * @customfunction
 */
function USDTOCHF(dollars){
  var swissFrancs = dollars * .99;
  return 'CHF' + swissFrancs;
}

3. Untuk menyimpan skrip, klik Simpan .

String franc Swiss sekarang menjadi awalan nilai kolom I:

Fungsi kustom Anda kini tidak hanya mengonversi dolar AS ke franc Swiss, tetapi juga menampilkan mata uang dengan awalan string.

Lanjutan: Mengambil data eksternal

Ini merupakan awal yang baik untuk fungsi khusus dasar, tetapi contoh ini mengasumsikan nilai tukar untuk dolar ke franc Swiss konstan. Misalnya Anda ingin menggunakan nilai tukar saat ini, jadi setiap kali sheet dimuat ulang, nilai dihitung ulang untuk mewakili konversi saat ini. Untuk melakukannya, Anda memerlukan sarana untuk mengetahui nilai tukar saat ini. Informasi itu belum tersedia di Google Spreadsheet, tetapi untungnya Anda bisa menggunakan Apps Script untuk mendapatkannya.

Anda dapat menggunakan kode seperti di bawah ini untuk mendapatkan rasio konversi franc Swiss saat ini ke dolar AS:

function USDTOCHF(dollars){
  // Gets a cache that is common to all users of the script.
  var cache = CacheService.getScriptCache();

  // Accesses the memory location (rates.CHF) of the script cache.
  var rate = cache.get('rates.CHF');

  // If a cache miss occurs, the program fetches the current
  // CHF rate from an API and stores the rate in the cache
  // for later convenience.
  if (!rate) {
    var response =
UrlFetchApp.fetch('https://api.exchangeratesapi.io/latest?base=USD');
    var result = JSON.parse(response.getContentText());
    rate = result.rates.CHF;
    cache.put('rates.CHF', rate);
  }
  // Converts dollars to CHF according to the latest rate.
  var swissFrancs = dollars * rate;
  // Returns the CHF value.
  return 'CHF' + swissFrancs;
}

Kode ini mengambil nilai tukar saat ini dari server informasi keuangan menggunakan API nilai tukar pihak ketiga. Ini dilakukan menggunakan layanan Apps Script seperti UrlFetchApp dan CacheService. Konsep lanjutan tersebut berada di luar cakupan codelab khusus ini, tetapi Anda dapat mulai melihat keserbagunaan Apps Script untuk mengotomatiskan tugas kompleks di Google Spreadsheet.

Pedoman fungsi khusus

Selamat telah menyelesaikan latihan untuk fungsi khusus. Saat menggunakan fungsi kustom di project Anda, penting untuk memahami bahwa fungsi tersebut memiliki batasan tertentu. Daftar berikut merangkum batasan yang dijelaskan dalam panduan Fungsi Kustom di Google Spreadsheet:

• Jangan buat fungsi khusus yang memerlukan otorisasi pengguna. Buat fungsi kustom untuk memenuhi tugas yang lebih sederhana seperti penghitungan data sampel, pengeditan teks, dll. Buka Menggunakan layanan Apps Script.
• Jangan beri nama fungsi kustom sama dengan fungsi bawaan lainnya, atau akhiri nama dengan garis bawah. Tinjau Panduan penamaan.
• Jangan teruskan argumen variabel ke fungsi kustom. Anda hanya dapat meneruskan nilai deterministik (tetap) ke fungsi kustom sebagai argumen. Meneruskan argumen variabel, seperti hasil =RAND(), akan merusak fungsi kustom. Lihat Panduan argumen.
• Jangan membuat fungsi yang memerlukan waktu lebih dari 30 detik untuk diselesaikan. Jika terjadi error lebih lama, biarkan kode fungsi tetap sederhana dan dibatasi cakupannya. Sebaiknya perhitungkan dilakukan dalam fungsi kustom sesederhana mungkin. Lihat Panduan nilai pengembalian.

Sekarang Anda dapat menyempurnakan spreadsheet dengan menggunakan editor skrip untuk bekerja dengan makro dan membuat fungsi kustom. Di bagian berikutnya, Anda dapat meninjau apa yang telah Anda pelajari dan apa yang dapat Anda lakukan selanjutnya untuk meningkatkan keterampilan membuat skrip.

6. Kesimpulan

Anda telah menyelesaikan codelab pertama dari Dasar-Dasar Skrip Aplikasi dengan Google Spreadsheet. Dengan membuat dan mengedit makro Spreadsheet serta fungsi kustom, Anda telah mempelajari konsep dasar Apps Script. Anda dapat memperluas pengetahuan Apps Script lebih lanjut di codelab berikutnya.

Apakah codelab ini bermanfaat bagi Anda?

Ya Tidak

Yang telah kita bahas

• Konsep Apps Script dasar.
• Cara menavigasi editor skrip.
• Cara membuat dan mengupdate makro Spreadsheet.
• Cara membuat fungsi kustom untuk Google Spreadsheet.

Istilah Utama

• Referensi absolut: Setelan perekaman makro yang menentukan tindakan makro yang direkam diterapkan ke sel persis yang digunakan dalam rekaman.
• Aktif (status): Menunjukkan spreadsheet, sheet, rentang, atau sel yang ditentukan adalah spreadsheet yang sedang dilihat atau disoroti oleh pengguna spreadsheet.
• Apps Script: Platform pengembangan aplikasi yang cepat, berdasarkan JavaScript, yang mempercepat dan mempermudah perluasan aplikasi Google Workspace serta mengotomatiskan pekerjaan.
• Otorisasi: Proses pengguna memberikan izin untuk mengizinkan Apps Script mengakses data pengguna di layanan Google yang relevan atau melakukan tindakan atas nama pengguna.
• Skrip yang terikat dengan penampung: Skrip apa pun yang terikat dan dibuat dari dokumen Google Workspace, seperti Google Spreadsheet atau Google Dokumen.
• Fungsi kustom: Formula yang ditentukan pengguna di Apps Script yang digunakan dalam spreadsheet untuk operasi sederhana.
• JSDoc: Bahasa markup yang digunakan untuk menulis catatan penjelasan pada file sumber berbasis JavaScript.
• Makro: Singkatan dari "macroinstruction". Rangkaian tindakan Google Spreadsheet yang direkam dan dapat Anda ulangi menggunakan item menu atau tombol pintasan.
• Perantaian metode: Idiom pemrograman untuk memanggil beberapa panggilan metode pada objek, mengandalkan fakta bahwa setiap panggilan metode menampilkan objek.
• Rentang: Grup dari satu atau beberapa sel yang berdekatan dalam sheet.
• Referensi relatif: Setelan perekaman makro yang menentukan tindakan makro yang direkam diterapkan ke sel relatif terhadap pilihan sel saat ini.
• Editor skrip: Editor kode dalam browser untuk Apps Script.
• Sheet: Satu halaman spreadsheet (mirip dengan workbook Microsoft Excel). Terkadang digunakan untuk merujuk ke file Google Spreadsheet dalam Google Drive.
• SpreadsheetApp: Class ini berfungsi sebagai class induk untuk layanan Spreadsheet dan menyediakan titik awal untuk kode yang membaca atau memanipulasi data Google Spreadsheet.
• Spreadsheet: File Google Spreadsheet yang berada dalam Google Drive.
• Layanan spreadsheet: Layanan Apps Script yang memungkinkan skrip membuat, mengakses, dan mengubah file Google Spreadsheet.

Pelajari Apps Script lebih lanjut di dokumentasi Apps Script.

Apa selanjutnya

Codelab berikutnya dalam playlist ini menyajikan class inti dan terminologi dari layanan Spreadsheet Apps Script. Layanan ini memungkinkan Anda mengontrol nilai dan presentasi data di Google Spreadsheet dengan baik menggunakan Apps Script.

Temukan codelab berikutnya di Spreadsheet, Spreadsheet, dan Rentang.