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 tersebut guna mengembangkan alur kerja SQL 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.

Sebelum memulai

  1. Di konsol Google Cloud, buka halaman Dataform.

    Buka halaman Dataform

  2. Pilih atau buat repositori.

  3. Pilih atau buat ruang kerja pengembangan.

  4. Jika repositori Anda tidak berisi file package.json, buat package.json dan pindahkan paket inti Dataform.

  5. Opsional: Untuk menginstal paket pribadi, autentikasi paket pribadi.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna menginstal 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 ke project, folder, dan organisasi.

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

Menginstal paket

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

Untuk menambahkan paket sebagai dependensi dalam file package.json, lakukan langkah-langkah berikut:

  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 paket dimensi yang berubah perlahan 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

Langkah selanjutnya