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 Anda, Dataform mengompilasi kode Anda ke SQL untuk membuat hasil kompilasi. Kemudian, selama pemanggilan alur kerja, Dataform mengeksekusi hasil kompilasi di BigQuery.

Secara default, Dataform menggunakan setelan dalam file dataform.json 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 committish Git yang dipilih.

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

Kemudian, Anda dapat menjalankan 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 dataform.json sebagai defaultDatabase.
Awalan tabel: Awalan kustom ditambahkan ke semua nama tabel dalam hasil kompilasi.
Akhiran skema: Akhiran kustom ditambahkan ke skema tabel yang ditentukan dalam defaultSchema di dataform.json atau dalam parameter schema dalam 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 digunakan untuk satu hasil kompilasi, Anda dapat mengonfigurasi penggantian kompilasi Workspace di Konsol Google Cloud.

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

Sebelum memulai

Di konsol Google Cloud, buka halaman Dataform.

Buka Dataform
Pilih atau buat repositori.
Pilih atau buat ruang kerja pengembangan.

Menetapkan sumber hasil kompilasi

Untuk mengajukan permintaan compilationResults.create Dataform API, Anda perlu 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.

Tetapkan ruang kerja sebagai sumber hasil kompilasi

Dalam permintaan compilationResults.create, isi properti workspace dengan jalur ruang kerja Formulir data 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 dataform.json.
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 Git, tag, atau SHA commit yang dipilih dalam format berikut:
```
{
  "gitCommitish": "GIT_COMMITISH"
}
```

Ganti GIT_COMMITISH dengan cabang Git yang dipilih, tag Git, atau SHA commit Git 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 di objek CodeCompilationConfig dalam permintaan compilationResults.create Dataform API.

Meneruskan project ID default yang terpisah dalam permintaan compilationResults.create akan menggantikan project ID Google Cloud default yang dikonfigurasi di file dataform.json, tetapi tidak akan mengganti project ID Google Cloud yang dikonfigurasi di masing-masing 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 di permintaan compilationResults.create Dataform API.

Untuk menambahkan awalan tabel, tetapkan properti tablePrefix pada objek CodeCompilationConfig dalam format berikut:

{
  "codeCompilationConfig": {
    "tablePrefix": "PREFIX",
  }
}

Ganti PREFIX dengan akhiran yang ingin Anda tambahkan, misalnya, _staging. Misalnya, jika defaultSchema di dataform.json 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 pada objek CodeCompilationConfig dalam format berikut:

{
  "codeCompilationConfig": {
    "schemaSuffix": "SUFFIX",
  }
}

Ganti SUFFIX dengan akhiran yang ingin Anda tambahkan, misalnya, _staging. Misalnya, jika defaultSchema di dataform.json ditetapkan ke dataform, Dataform akan membuat tabel dalam skema dataform_staging.

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

Menjalankan file yang dipilih secara bersyarat 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 di permintaan compilationResults.create Dataform API.

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

Buat variabel kompilasi dan tambahkan ke tabel yang dipilih.
Tetapkan pasangan nilai kunci YOUR_VARIABLE dan VALUE dalam blok codeCompilationConfig permintaan kompilasi Dataform API dalam format berikut:
```
{
 "codeCompilationConfig": {
   "vars": {
     "YOUR_VARIABLE": "VALUE"
   }
 }
}
```
Ganti YOUR_VARIABLE dengan nama variabel Anda, misalnya executionSetting.
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

Untuk menjalankan hasil kompilasi yang dibuat oleh permintaan compilationResults.create, teruskan ID hasil kompilasi yang ditampilkan oleh permintaan compilationResults.create dalam permintaan workflowInvocations.create.

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

Untuk mempelajari lebih lanjut cara mengonfigurasi penggantian kompilasi di Dataform, lihat Pengantar siklus proses kode.
Untuk mempelajari Dataform API lebih lanjut, lihat Dataform API.
Untuk mempelajari cara menggunakan Google Cloud Console guna mengonfigurasi penggantian kompilasi untuk semua ruang kerja di repositori, lihat Mengonfigurasi penggantian kompilasi Workspace.