Menerjemahkan kueri SQL dengan Translation API

Dokumen ini menjelaskan cara menggunakan Translation API dalam BigQuery untuk menerjemahkan skrip yang ditulis dalam dialek SQL lain ke dalam kueri GoogleSQL. Translation API dapat menyederhanakan proses migrasi beban kerja ke BigQuery.

Sebelum memulai

Sebelum Anda mengirimkan tugas terjemahan, selesaikan langkah-langkah berikut:

  1. Pastikan Anda memiliki semua izin yang diperlukan.
  2. Mengaktifkan BigQuery Migration API.
  3. Mengumpulkan file sumber yang berisi skrip dan kueri SQL yang akan diterjemahkan.
  4. Mengupload file sumber ke Cloud Storage.

Izin yang diperlukan

Untuk mendapatkan izin yang diperlukan guna membuat tugas terjemahan menggunakan API terjemahan, minta administrator untuk memberi Anda peran IAM MigrationWorkflow Editor (roles/bigquerymigration.editor) pada resource parent. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk membuat tugas terjemahan menggunakan API terjemahan. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk membuat tugas terjemahan menggunakan Translation API:

  • bigquerymigration.workflows.create
  • bigquerymigration.workflows.get

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Mengaktifkan BigQuery Migration API

Jika project Google Cloud CLI Anda dibuat sebelum 15 Februari 2022, aktifkan BigQuery Migration API sebagai berikut:

  1. Di konsol Google Cloud, buka halaman BigQuery Migration API.

    Buka BigQuery Migration API

  2. Klik Enable.

Mengupload file input ke Cloud Storage

Jika ingin menggunakan Konsol Google Cloud atau BigQuery Migration API untuk melakukan tugas terjemahan, Anda harus mengupload file sumber yang berisi kueri dan skrip yang ingin diterjemahkan ke Cloud Storage. Anda juga dapat mengupload file metadata apa pun atau file YAML konfigurasi ke bucket Cloud Storage yang sama yang berisi file sumber. Untuk mengetahui informasi selengkapnya tentang membuat bucket dan mengupload file ke Cloud Storage, lihat Membuat bucket dan Mengupload objek dari sistem file.

Jenis tugas yang didukung

Translation API dapat menerjemahkan berikut dialek SQL ke GoogleSQL:

  • Amazon Redshift SQL - Redshift2BigQuery_Translation
  • Apache HiveQL dan Beeline CLI - HiveQL2BigQuery_Translation
  • Apache Spark SQL - SparkSQL2BigQuery_Translation
  • T-SQL Azure Synapse - AzureSynapse2BigQuery_Translation
  • SQL Greenplum - Greenplum2BigQuery_Translation
  • IBM Db2 SQL - Db22BigQuery_Translation
  • IBM Netezza SQL dan NZPLSQL - Netezza2BigQuery_Translation
  • SQL MySQL - MySQL2BigQuery_Translation
  • Oracle SQL, PL/SQL, Exadata - Oracle2BigQuery_Translation
  • PostgreSQL SQL - Postgresql2BigQuery_Translation
  • Presto atau Trino SQL - Presto2BigQuery_Translation
  • Snowflake SQL - Snowflake2BigQuery_Translation
  • SQLite - SQLite2BigQuery_Translation
  • SQL Server T-SQL - SQLServer2BigQuery_Translation
  • Vantage Teradata dan Teradata - Teradata2BigQuery_Translation
  • Vertica SQL - Vertica2BigQuery_Translation

Lokasi

Translation API tersedia dalam lokasi pemrosesan:

Deskripsi region Nama region Detail
Asia Pasifik
Tokyo asia-northeast1
Mumbai asia-south1
Singapura asia-southeast1
Sydney australia-southeast1
Eropa
Multi-region Uni Eropa eu
Warsawa europe-central2
Finlandia europe-north1 ikon daun CO Rendah2
Madrid europe-southwest1 ikon daun CO Rendah2
Belgia europe-west1 ikon daun CO Rendah2
London europe-west2 ikon daun CO Rendah2
Frankfurt europe-west3 ikon daun CO Rendah2
Belanda europe-west4 ikon daun CO Rendah2
Zürich europe-west6 ikon daun CO Rendah2
Paris europe-west9 ikon daun CO2 Rendah
Turin europe-west12
Amerika
Sao Paulo southamerica-east1 ikon daun CO Rendah2
Multi-region AS us
Iowa us-central1 ikon daun CO Rendah2
South Carolina us-east1
Northern Virginia us-east4
Columbus, Ohio us-east5
Dallas us-south1 ikon daun CO2 Rendah
Oregon us-west1 ikon daun CO Rendah2
Los Angeles us-west2
Salt Lake City us-west3

Mengirim tugas terjemahan

Untuk mengirimkan tugas terjemahan menggunakan Translation API, gunakan projects.locations.workflows.create dan menyediakan instance MigrationWorkflow resource dengan jenis tugas yang didukung.

Setelah tugas dikirim, Anda dapat mengeluarkan kueri untuk mendapatkan hasil.

Membuat terjemahan batch

Perintah curl berikut membuat tugas terjemahan batch di mana input dan file output disimpan di Cloud Storage. Kolom source_target_mapping berisi daftar yang memetakan entri literal sumber ke jalur relatif opsional untuk output target.

curl -d "{
  \"tasks\": {
      string: {
        \"type\": \"TYPE\",
        \"translation_details\": {
            \"target_base_uri\": \"TARGET_BASE\",
            \"source_target_mapping\": {
              \"source_spec\": {
                  \"base_uri\": \"BASE\"
              }
            },
        }
      }
  }
  }" \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows

Ganti kode berikut:

  • TYPE: jenis tugas terjemahan, yang menentukan dialek sumber dan target.
  • TARGET_BASE: URI dasar untuk semua terjemahan output.
  • BASE: URI dasar untuk semua file yang dibaca sebagai sumber terjemahan.
  • TOKEN: token untuk autentikasi. Untuk membuat token, gunakan perintah gcloud auth print-access-token atau OAuth 2.0 playground (gunakan cakupan https://www.googleapis.com/auth/cloud-platform).
  • PROJECT_ID: project untuk memproses terjemahan.
  • LOCATION: lokasi tempat tugas diproses.

Perintah sebelumnya menampilkan respons yang menyertakan ID alur kerja yang ditulis dalam format projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID.

Contoh Terjemahan Batch

Untuk menerjemahkan skrip SQL Teradata di direktori Cloud Storage gs://my_data_bucket/teradata/input/ dan menyimpan hasilnya di direktori Cloud Storage gs://my_data_bucket/teradata/output/, Anda dapat menggunakan kueri berikut:

{
  "tasks": {
     "task_name": {
       "type": "Teradata2BigQuery_Translation",
       "translation_details": {
         "target_base_uri": "gs://my_data_bucket/teradata/output/",
           "source_target_mapping": {
             "source_spec": {
               "base_uri": "gs://my_data_bucket/teradata/input/"
             }
          },
       }
    }
  }
}

Panggilan ini akan menampilkan pesan yang berisi ID alur kerja yang dibuat di kolom "name":

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "task_name": { /*...*/ }
  },
  "state": "RUNNING"
}

Untuk mendapatkan status terbaru alur kerja, jalankan kueri GET. Tugas selesai saat "state" berubah menjadi COMPLETED. Jika tugas sudah selesai berhasil, SQL yang diterjemahkan dapat ditemukan di gs://my_data_bucket/teradata/output.

Membuat tugas terjemahan interaktif dengan input dan output string literal

Perintah curl berikut membuat tugas terjemahan dengan literal string input dan output-nya. Kolom source_target_mapping berisi daftar yang memetakan direktori sumber ke jalur relatif opsional untuk output target.

curl -d "{
  \"tasks\": {
      string: {
        \"type\": \"TYPE\",
        \"translation_details\": {
        \"source_target_mapping\": {
            \"source_spec\": {
              \"literal\": {
              \"relative_path\": \"PATH\",
              \"literal_string\": \"STRING\"
              }
            }
        },
        \"target_return_literals\": \"TARGETS\",
        }
      }
  }
  }" \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows

Ganti kode berikut:

  • TYPE: jenis tugas terjemahan, yang menentukan dialek sumber dan target.
  • PATH: ID entri literal, mirip dengan nama file atau jalur.
  • STRING: string data input literal (misalnya, SQL) yang akan diterjemahkan.
  • TARGETS: target yang diharapkan yang diinginkan pengguna untuk ditampilkan secara langsung dalam respons dalam format literal. Ini harus dalam format URI target (misalnya, GENERATED_DIR + target_spec.relative_path + source_spec.literal.relative_path). Apa pun yang tidak ada dalam daftar ini tidak akan ditampilkan dalam respons. Direktori yang dihasilkan, GENERATED_DIR untuk terjemahan SQL umum adalah sql/.
  • TOKEN: token untuk autentikasi. Untuk membuat token, gunakan perintah gcloud auth print-access-token atau OAuth 2.0 playground (gunakan cakupan https://www.googleapis.com/auth/cloud-platform).
  • PROJECT_ID: project untuk memproses penerjemahan mesin.
  • LOCATION: lokasi tempat tugas diproses.

Perintah sebelumnya menampilkan respons yang menyertakan ID alur kerja yang ditulis dalam format projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID.

Setelah tugas selesai, Anda dapat melihat hasilnya dengan mengkueri tugas dan memeriksa kolom translation_literals inline dalam respons setelah alur kerja selesai.

Contoh Terjemahan Interaktif

Untuk menerjemahkan string Hive SQL select 1 secara interaktif, Anda dapat menggunakan kueri berikut:

"tasks": {
  string: {
    "type": "HiveQL2BigQuery_Translation",
    "translation_details": {
      "source_target_mapping": {
        "source_spec": {
          "literal": {
            "relative_path": "input_file",
            "literal_string": "select 1"
          }
        }
      },
      "target_return_literals": "sql/input_file",
    }
  }
}

Anda dapat menggunakan relative_path yang diinginkan untuk literal, tetapi literal yang diterjemahkan hanya akan muncul dalam hasil jika Anda menyertakan sql/$relative_path dalam target_return_literals. Anda juga dapat menyertakan beberapa literal dalam satu kueri, di mana setiap jalur relatifnya harus disertakan dalam target_return_literals.

Panggilan ini akan menampilkan pesan yang berisi ID alur kerja yang dibuat di kolom "name":

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "task_name": { /*...*/ }
  },
  "state": "RUNNING"
}

Untuk mendapatkan status terbaru alur kerja, jalankan kueri GET. Tugas selesai saat "state" berubah menjadi COMPLETED. Jika tugas itu berhasil, Anda akan menemukan SQL yang diterjemahkan dalam pesan respons:

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "string": {
      "id": "0fedba98-7654-3210-1234-56789abcdef",
      "type": "HiveQL2BigQuery_Translation",
      /* ... */
      "taskResult": {
        "translationTaskResult": {
          "translatedLiterals": [
            {
              "relativePath": "sql/input_file",
              "literalString": "-- Translation time: 2023-10-05T21:50:49.885839Z\n-- Translation job ID: projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00\n-- Source: input_file\n-- Translated from: Hive\n-- Translated to: BigQuery\n\nSELECT\n    1\n;\n"
            }
          ],
          "reportLogMessages": [
            ...
          ]
        }
      },
      /* ... */
    }
  },
  "state": "COMPLETED",
  "createTime": "2023-10-05T21:50:49.543221Z",
  "lastUpdateTime": "2023-10-05T21:50:50.462758Z"
}

Pelajari output terjemahan

Setelah menjalankan tugas terjemahan, ambil hasilnya dengan menentukan ID alur kerja tugas terjemahan menggunakan berikut:

curl \
-H "Content-Type:application/json" \
-H "Authorization:Bearer TOKEN" -X GET https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Ganti kode berikut:

  • TOKEN: token untuk autentikasi. Untuk membuat token, gunakan perintah gcloud auth print-access-token atau OAuth 2.0 playground (gunakan cakupan https://www.googleapis.com/auth/cloud-platform).
  • PROJECT_ID: project untuk memproses terjemahan.
  • LOCATION: lokasi tempat tugas diproses.
  • WORKFLOW_ID: ID yang dibuat saat Anda membuat alur kerja terjemahan.

Responsnya berisi status alur kerja migrasi Anda, dan file yang telah selesai di target_return_literals.

Respons akan berisi status alur kerja migrasi Anda, dan file yang telah selesai di target_return_literals. Anda dapat melakukan polling pada endpoint ini untuk memeriksa status alur kerja.