Menginstal paket di Dataform

Dokumen ini menunjukkan cara menginstal paket JavaScript di repositori Dataform, dan mengimpornya ke file JavaScript dan file SQLX untuk menggunakan paket guna mengembangkan alur kerja SQL di Dataform.

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

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 harus mengimpor konten paket yang dipilih ke file. Anda juga dapat mengimpor seluruh paket ke file JavaScript atau SQLX, bukan konten yang dipilih.

Sebelum memulai

Di konsol Google Cloud, buka halaman Dataform.

Buka halaman Dataform
Pilih atau buat repositori.
Pilih atau buat ruang kerja pengembangan.
[Opsional] Untuk menginstal paket pribadi, autentikasi paket pribadi.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk mengimpor paket, minta administrator untuk memberi Anda peran IAM Dataform Editor (roles/dataform.editor) di ruang kerja. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses.

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

Menginstal paket di repositori Dataform

Untuk menginstal paket di dalam repositori Dataform, Anda harus menambahkannya sebagai dependensi dalam file package.json. Format definisi dependensi dalam file package.json bergantung pada jenis paket. Jika Anda tidak memiliki file package.json karena file workflow_settings.yaml menentukan dataformCoreVersion, hapus dataformCoreVersion dari workflow_settings.yaml, lalu buat file package.json dan tambahkan @dataform/core sebagai dependensi.

Untuk menginstal paket di repositori Dataform, ikuti langkah-langkah berikut:

Di ruang kerja Anda, di panel Files, 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.
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 .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 Install packages.
Commit dan push perubahan Anda.

Contoh kode berikut menunjukkan paket open source publik Paket paket dimensi yang berubah perlahan dan ditambahkan ke file .package.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 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 tersebut, 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 dalam 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 Files, pilih file .js tempat Anda ingin menggunakan paket.
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.
Commit dan push 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 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 Files, pilih file .sqlx tempat Anda ingin menggunakan paket.
Dalam file, 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 Files, pilih file .sqlx tempat Anda ingin menggunakan paket.
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.
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 di file SQLX:

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

config {
    type: "table",
}

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

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

Langkah selanjutnya

Untuk mempelajari cara mengautentikasi paket NPM pribadi di Dataform, lihat Mengautentikasi paket pribadi di Dataform.
Untuk mempelajari lebih lanjut paket di Dataform, baca artikel Menggunakan kembali kode di beberapa repositori dengan paket.
Untuk mempelajari cara membuat paket Anda sendiri di Dataform, lihat Membuat paket di Dataform.
Untuk mempelajari cara menggunakan paket open source di Dataform, lihat Menggunakan Perlahan mengubah dimensi di Dataform.