Menggunakan paket JavaScript

Dokumen ini menunjukkan cara melakukan hal berikut:

• Menginstal paket JavaScript di repositori Dataform.
• Mengautentikasi paket NPM pribadi untuk mengaktifkan penginstalannya di repositori.
• Buat paket JavaScript kustom yang dapat Anda gunakan untuk mengembangkan alur kerja.

Sebelum memulai

1. Di konsol Google Cloud , buka halaman Dataform.

   Buka Dataform

2. Lakukan salah satu atau kedua hal berikut:

   1. Untuk menginstal paket di repositori atau mengautentikasi paket NPM pribadi untuk mengaktifkan penginstalannya, ikuti langkah-langkah berikut:
      1. Pilih atau buat repositori.
      2. Pilih atau buat ruang kerja pengembangan.
      3. Opsional: Untuk menginstal paket pribadi, autentikasi paket pribadi.
      4. Jika repositori Anda tidak berisi file package.json, buat package.json dan pindahkan paket inti Dataform.
   2. Untuk membuat paket, ikuti langkah-langkah berikut:
      1. Buat repositori Dataform yang dikhususkan untuk paket Anda. Cocokkan nama repositori dengan nama paket Anda.
      2. Hubungkan repositori ke repositori Git pihak ketiga yang akan menghosting paket Anda.
      3. Buat dan lakukan inisialisasi ruang kerja di repositori Dataform.

3. Pastikan Anda memiliki izin yang diperlukan untuk menyelesaikan tugas dalam dokumen ini.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menyelesaikan tugas dalam dokumen ini, minta administrator untuk memberi Anda peran IAM berikut:

• Dataform Editor (roles/dataform.editor) di ruang kerja dan repositori
• Dataform Admin (roles/dataform.admin) di repositori

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Menginstal paket

Bagian ini menunjukkan cara menginstal paket JavaScript dan mengimpornya ke file JavaScript dan file SQLX sehingga Anda dapat menggunakan paket tersebut untuk mengembangkan alur kerja di Dataform.

Untuk menggunakan paket di Dataform, Anda harus menginstalnya di repositori.

Anda dapat menginstal jenis paket berikut di Dataform:

• Paket NPM publik yang dipublikasikan
• Paket NPM publik yang tidak dipublikasikan
• Paket NPM pribadi yang diautentikasi

Kemudian, untuk menggunakan paket dalam file JavaScript atau SQLX, Anda perlu mengimpor konten paket yang dipilih ke file. Anda juga dapat mengimpor seluruh paket ke file JavaScript atau SQLX, bukan konten yang dipilih.

Untuk mencegah masalah penginstalan paket di lingkungan produksi, sebaiknya lakukan hal berikut:

• Tentukan versi paket secara eksplisit di package.json, misalnya, 3.0.0. Jangan gunakan opsi dependencies lain dari package.json, misalnya, >version.

• Uji versi paket baru di lingkungan non-produksi. Untuk mengetahui informasi selengkapnya tentang cara mengonfigurasi berbagai lingkungan siklus proses alur kerja, lihat Praktik terbaik untuk siklus proses alur kerja.

Menambahkan paket sebagai dependensi

Untuk menginstal paket di dalam repositori Dataform, Anda harus menambahkannya sebagai dependensi dalam file package.json:

1. Di ruang kerja Anda, di panel Files, pilih package.json.

2. Tambahkan paket ke blok dependencies:

   1. Tambahkan paket NPM publik yang dipublikasikan dalam format berikut:

      "PACKAGE-NAME": "PACKAGE-VERSION"
      

      Ganti kode berikut:

      • PACKAGE-NAME dengan nama paket.
      • PACKAGE-VERSION dengan versi terbaru paket NPM publik yang dipublikasikan. Untuk mencegah masalah penginstalan paket, tentukan versi secara eksplisit, misalnya, 3.0.0.

   2. Tambahkan paket NPM publik yang tidak dipublikasikan dalam format berikut:

      "PACKAGE-NAME": "PACKAGE-URL"
      

      Ganti kode berikut:

      • PACKAGE-NAME dengan nama paket.
      • PACKAGE-URL dengan URL tar.gz repositori paket pihak ketiga, misalnya https://github.com/user/sample-package-repository/archive/master.tar.gz.

   3. Tambahkan paket NPM pribadi yang diautentikasi dalam format berikut:

      "REGISTRY-SCOPE/PACKAGE-NAME": "PACKAGE-URL"
      

      Ganti kode berikut:

      • REGISTRY-SCOPE dengan nama paket. REGISTRY-SCOPE harus cocok dengan cakupan registry yang ditentukan dalam file .npmrc di repositori Anda.
      • PACKAGE-NAME dengan nama paket.
      • PACKAGE-URL dengan URL tar.gz repositori paket, misalnya https://github.com/user/sample-package-repository/archive/master.tar.gz.

3. Klik Install packages.

4. Commit dan kirim perubahan Anda.

Contoh kode berikut menunjukkan paket Slowly changing dimensions open source publik yang ditambahkan ke file .package.json:

 ```json
 {
   "name": "repository-name",
   "dependencies": {
     "@dataform/core": "2.0.3",
     "dataform-scd": "https://github.com/dataform-co/dataform-scd/archive/0.3.tar.gz"
   }
 }
 ```

Mengimpor fungsi atau konstanta paket ke file JavaScript di Dataform

Untuk menggunakan fungsi atau konstanta dari paket di dalam file JavaScript di Dataform, Anda harus mengimpornya terlebih dahulu ke file tersebut.

Untuk mengimpor fungsi atau konstanta dari paket ke file JavaScript, ikuti langkah-langkah berikut:

1. Di ruang kerja, di panel Files, pilih file .js tempat Anda ingin menggunakan paket.

2. Dalam file, impor fungsi atau konstanta dalam format berikut:

   const { EXPORT-NAME } = require("PACKAGE-NAME");
   

   1. Ganti EXPORT-NAME dengan nama fungsi atau konstanta yang ingin Anda gunakan, yang dideklarasikan di module.exports dalam file paket index.js.
   2. Ganti PACKAGE-NAME dengan nama paket yang ingin Anda gunakan.

3. Commit dan kirim perubahan Anda.

Contoh kode berikut menunjukkan fungsi getDomain dari paket postoffice yang diimpor dan digunakan dalam file JavaScript:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

const { getDomain } = require("postoffice");
getDomain();

Mengimpor seluruh paket ke file JavaScript di Dataform

Untuk mengimpor seluruh paket ke file JavaScript, bukan mengimpor fungsi atau konstanta yang dipilih ke file JavaScript, ikuti langkah-langkah berikut:

1. Di ruang kerja Anda, di panel Files, pilih file .js tempat Anda ingin menggunakan paket.

2. Dalam file, impor paket dalam format berikut:

   const CONSTANT-NAME = require("PACKAGE-NAME");
   

   1. Ganti CONSTANT-NAME dengan nama untuk konstanta.
   2. Ganti PACKAGE-NAME dengan nama paket yang ingin Anda gunakan.

3. Commit dan kirim perubahan Anda.

Contoh kode berikut menunjukkan fungsi getDomain dari paket postoffice yang diimpor yang digunakan dalam file JavaScript:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

const postoffice = require("postoffice");
postoffice.getDomain();

Mengimpor fungsi atau konstanta paket ke file SQLX di Dataform

Untuk menggunakan fungsi atau konstanta dari paket di dalam file SQLX, Anda harus mengimpornya terlebih dahulu ke file tersebut.

Untuk mengimpor fungsi atau konstanta dari paket ke file SQLX, ikuti langkah-langkah berikut:

1. Di ruang kerja, di panel Files, pilih file .sqlx tempat Anda ingin menggunakan paket.

2. Dalam file tersebut, masukkan blok js berikut:

   js {
     const { EXPORT-NAME } = require("PACKAGE-NAME");
   }
   

   1. Ganti EXPORT-NAME dengan nama fungsi atau konstanta yang ingin Anda gunakan, yang dideklarasikan di module.exports dalam file paket index.js.
   2. Ganti PACKAGE-NAME dengan nama paket yang ingin Anda gunakan.

3. Commit dan kirim perubahan Anda.

Contoh kode berikut menunjukkan fungsi getDomain dari paket postoffice yang diimpor dalam blok js dan digunakan dalam pernyataan SELECT dalam file SQLX:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

config {
    type: "table",
}

js {
  const { getDomain } = require("postoffice");
}

SELECT ${getDomain("email")} as test

Mengimpor seluruh paket ke file SQLX di Dataform

Untuk mengimpor seluruh paket ke file SQLX, bukan mengimpor fungsi atau konstanta yang dipilih ke file JavaScript, ikuti langkah-langkah berikut:

1. Di ruang kerja, di panel Files, pilih file .sqlx tempat Anda ingin menggunakan paket.

2. Dalam file, impor paket dalam format berikut:

   js {
     const CONSTANT-NAME = require("PACKAGE-NAME");
   }
   

   1. Ganti CONSTANT-NAME dengan nama untuk konstanta.
   2. Ganti PACKAGE-NAME dengan nama paket yang ingin Anda gunakan.

3. Commit dan kirim perubahan Anda.

Contoh kode berikut menunjukkan paket postoffice yang diimpor dalam blok js dan fungsi getDomain-nya yang digunakan dalam pernyataan SELECT dalam file SQLX:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

config {
    type: "table",
}

js {
  const postoffice = require("postoffice");
}

SELECT ${postoffice.getDomain("email")} as test

Mengautentikasi paket pribadi

Perhatian: Secret yang dibagikan kepada agen layanan Dataform (seperti token registry NPM pribadi) berpotensi diakses oleh pengguna yang dapat mengedit kode atau memicu hasil kompilasi di repositori. Untuk mengetahui informasi selengkapnya, lihat Akses secret selama penginstalan paket.

Bagian ini menunjukkan cara mengautentikasi paket NPM pribadi di Dataform untuk mengaktifkan penginstalannya di repositori Dataform.

Untuk menginstal paket NPM pribadi di repositori Dataform dan menggunakannya untuk mengembangkan alur kerja, Anda harus mengautentikasi paket tersebut terlebih dahulu di Dataform. Proses autentikasi berbeda untuk paket pribadi pertama dalam repositori dan paket pribadi berikutnya dalam repositori.

Mengautentikasi paket pribadi pertama di repositori Dataform

Untuk mengautentikasi paket NPM pribadi di Dataform, Anda harus melakukan hal berikut sebelum menginstal paket NPM pribadi pertama di repositori Dataform:

1. Buat secret Secret Manager yang dikhususkan untuk menyimpan token autentikasi paket NPM pribadi di repositori Dataform.

   1. Tambahkan token autentikasi paket, yang diperoleh dari registry NPM Anda, ke secret.

   Anda harus menyimpan semua token autentikasi paket NPM pribadi di repositori Anda dalam satu secret. Anda perlu membuat satu secret khusus per repositori Dataform. Rahasia harus dalam format JSON.

2. Upload secret ke repositori Dataform.

3. Buat file .npmrc dan tambahkan token autentikasi paket ke file.

   Token autentikasi dalam file .npmrc harus cocok dengan token autentikasi dalam secret yang diupload.

Setelah mengautentikasi paket NPM pribadi, Anda dapat menginstal paket di repositori Dataform.

Membuat secret untuk autentikasi paket pribadi

Untuk mengautentikasi paket NPM pribadi di repositori Dataform, Anda perlu membuat secret Secret Manager dan menentukan token autentikasi untuk semua paket pribadi yang ingin Anda instal di repositori Dataform di dalam secret. Tentukan satu token autentikasi untuk setiap paket NPM pribadi, dan simpan semua token autentikasi dalam satu secret untuk setiap repositori. Rahasia harus dalam format JSON.

Untuk membuat secret dengan token autentikasi untuk paket NPM pribadi, ikuti langkah-langkah berikut:

1. Di Secret Manager, buat secret.

   1. Di kolom Secret value, masukkan satu atau beberapa token autentikasi dalam format berikut:

   {
     "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
   }
   

   Ganti kode berikut:

   • AUTHENTICATION_TOKEN_NAME: nama unik untuk token yang mengidentifikasi paket yang diautentikasinya.
   • TOKEN_VALUE: nilai token autentikasi, yang diperoleh dari registry NPM Anda.

2. Berikan akses ke secret kepada agen layanan Dataform.

   ID agen layanan Dataform memiliki format berikut:

   service-PROJECT_NUMBER@gcp-sa-dataform.
   

   1. Saat memberikan akses, pastikan untuk memberikan peran roles/secretmanager.secretAccessor kepada agen layanan Dataform.

Jika Anda menggunakan token autentikasi berumur singkat, seperti token akses OAuth untuk Artifact Registry, Anda harus memperbarui secret secara berkala dengan versi secret baru sebelum masa berlaku token berakhir. Dataform menggunakan versi terbaru secret secara default. Untuk mengetahui informasi tentang cara mengotomatiskan update secret, lihat Merotasi secret Anda.

Mengupload secret untuk autentikasi paket pribadi ke repositori Dataform

Sebelum menginstal paket NPM pribadi di repositori Dataform untuk pertama kalinya, upload secret yang berisi token autentikasi paket ke repositori.

Untuk mengupload secret dengan token autentikasi paket NPM pribadi ke repositori Dataform, ikuti langkah-langkah berikut:

1. Di konsol Google Cloud , buka halaman Dataform.

   Buka Dataform

2. Pilih repositori tempat Anda ingin menginstal paket NPM pribadi.

3. Di halaman repositori, klik Settings > Configure private NPM packages.

4. Di panel Add NPM package secret token, di menu Secret, pilih secret yang berisi token autentikasi untuk paket NPM pribadi.

5. Klik Simpan.

Membuat file .npmrc untuk autentikasi paket pribadi

Untuk mengautentikasi paket NPM pribadi di repositori Dataform, Anda perlu membuat file .npmrc level teratas di repositori. Anda harus menyimpan token autentikasi untuk semua paket NPM pribadi yang akan diinstal di repositori di dalam file .npmrc. Token autentikasi dalam file .npmrc harus cocok dengan token autentikasi dalam secret yang diupload ke repositori. Untuk mengetahui informasi selengkapnya tentang file .npmrc, lihat dokumentasi npmrc.

Untuk membuat file .npmrc level teratas di repositori Anda, ikuti langkah-langkah berikut:

1. Di konsol Google Cloud , buka halaman Dataform.

   Buka Dataform

2. Pilih repositori tempat Anda ingin menginstal paket NPM pribadi, lalu pilih ruang kerja.

3. Di panel Files, klik More, lalu klik Create file.

4. Di panel Create new file, lakukan hal berikut:

   1. Di kolom Add a file path, masukkan .npmrc.

   2. Klik Create file.

Menambahkan token autentikasi ke file .npmrc di repositori Dataform

Untuk mengautentikasi paket NPM pribadi di repositori Dataform yang sudah berisi secret dengan token autentikasi paket dan file .npmrc, Anda perlu menambahkan token autentikasi untuk paket pribadi ke file .npmrc di repositori.

Dalam file .npmrc, Anda perlu menentukan cakupan registry NPM dan menambahkan token autentikasi untuk paket pribadi yang diakses dalam cakupan tersebut. Untuk mengetahui informasi selengkapnya tentang file .npmrc, lihat dokumentasi npmrc.

Token autentikasi dalam file .npmrc harus cocok dengan token autentikasi dalam secret yang diupload ke repositori.

Untuk menambahkan token autentikasi ke file .npmrc di repositori Dataform, ikuti langkah-langkah berikut:

1. Di konsol Google Cloud , buka halaman Dataform.

   Buka Dataform

2. Pilih repositori tempat Anda ingin menginstal paket NPM pribadi, lalu pilih ruang kerja.

3. Di panel Files, pilih file .npmrc.

4. Di file .npmrc, tentukan cakupan registry NPM dan token autentikasi untuk paket pribadi dalam format berikut:

   @REGISTRY-SCOPE:registry=NPM-REGISTRY-URL
   NPM-REGISTRY-URL:_authToken=$AUTHENTICATION-TOKEN
   

   Ganti kode berikut:

   • REGISTRY-SCOPE: cakupan registry NPM yang ingin Anda terapkan token autentikasi.
   • NPM-REGISTRY-URL: URL registry NPM Anda, misalnya, https://npm.pkg.github.com.
   • AUTHENTICATION-TOKEN: token autentikasi untuk paket NPM pribadi. Token autentikasi dalam file .npmrc harus cocok dengan token autentikasi dalam rahasia yang diupload. Token autentikasi disediakan sebagai variabel lingkungan dalam file .npmrc, jadi pastikan Anda menambahkan tanda kurung buka ${ dan tanda kurung tutup }.

   Anda dapat memasukkan beberapa token autentikasi.

Contoh kode berikut menunjukkan token autentikasi untuk paket NPM pribadi yang ditambahkan ke file .npmrc di repositori Dataform:

@company:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${AUTHENTICATION_TOKEN}

Mengautentikasi paket pribadi berikutnya di repositori Dataform

Untuk mengautentikasi paket NPM pribadi di repositori Dataform yang sudah berisi secret dengan token autentikasi paket dan file .npmrc, ikuti langkah-langkah berikut:

1. Di Secret Manager, cantumkan secret dan pilih secret yang menyimpan token autentikasi paket NPM pribadi repositori Anda.

2. Tambahkan versi baru ke secret.

   Dataform menggunakan versi terbaru secret secara default.

   1. Tambahkan token autentikasi untuk paket pribadi ke nilai secret dalam format berikut:

   {
     "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
   }
   

   Ganti kode berikut:

   • AUTHENTICATION_TOKEN_NAME: nama unik untuk token yang mengidentifikasi paket yang diautentikasinya.
   • TOKEN_VALUE: nilai token autentikasi, yang diperoleh dari registry NPM Anda.

   Anda dapat menambahkan beberapa token autentikasi sekaligus.

3. Di Dataform, tambahkan token autentikasi ke file .npmrc di repositori Anda.

Setelah mengautentikasi paket NPM pribadi, Anda dapat menginstal paket di repositori Dataform.

Membuat paket

Bagian ini menunjukkan cara membuat paket JavaScript kustom yang dapat Anda gunakan untuk mengembangkan alur kerja di Dataform.

Untuk membuat paket yang dapat Anda gunakan kembali di beberapa repositori Dataform, Anda harus membuat repositori Dataform yang dikhususkan untuk paket tersebut dan menghubungkannya ke repositori Git pihak ketiga agar tersedia untuk repositori Dataform lainnya.

Kemudian, Anda perlu membuat file index.js tingkat atas dan menambahkan konten paket yang dapat diekspor, seperti fungsi dan konstanta, ke file tersebut. Untuk contoh paket yang dibuat di Dataform, lihat dataform-package-base di GitHub.

Setelah membuat paket, Anda dapat menginstal paket di repositori Dataform yang berbeda dan menggunakan konten yang dapat diekspor pada paket, seperti konstanta dan fungsi, untuk mengembangkan alur kerja.

Sebagai alternatif untuk membuat paket, Anda dapat menggunakan kembali fungsi dan konstanta JavaScript di satu repositori Dataform dengan include. Untuk mengetahui informasi selengkapnya, lihat Menggunakan kembali variabel dan fungsi dengan penyertaan di Dataform.

Untuk membuat paket Anda sendiri dengan kode JavaScript yang dapat Anda gunakan kembali di Dataform, ikuti langkah-langkah berikut di ruang kerja Anda:

1. Di panel Files, klik More.

2. Klik Create file.

   1. Di panel Create new file, lakukan hal berikut:

   2. Di kolom Add a file path, masukkan index.js.

   3. Klik Create file.

3. Dalam file index.js, masukkan kode JavaScript yang ingin diekspor oleh paket Anda.

   1. Buat konstanta dalam format berikut:

      const CONSTANT_NAME = CONSTANT_VALUE;
      module.exports = { CONSTANT_NAME };
      

      Ganti kode berikut:

      • CONSTANT_NAME: nama konstanta Anda
      • CONSTANT_VALUE: nilai konstanta Anda

   2. Buat fungsi dalam format berikut:

      function FUNCTION_NAME(PARAMETERS) { FUNCTION_BODY }
      
      module.exports = { FUNCTION_NAME }
      

      Ganti kode berikut:

      • FUNCTION_NAME: nama fungsi Anda.
      • PARAMETERS: parameter fungsi Anda.
      • FUNCTION_BODY: kode yang Anda inginkan untuk dijalankan oleh fungsi.

4. Opsional: Klik Format.

5. Opsional: Di direktori definitions, tambahkan kode paket Anda yang tidak akan diekspor.

6. Commit dan kirim perubahan Anda.

Contoh kode paket berikut menunjukkan file index.js dari paket postoffice yang mengekspor fungsi getDomain:

// filename index.js
// package name postoffice

const GENERIC_DOMAINS = "('samplemail.com','samplemail.co.uk','examplemailbox.com'";

function getDomain(email) {
  let cleanEmail = `trim(${email})`
  const domain = `substr(${cleanEmail}, strpos(${cleanEmail}, '@') + 1)`;
  return `case
            when ${domain} in ${common.GENERIC_DOMAINS} then ${cleanEmail}
            when ${domain} = "othermailbox.com" then "other.com"
            when ${domain} = "mailbox.com" then "mailbox.global"
            when ${domain} = "support.postman.com" then "postman.com"
            else ${domain}
          end`;
}

module.exports = { getDomain }

Langkah berikutnya

• Untuk mempelajari cara mengelola paket inti Dataform yang diperlukan, lihat Mengelola paket inti Dataform.
• Untuk mempelajari lebih lanjut paket di Dataform, lihat Menggunakan kembali kode di beberapa repositori dengan paket.
• Untuk mempelajari cara menulis variabel dan fungsi JavaScript yang dapat Anda gunakan kembali di Dataform, lihat Menggunakan kembali variabel dan fungsi dengan penyertaan di Dataform.