Menggunakan paket JavaScript

Dokumen ini menunjukkan cara melakukan hal berikut:

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 guna 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 didedikasikan 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 Anda untuk memberikan peran IAM berikut:

Untuk mengetahui informasi selengkapnya tentang cara memberikan 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 untuk mengembangkan alur kerja di Dataform.

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

Anda dapat menginstal jenis paket berikut di Dataform:

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 terkait 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 informasi selengkapnya tentang cara mengonfigurasi berbagai lingkungan siklus proses kode, lihat Mengelola siklus proses kode.

Menambahkan paket sebagai dependensi

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

  1. Di ruang kerja, di panel File, 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 terkait 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 dari 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 .nmprc 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 Instal paket.

  4. Commit dan push perubahan Anda.

Contoh kode berikut menunjukkan paket open source publik Slowly changing dimensions 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.

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 index.js paket.
    2. Ganti PACKAGE-NAME dengan nama paket yang ingin Anda gunakan.

  3. Commit dan push 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, di panel File, pilih file .js tempat Anda ingin menggunakan paket.

  2. Dalam file tersebut, 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 push 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 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.

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

  1. Di ruang kerja, di panel File, 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 index.js paket.
    2. Ganti PACKAGE-NAME dengan nama paket yang ingin Anda gunakan.

  3. Commit dan push 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 File, pilih file .sqlx tempat Anda ingin menggunakan paket.

  2. Dalam file tersebut, 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 push 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

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 terlebih dahulu di Dataform. Proses autentikasi berbeda untuk paket pribadi pertama di repositori dan paket pribadi berikutnya di repositori.

Mengautentikasi paket pribadi pertama di repositori Dataform

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

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

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

    Anda perlu menyimpan semua token autentikasi paket NPM pribadi di repositori dalam satu secret. Anda perlu membuat satu secret khusus per repositori Dataform. Secret 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 harus membuat secret Pengelola Secret dan menentukan token autentikasi untuk semua paket pribadi yang ingin diinstal 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. Secret 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 diautentikasi.
    • TOKEN_VALUE: nilai token autentikasi, yang diperoleh dari registry NPM Anda.

  2. Berikan akses ke secret ke akun layanan Dataform Anda.

    Akun layanan Dataform Anda memiliki format berikut:

    service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com
    1. Saat memberikan akses, pastikan untuk memberikan peran roles/secretmanager.secretAccessor ke akun layanan Dataform 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 Setelan > Konfigurasi paket NPM pribadi.

  4. Di panel Tambahkan token secret paket NPM, 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 tingkat teratas di repositori. Anda perlu 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, 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 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 tempat Anda ingin menerapkan 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 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}

Melakukan autentikasi 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 dari repositori Anda.

  2. Tambahkan versi baru ke secret.

    Dataform menggunakan rahasia versi terbaru 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 diautentikasi.
    • 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 digunakan kembali di beberapa repositori Dataform, Anda perlu 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 teratas 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 lain 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 seluruh repositori Dataform dengan menyertakan. Untuk mengetahui informasi selengkapnya, lihat Menggunakan kembali variabel dan fungsi dengan menyertakan di Dataform.

Untuk membuat paket Anda sendiri dengan kode JavaScript yang dapat digunakan 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 ingin Anda jalankan fungsinya.

  4. Opsional: Klik Format.

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

  6. Commit dan push 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