Mengonfigurasi penggantian kompilasi dengan Dataform API

Dokumen ini menunjukkan cara membuat dan menjalankan hasil kompilasi dengan penggantian kompilasi menggunakan Dataform API.

Tentang penggantian kompilasi Dataform API

Untuk menjalankan alur kerja SQL, Dataform mengompilasi kode Anda ke SQL untuk membuat hasil kompilasi. Kemudian, selama pemanggilan alur kerja, Dataform akan menjalankan hasil kompilasi di BigQuery.

Secara default, Dataform menggunakan setelan dalam file setelan alur kerja untuk membuat hasil kompilasi. Untuk mengisolasi data yang dijalankan pada berbagai tahap siklus proses pengembangan, Anda dapat mengganti setelan default dengan penggantian kompilasi.

Dengan meneruskan permintaan Dataform API di terminal, Anda dapat membuat dan menjalankan satu hasil kompilasi dengan penggantian kompilasi. Anda dapat membuat hasil kompilasi dari ruang kerja atau commit Git yang dipilih.

Untuk membuat hasil kompilasi dengan penggantian kompilasi, Anda perlu mengajukan permintaan compilationResults.create Dataform API. Dalam permintaan, Anda harus menentukan sumber, workspace, atau commitish Git, agar Dataform dapat dikompilasi ke dalam hasil kompilasi. Dalam objek CodeCompilationConfig dari permintaan compilationResults.create, Anda dapat mengonfigurasi penggantian kompilasi.

Kemudian, Anda dapat mengeksekusi hasil kompilasi yang dibuat dalam permintaan workflowInvocations.create Dataform API.

Anda dapat mengonfigurasi penggantian kompilasi berikut menggunakan Dataform API:

Project Google Cloud : Project Google Cloud tempat Dataform menjalankan hasil kompilasi, yang ditetapkan di workflow_settings.yaml sebagai defaultProject atau di dataform.json sebagai defaultDatabase.

Awalan tabel
Awalan kustom ditambahkan ke semua nama tabel dalam hasil kompilasi.
Akhiran skema
Akhiran kustom yang ditambahkan ke skema tabel yang ditentukan dalam defaultDataset di workflow_settings.yaml, defaultSchema di dataform.json, atau dalam parameter schema di blok config tabel.

Nilai variabel kompilasi : Nilai variabel kompilasi yang akan digunakan dalam hasil kompilasi. Anda dapat menggunakan variabel kompilasi untuk mengeksekusi tabel secara bersyarat.

Sebagai alternatif penggantian kompilasi Dataform API yang hanya dapat Anda gunakan untuk satu hasil kompilasi, Anda dapat mengonfigurasi penggantian kompilasi ruang kerja di konsol Google Cloud.

Untuk mempelajari cara alternatif mengonfigurasi penggantian kompilasi di Dataform, lihat Pengantar siklus proses kode.

Sebelum memulai

  1. Di konsol Google Cloud, buka halaman Dataform.

    Buka Dataform

  2. Pilih atau buat repositori.

  3. Pilih atau buat ruang kerja pengembangan.

Menetapkan sumber hasil kompilasi

Untuk mengajukan permintaan compilationResults.create Dataform API, Anda harus menentukan sumber untuk hasil kompilasi.

Anda dapat menetapkan ruang kerja Dataform atau cabang Git, tag Git, atau SHA commit Git sebagai sumber dalam permintaan compilationResults.create.

Menetapkan ruang kerja sebagai sumber hasil kompilasi

  • Dalam permintaan compilationResults.create, isi properti workspace dengan jalur ruang kerja Dataform yang dipilih dalam format berikut:
{
"workspace": "projects/PROJECT_NAME/locations/LOCATION/repositories/REPOSITORY_NAME/workspaces/WORKSPACE_NAME"
}

Ganti kode berikut:

  • PROJECT_NAME dengan nama project Google Cloud Anda.
  • LOCATION dengan lokasi repositori Dataform Anda, yang ditetapkan di setelan alur kerja.
  • REPOSITORY_NAME dengan nama repositori Dataform Anda.
  • WORKSPACE_NAME dengan nama ruang kerja Dataform Anda.

Contoh kode berikut menunjukkan properti workspace dalam permintaan compilationResults.create yang ditetapkan ke ruang kerja bernama "sales-test":

{
"workspace": "projects/analytics/locations/europe-west4/repositories/sales/workspaces/sales-test"
}

Menetapkan commitish Git sebagai sumber hasil kompilasi

  • Dalam permintaan compilationResults.create, isi properti gitCommitish dengan cabang, tag, atau SHA commit Git yang dipilih dalam format berikut:

    {
  "gitCommitish": "GIT_COMMITISH"
}

Ganti GIT_COMMITISH dengan cabang Git, tag Git, atau SHA commit Git yang dipilih untuk hasil kompilasi.

Contoh kode berikut menunjukkan properti gitCommitish dalam permintaan compilationResults.create yang ditetapkan ke "staging":

{
  "gitCommitish": "staging"
}

Mengganti project Google Cloud default

Untuk membuat tabel staging atau produksi di project Google Cloud yang terpisah dari project yang digunakan untuk pengembangan, Anda dapat meneruskan ID project Google Cloud yang berbeda dalam objek CodeCompilationConfig dalam permintaan compilationResults.create Dataform API.

Meneruskan project ID default terpisah dalam permintaan compilationResults.create akan mengganti project ID Google Cloud default yang dikonfigurasi dalam file setelan alur kerja, tetapi tidak mengganti project ID Google Cloud yang dikonfigurasi di setiap tabel.

  • Untuk mengganti project ID Google Cloud default, tetapkan properti defaultDatabase ke project ID Google Cloud yang dipilih di objek CodeCompilationConfig dalam format berikut:

    {
  "codeCompilationConfig": {
    "defaultDatabase": "PROJECT_NAME"
  }
}

Ganti PROJECT_NAME dengan project ID Google Cloud yang ingin Anda tetapkan untuk hasil kompilasi.

Menambahkan awalan tabel

Untuk mengidentifikasi tabel dengan cepat dari hasil kompilasi, Anda dapat menambahkan awalan ke semua nama tabel dalam hasil kompilasi dengan meneruskan awalan tabel dalam objek CodeCompilationConfig dalam permintaan compilationResults.create Dataform API.

  • Untuk menambahkan awalan tabel, tetapkan properti tablePrefix dalam objek CodeCompilationConfig dalam format berikut:
{
  "codeCompilationConfig": {
    "tablePrefix": "PREFIX",
  }
}

Ganti PREFIX dengan akhiran yang ingin ditambahkan, misalnya, _staging. Misalnya, jika defaultDataset di workflow_settings.yaml ditetapkan ke dataform, Dataform akan membuat tabel dalam skema dataform_staging.

Menambahkan akhiran skema

Untuk memisahkan data pengembangan, staging, dan produksi, Anda dapat menambahkan akhiran ke skema dalam hasil kompilasi dengan meneruskan akhiran skema dalam objek CodeCompilationConfig dalam permintaan compilationResults.create Dataform API.

  • Untuk menambahkan akhiran skema, tetapkan properti schemaSuffix dalam objek CodeCompilationConfig dalam format berikut:
{
  "codeCompilationConfig": {
    "schemaSuffix": "SUFFIX",
  }
}

Ganti SUFFIX dengan akhiran yang ingin ditambahkan, misalnya, _staging. Misalnya, jika defaultDataset di workflow_settings.yaml ditetapkan ke dataform, Dataform akan membuat tabel dalam skema dataform_staging.

Catatan: Parameter CodeCompilationConfig schemaSuffix akan menggantikan skema yang dikonfigurasi dalam blok config setiap file.

Menjalankan file yang dipilih secara kondisional dengan variabel kompilasi

Untuk menjalankan tabel yang dipilih hanya dalam setelan eksekusi tertentu, Anda dapat membuat variabel kompilasi untuk setelan eksekusi, lalu meneruskan nilainya dalam objek CodeCompilationConfig dalam permintaan compilationResults.create Dataform API.

Untuk mengeksekusi tabel secara kondisional dalam setelan eksekusi tertentu menggunakan Dataform API, ikuti langkah-langkah berikut:

  1. Buat variabel kompilasi dan tambahkan ke tabel yang dipilih.

  2. Tetapkan pasangan nilai kunci YOUR_VARIABLE dan VALUE di blok codeCompilationConfig permintaan kompilasi Dataform API dalam format berikut:

    {
 "codeCompilationConfig": {
   "vars": {
     "YOUR_VARIABLE": "VALUE"
   }
 }
}

  3. Ganti YOUR_VARIABLE dengan nama variabel Anda, misalnya executionSetting.

  4. Ganti VALUE dengan nilai variabel untuk hasil kompilasi ini yang memenuhi kondisi when yang ditetapkan dalam tabel yang dipilih.

Contoh kode berikut menunjukkan variabel executionSetting yang diteruskan ke permintaan kompilasi Dataform API:

{
  "gitCommitish": "staging",
  "codeCompilationConfig": {
    "vars": {
      "executionSetting": "staging"
    }
  }
}

Menjalankan hasil kompilasi dengan penggantian kompilasi

Contoh kode berikut menunjukkan ID hasil kompilasi yang diteruskan dalam permintaan workflowInvocations.create:

{
  "compilationResult": "projects/my-project-name/locations/europe-west4/repositories/my-repository-name/compilationResults/7646b4ed-ac8e-447f-93cf-63c43249ff11"
}

Langkah selanjutnya