Halaman ini diterjemahkan oleh Cloud Translation API.

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

Di konsol Google Cloud , buka halaman Dataform.

Buka Dataform
Lakukan salah satu atau kedua hal berikut:
1. Untuk menginstal paket di repositori atau mengautentikasi paket NPM pribadi agar dapat diinstal, ikuti langkah-langkah berikut:
  1. Pilih atau buat repositori.
  2. Pilih atau buat ruang kerja pengembangan.
  3. Opsional: Untuk menginstal paket pribadi, lakukan 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.
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 memberi Anda peran IAM berikut:

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

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 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:

Memublikasikan paket NPM publik
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 Anda melakukan hal berikut:

Tentukan versi paket secara eksplisit di package.json, misalnya, 3.0.0. Jangan gunakan opsi dependencies lainnya dari package.json, misalnya, >version.
Uji versi paket baru di lingkungan non-produksi. Untuk mengetahui informasi selengkapnya tentang cara mengonfigurasi lingkungan siklus proses alur kerja yang berbeda, 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:

Di ruang kerja Anda, di panel File, pilih package.json.
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 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 registri yang ditentukan dalam file .nmprc di repositori Anda.
  - PACKAGE-NAME dengan nama paket.
  - PACKAGE-URL dengan URL tar.gz dari repositori paket, misalnya https://github.com/user/sample-package-repository/archive/master.tar.gz.
Klik Instal paket.
Commit dan push perubahan Anda.

Contoh kode berikut menunjukkan paket dimensi yang berubah perlahan 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.

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

Di ruang kerja Anda, di panel Files, pilih file .js tempat Anda ingin menggunakan paket.
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.
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:

Di ruang kerja Anda, di panel File, pilih file .js tempat Anda ingin menggunakan paket.
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.
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:

Di ruang kerja Anda, di panel File, pilih file .sqlx tempat Anda ingin menggunakan paket.
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.
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:

Di ruang kerja Anda, di panel File, pilih file .sqlx tempat Anda ingin menggunakan paket.
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.
Commit dan push perubahan Anda.

Contoh kode berikut menunjukkan paket postoffice yang diimpor dalam blok js dan fungsi getDomain 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 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:

Buat secret Secret Manager khusus untuk menyimpan token autentikasi paket NPM pribadi di repositori Dataform.
1. Tambahkan token autentikasi paket, yang diperoleh dari registry NPM, ke secret.
Anda harus menyimpan semua token autentikasi paket NPM pribadi di repositori Anda dalam satu rahasia. Anda harus membuat satu rahasia khusus per repositori Dataform. Secret harus dalam format JSON.
Upload secret ke repositori Dataform.
Buat file .npmrc dan tambahkan token autentikasi paket ke file tersebut.

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 rahasia 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 dalam secret. Tentukan satu token autentikasi untuk setiap paket NPM pribadi, dan simpan semua token autentikasi dalam satu rahasia untuk setiap repositori. Secret harus dalam format JSON.

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

Di Secret Manager, buat secret.
1. Di kolom Nilai rahasia, 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.
Berikan akses ke rahasia untuk 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 rahasia Anda yang berisi token autentikasi paket ke repositori.

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

Di konsol Google Cloud , buka halaman Dataform.

Buka Dataform
Pilih repositori tempat Anda ingin menginstal paket NPM pribadi.
Di halaman repositori, klik Setelan > Konfigurasi paket NPM pribadi.
Di panel Add NPM package secret token, di menu Secret, pilih rahasia Anda yang berisi token autentikasi untuk paket NPM pribadi.
Klik Simpan.

Membuat file `.npmrc` untuk autentikasi paket pribadi

Untuk mengautentikasi paket NPM pribadi di repositori Dataform, Anda harus membuat file .npmrc tingkat teratas di repositori. Anda harus menyimpan token autentikasi untuk semua paket NPM pribadi yang akan diinstal di repositori 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 tingkat teratas di repositori Anda, ikuti langkah-langkah berikut:

Di konsol Google Cloud , buka halaman Dataform.

Buka Dataform
Pilih repositori tempat Anda ingin menginstal paket NPM pribadi, lalu pilih ruang kerja.
Di panel Files, klik More, lalu klik Create file.
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 rahasia dengan token autentikasi paket dan file .npmrc, Anda harus 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:

Di konsol Google Cloud , buka halaman Dataform.

Buka Dataform
Pilih repositori tempat Anda ingin menginstal paket NPM pribadi, lalu pilih ruang kerja.
Di panel Files, pilih file .npmrc.
Dalam 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 diberikan 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}

Mengautentikasi paket pribadi berikutnya di repositori Dataform

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

Di Secret Manager, cantumkan secret dan pilih secret yang menyimpan token autentikasi paket NPM pribadi repositori Anda.
Tambahkan versi baru ke secret.

Dataform menggunakan versi terbaru rahasia 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.
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 khusus 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 satu repositori Dataform dengan include. Untuk mengetahui informasi selengkapnya, lihat Menggunakan kembali variabel dan fungsi dengan include 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:

Di panel Files, klik More.
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.
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 agar fungsi dijalankan.
Opsional: Klik Format.
Opsional: Di direktori definitions, tambahkan kode paket Anda yang tidak akan diekspor.
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

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 include di Dataform.

Menggunakan paket JavaScript Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.