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 software pengembangan kode.
• Anda dapat mendesain antarmuka pengguna untuk editor Google Workspace yang memungkinkan Anda mengaktifkan skrip langsung dari editor tersebut menggunakan item menu, dialog, dan sidebar.

Playlist codelab Dasar-Dasar Apps Script 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 tenaga. Apps Script menyediakan layanan Spreadsheet yang memungkinkan skrip berinteraksi dengan file Google Spreadsheet Anda dan data di dalamnya. Anda dapat menggunakan layanan ini untuk mengotomatiskan tugas spreadsheet umum berikut:

• Buat atau ubah spreadsheet.
• Membaca dan memperbarui data, formula, dan pemformatan sel.
• Buat tombol dan menu kustom.
• Mengimpor dan mengekspor data dari aplikasi Google lain atau sumber pihak ketiga.
• Membagikan 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, Sheet, dan Rentang
3. Menangani data
4. Pemformatan data
5. Membuat diagram dan mempresentasikan data di Slide

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

Lanjutkan ke bagian berikutnya untuk mempelajari lebih lanjut isi codelab ini.

2. Pengantar

Selamat datang di codelab pertama dalam 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. Mirip dengan fungsi bawaan yang ditawarkan Spreadsheet (seperti SUM atau AVERAGE), Anda dapat menggunakan Apps Script untuk menulis fungsi kustom Anda sendiri untuk operasi sederhana dan khusus (seperti konversi atau penggabungan string). Setelah dibuat, Anda dapat memanggil fungsi ini di Spreadsheet seperti memanggil fungsi bawaan. Fungsi kustom juga dapat digunakan dalam formula sel yang Anda tulis, menggabungkannya dengan fungsi lain sesuai kebutuhan.

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

Yang akan Anda pelajari

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

Yang Anda butuhkan

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

Catatan: Apps Script didasarkan pada JavaScript. Jika Anda baru menggunakan JavaScript, Codecademy menawarkan kursus Introductory JavaScript gratis. Meskipun Google tidak membuat kursus ini, kursus ini akan mencakup semua hal yang perlu Anda ketahui.

Anda telah menyelesaikan pengantar. Buka bagian berikutnya untuk mulai menggunakan makro.

3. Membuat makro di Spreadsheet

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

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

Sebelum memulai

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

Salinan contoh spreadsheet yang dapat Anda gunakan ditempatkan di folder Google Drive Anda dan diberi nama "Salinan 10 Film dengan Pendapatan Tertinggi (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 Anda lakukan dalam spreadsheet: menandai sel, menambahkan data, beralih ke sheet lain, memformat, dan sebagainya. Tindakan ini akan menjadi 'skrip' yang diulang setelah Anda menyimpan dan mengaktifkan makro nanti.

3. Dalam dialog Makro, pilih Referensi relatif.

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

Codelab ini meminta Anda menggunakan referensi relatif untuk makro.

4. Pilih baris 1.

5. Ubah warna Warna Pengisi baris atas 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 di macOS).
8. Untuk membekukan baris atas, pilih Tampilan > Bekukan > 1 baris.

9. Klik Simpan di dialog makro. Dialog baru akan meminta Anda memberi nama makro. Masukkan nama "Header", lalu klik Simpan.

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

Mengaktifkan makro

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

1. Untuk membuat sheet, klik Tambahkan Sheet .

2. Di sheet baru, tambahkan beberapa teks ke A1:C2. Anda dapat mengikuti contoh input di bawah:

3. Tandai baris pertama.

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

Catatan: Jika Anda menggunakan akun gmail.com, Anda juga dapat melihat dialog aplikasi yang tidak terverifikasi saat pertama kali menggunakan skrip. Google menggunakan informasi ini untuk memperingatkan pengguna yang mungkin menggunakan kode dari penulis yang tidak dikenal atau tidak tepercaya. Jika Anda melihat dialog ini, Anda dapat melanjutkan karena Anda adalah penulis skrip. Ikuti perintah di layar untuk melanjutkan pemberian otorisasi skrip. Proses untuk mendapatkan izin ini disebut otorisasi.

6. Ulangi Langkah 4 untuk menjalankan makro lagi (mengizinkannya 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 yang lebih canggih. Berikut rahasianya: saat 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 mengubah kode secara langsung menggunakan editor dalam browser 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 dalam codelab ini dilampirkan ke file Google Spreadsheet tempat makro dan skrip tersebut beroperasi, dan dapat diakses kapan saja dari menu Ekstensi > Apps Script Spreadsheet. Skrip yang dilampirkan ke Google Spreadsheet seperti ini disebut terikat ke penampung.

Analisis macros.gs

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

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

Baris pertama adalah komentar anotasi yang memengaruhi otorisasi:

/** @OnlyCurrentDoc */

Sebagian besar skrip meminta beberapa izin pengguna sebelum dapat dijalankan. Izin ini mengontrol apa yang diizinkan pengguna untuk dilakukan 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. Selalu merupakan praktik terbaik untuk menyertakan anotasi ini saat Anda hanya bekerja dengan satu file. Perekam makro akan menambahkan komentar ini secara otomatis untuk Anda.

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

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() menentukan nama fungsi dan parameternya. Perhatikan bahwa Header() tidak memerlukan parameter karena fungsi makro di Apps Script tidak memerlukan input. Kurung kurawal selalu mengapit isi fungsi di Apps Script.

Codelab selanjutnya dalam playlist ini menjelaskan class dan konsep yang terlibat dalam pembuatan makro. Untuk saat ini, Anda dapat membaca deskripsi kode berikut untuk mendapatkan gambaran umum tentang komponennya dan perannya dalam menyusun makro. Pertimbangkan baris pertama:

var spreadsheet = SpreadsheetApp.getActive();

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

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

Baris ini sesuai dengan tindakan mengklik baris pertama untuk menandainya. Tindakan ini disebut aktivasi. Baris pertama menyimpan sheet saat ini dalam 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, sedangkan 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 secara efisien dengan spreadsheet, kode menumpuk tiga metode ke getActiveRangeList() untuk mencegah kode memanggil metode spreadsheet ini lebih dari sekali secara berlebihan. Saat Anda menulis lebih banyak kode menggunakan Apps Script, Anda akan lebih memahami konvensi pemanggilan beberapa metode pada satu class ini (juga dikenal sebagai penggabungan metode). Untuk saat ini, Anda dapat membaca penjelasan singkat tentang setiap metode dalam blok kode berikut:

• getActiveRangeList() menampilkan RangeList aktif saat ini di spreadsheet. Dalam hal ini, cukup baris pertama yang diaktifkan oleh baris sebelumnya.
• Metode setBackground(color) dan 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 dengan istilah atau metode yang tidak Anda kenal yang disebutkan di atas. Deskripsi ini dimaksudkan untuk membuat Anda memikirkan beberapa ide yang menjadi fokus Apps Script dalam fungsi makro umum, dan topik yang akan dibahas dalam codelab mendatang.

Bagian berikutnya berfokus pada manipulasi kode fungsi Header() untuk menunjukkan cara menggunakan editor skrip guna mempersonalisasi makro lebih lanjut.

Menyesuaikan makro dengan Apps Script

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

Mengubah sel yang terpengaruh

Misalkan Anda ingin mengubah makro agar hanya memengaruhi 10 kolom pertama dari baris pertama, bukan seluruh baris. Anda dapat menghapus makro 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 dalam 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, masukkan "Macros and Custom Functions" sebagai nama project baru, lalu klik Rename.
4. Untuk membuat sheet, di Spreadsheet, klik Tambahkan Sheet .

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 menggunakan rentang atau notasi A1 sebagai parameter untuk menentukan sel mana yang akan ditindaklanjuti.

Selanjutnya, 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 teks atau pengisi rentang. Ikuti petunjuk berikut untuk mempelajari cara menyesuaikan warna makro.

Petunjuk ini berfokus pada perubahan warna latar belakang makro Anda:

1. Di Spreadsheet, beralih 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 merepresentasikan warna yang berbeda menggunakan notasi triplet heksadesimal.

/** @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 Jalankan.

Di Spreadsheet, pengisian latar belakang 10 kolom pertama di baris pertama diwarnai ulang menjadi warna pirus kustom:

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

Anda kini telah mengubah komposisi warna latar belakang dengan makro. Jika Anda ingin mengubah warna teks juga, ubah kode warna kedua.

1. Di Spreadsheet, klik baris pertama untuk memastikan baris tersebut masih disorot.
2. Di editor skrip, ganti warna font #ffffff dengan #191970. Hal ini menyebabkan makro menetapkan warna font biru tua.

/** @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 Jalankan.

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

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

5. Mengodekan skrip pertama Anda: Fungsi kustom

Seperti kebanyakan aplikasi spreadsheet, Google Spreadsheet memiliki beberapa fungsi formula bawaan seperti =SUM() yang memungkinkan perhitungan cepat pada data spreadsheet. Fungsi kustom hanyalah fungsi yang Anda tentukan menggunakan Apps Script. Setelah menentukan fungsi kustom, Anda dapat menggunakannya di mana saja dalam spreadsheet, seperti fungsi bawaan.

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

Membuat file skrip

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

1. Untuk membuat file Apps Script, kembali ke editor skrip.
2. Di samping Files, klik Tambahkan file > Script.
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 di dalam editor.

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

Konversi dolar AS ke franc Swiss

Misalnya, Anda ingin mengubah data untuk '10 Film Terlaris 2018' agar menampilkan tidak hanya nilai kotor di seluruh dunia dalam dolar AS, tetapi juga dalam franc Swiss. Dengan fungsi kustom, Anda dapat melakukannya dengan mudah. Latihan berikut menunjukkan cara membuat fungsi kustom untuk mengonversi nilai dolar Anda ke nilai franc secara matematis.

Sebelum Anda dapat menulis fungsi kustom pertama, ubah set data Anda agar fungsi dapat menunjukkan output yang tepat. Untuk melakukannya:

1. Di Spreadsheet, klik kanan kolom H.
2. Di menu yang muncul, klik Sisipkan 1 kanan.

3. Beri label pada kolom "Worldwide_Gross (Swiss francs)" di sel I1.

Sekarang Anda memiliki kolom yang dapat menyimpan hasil fungsi kustom konversi. Selanjutnya, Anda dapat menggunakan editor skrip untuk membuat fungsi kustom 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 kolom 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 Anda akan berubah menjadi saat mengarah 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 di Kolom H.

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

Analisis USDTOCHF()

Komentar awal menjelaskan tujuan kode:

/**
 * 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 yang dilakukan.

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

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

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

Perhatikan teks yang muncul di pop-up pelengkapan otomatis sama persis dengan teks deskripsi yang Anda masukkan di blok komentar. Anda dapat membuat fungsi kustom lebih mudah digunakan dengan memastikan deskripsi yang Anda buat ditulis dengan baik dan lengkap.

Selanjutnya, fokus pada kode dalam fungsi USDTOCHF():

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

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

Fungsi kustom 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 penggabungan (+), seperti yang ditunjukkan dalam 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 bagian depan nilai yang ada dalam 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 kini menambahkan awalan pada nilai kolom I:

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

Lanjutan: Mengambil data eksternal

Ini adalah awal yang baik untuk fungsi kustom dasar, tetapi contoh ini mengasumsikan nilai tukar dolar ke franc Swiss konstan. Misalnya, Anda ingin menggunakan nilai tukar saat ini, sehingga setiap kali sheet dimuat ulang, nilai akan dihitung ulang untuk merepresentasikan konversi saat ini. Untuk melakukannya, Anda memerlukan cara untuk mengetahui nilai tukar saat ini. Informasi tersebut tidak tersedia di Google Spreadsheet, tetapi Anda dapat menggunakan Apps Script untuk mendapatkannya.

Anda dapat menggunakan kode seperti di bawah ini untuk mendapatkan nilai tukar saat ini dari franc Swiss 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. Hal 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 fleksibilitas Apps Script untuk mengotomatiskan tugas kompleks di Google Spreadsheet.

Panduan fungsi kustom

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

• Jangan membuat fungsi kustom yang memerlukan otorisasi pengguna. Sebaliknya, buat fungsi kustom Anda untuk menyelesaikan tugas yang lebih sederhana seperti perhitungan data contoh, pengeditan teks, dll. Buka Menggunakan layanan Apps Script.
• Jangan beri nama fungsi kustom sama dengan fungsi bawaan lain, atau akhiri nama dengan garis bawah. Tinjau Panduan penamaan.
• Jangan meneruskan 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 memerlukan waktu lebih lama, akan terjadi error, jadi buat kode fungsi tetap sederhana dan terbatas cakupannya. Sebaiknya buat penghitungan yang dilakukan dalam fungsi kustom sesederhana mungkin. Lihat Panduan nilai yang ditampilkan.

Sekarang Anda dapat meningkatkan kualitas spreadsheet dengan menggunakan editor skrip untuk menggunakan 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 pembuatan skrip.

6. Kesimpulan

Anda telah menyelesaikan codelab pertama Dasar-Dasar Apps Script dengan Google Spreadsheet. Dengan membuat dan mengedit makro dan fungsi kustom Spreadsheet, 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 dasar Apps Script.
• Cara membuka editor skrip.
• Cara membuat dan memperbarui 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 bahwa spreadsheet, sheet, rentang, atau sel yang ditentukan adalah yang sedang dilihat atau ditandai oleh pengguna spreadsheet.
• Apps Script: Platform pengembangan aplikasi cepat, berbasis JavaScript, yang mempercepat dan mempermudah perluasan aplikasi Google Workspace dan mengotomatiskan pekerjaan.
• Otorisasi: Proses pemberian izin oleh pengguna untuk mengizinkan Apps Script mengakses data pengguna di layanan Google yang relevan atau mengambil tindakan atas nama pengguna.
• Skrip terikat penampung: Skrip apa pun yang terikat ke dan dibuat dari dokumen Google Workspace, seperti Spreadsheet Google atau Dokumen Google.
• 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". Serangkaian tindakan Google Spreadsheet yang direkam dan dapat Anda ulangi menggunakan item menu atau tombol pintasan.
• Merangkai metode: Idiom pemrograman untuk memanggil beberapa panggilan metode pada suatu objek, yang mengandalkan fakta bahwa setiap panggilan metode menampilkan objek.
• Rentang: Sekelompok satu atau beberapa sel yang berdekatan dalam sheet.
• Referensi relatif: Setelan perekaman makro yang menentukan tindakan makro yang direkam diterapkan ke sel yang 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 pada file Google Spreadsheet dalam Google Drive.
• SpreadsheetApp: Class ini berfungsi sebagai class induk untuk layanan Spreadsheet dan memberikan titik awal untuk kode yang membaca atau memanipulasi data Google Spreadsheet.
• Spreadsheet: File Google Spreadsheet yang berada di dalam Google Drive.
• Layanan spreadsheet: Layanan Apps Script yang memungkinkan skrip membuat, mengakses, dan mengubah file Google Spreadsheet.

Pelajari lebih lanjut Apps Script di dokumentasi Apps Script.

Langkah berikutnya

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

Temukan codelab berikutnya di Spreadsheet, Sheet, dan Rentang.