Beberapa atau semua informasi di halaman ini mungkin tidak berlaku untuk Trusted Cloud oleh S3NS.

Halaman ini diterjemahkan oleh Cloud Translation API.

Menerjemahkan kueri SQL dengan translation API

Dokumen ini menjelaskan cara menggunakan API terjemahan di BigQuery untuk menerjemahkan skrip yang ditulis dalam dialek SQL lainnya ke dalam kueri GoogleSQL. API terjemahan dapat menyederhanakan proses memigrasikan beban kerja ke BigQuery.

Sebelum memulai

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

Pastikan Anda memiliki semua izin yang diperlukan.
Mengaktifkan BigQuery Migration API.
Mengumpulkan file sumber yang berisi skrip dan kueri SQL yang akan diterjemahkan.
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 MigrationWorkflow Editor (roles/bigquerymigration.editor) peran IAM 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 API terjemahan:

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 seperti berikut:

Di Trusted Cloud konsol, buka halaman BigQuery Migration API.

Buka BigQuery Migration API
Klik Enable.

Mengupload file input ke Cloud Storage

Jika ingin menggunakan konsol Trusted 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 cara membuat bucket dan mengupload file ke Cloud Storage, lihat Membuat bucket dan Mengupload objek dari sistem file.

Jenis tugas yang didukung

API terjemahan dapat menerjemahkan dialek SQL berikut ke dalam GoogleSQL:

Amazon Redshift SQL - Redshift2BigQuery_Translation
Apache HiveQL dan Beeline CLI - HiveQL2BigQuery_Translation
Apache Spark SQL - SparkSQL2BigQuery_Translation
Azure Synapse T-SQL - AzureSynapse2BigQuery_Translation
Greenplum SQL - Greenplum2BigQuery_Translation
IBM Db2 SQL - Db22BigQuery_Translation
IBM Netezza SQL dan NZPLSQL - Netezza2BigQuery_Translation
MySQL SQL - 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
Teradata dan Teradata Vantage - Teradata2BigQuery_Translation
Vertica SQL - Vertica2BigQuery_Translation

Menangani fungsi SQL yang tidak didukung dengan UDF helper

Saat menerjemahkan SQL dari dialek sumber ke BigQuery, beberapa fungsi mungkin tidak memiliki padanan langsung. Untuk mengatasi hal ini, BigQuery Migration Service (dan komunitas BigQuery yang lebih luas) menyediakan fungsi yang ditentukan pengguna (UDF) helper yang mereplikasi perilaku fungsi dialek sumber yang tidak didukung ini.

UDF ini sering ditemukan dalam set data publik bqutil, sehingga kueri yang diterjemahkan dapat mereferensikannya pada awalnya menggunakan format bqutil.<dataset>.<function>(). Misalnya, bqutil.fn.cw_count().

Pertimbangan penting untuk lingkungan produksi:

Meskipun bqutil menawarkan akses yang mudah ke UDF helper ini untuk terjemahan dan pengujian awal, bergantung langsung pada bqutil untuk beban kerja produksi tidak direkomendasikan karena beberapa alasan:

Kontrol versi: Project bqutil menghosting versi terbaru UDF ini, yang berarti definisinya dapat berubah dari waktu ke waktu. Bergantung langsung pada bqutil dapat menyebabkan perilaku yang tidak terduga atau perubahan yang merusak dalam kueri produksi Anda jika logika UDF diperbarui.
Isolasi dependensi: Men-deploy UDF ke project Anda sendiri akan mengisolasi lingkungan produksi dari perubahan eksternal.
Penyesuaian: Anda mungkin perlu mengubah atau mengoptimalkan UDF ini agar lebih sesuai dengan logika bisnis atau persyaratan performa tertentu. Hal ini hanya dapat dilakukan jika berada dalam project Anda sendiri.
Keamanan dan tata kelola: Kebijakan keamanan organisasi Anda mungkin membatasi akses langsung ke set data publik seperti bqutil untuk pemrosesan data produksi. Menyalin UDF ke lingkungan terkontrol Anda sesuai dengan kebijakan tersebut.

Men-deploy UDF helper ke project Anda:

Untuk penggunaan produksi yang andal dan stabil, Anda harus men-deploy UDF helper ini ke project dan set data Anda sendiri. Tindakan ini memberi Anda kontrol penuh atas versi, penyesuaian, dan aksesnya. Untuk petunjuk mendetail tentang cara men-deploy UDF ini, lihat panduan deployment UDF di GitHub. Panduan ini menyediakan skrip dan langkah-langkah yang diperlukan untuk menyalin UDF ke lingkungan Anda.

Lokasi

API terjemahan tersedia di lokasi pemrosesan berikut:

	Deskripsi region	Nama region	Detail
Asia Pasifik
	Delhi	`asia-south2`
	Hong Kong	`asia-east2`
	Jakarta	`asia-southeast2`
	Melbourne	`australia-southeast2`
	Mumbai	`asia-south1`
	Osaka	`asia-northeast2`
	Seoul	`asia-northeast3`
	Singapura	`asia-southeast1`
	Sydney	`australia-southeast1`
	Taiwan	`asia-east1`
	Tokyo	`asia-northeast1`
Eropa
	Belgia	`europe-west1`	CO Rendah₂
	Berlin	`europe-west10`	CO Rendah₂
	Multi-region Uni Eropa	`eu`
	Finlandia	`europe-north1`	CO Rendah₂
	Frankfurt	`europe-west3`	CO Rendah₂
	London	`europe-west2`	CO Rendah₂
	Madrid	`europe-southwest1`	CO Rendah₂
	Milan	`europe-west8`
	Belanda	`europe-west4`	CO Rendah₂
	Paris	`europe-west9`	CO Rendah₂
	Stockholm	`europe-north2`	CO₂ Rendah
	Turin	`europe-west12`
	Warsawa	`europe-central2`
	Zürich	`europe-west6`	CO Rendah₂
Amerika
	Columbus, Ohio	`us-east5`
	Dallas	`us-south1`	CO Rendah₂
	Iowa	`us-central1`	CO₂ Rendah
	Las Vegas	`us-west4`
	Los Angeles	`us-west2`
	Meksiko	`northamerica-south1`
	Northern Virginia	`us-east4`
	Oregon	`us-west1`	CO Rendah₂
	Quebec	`northamerica-northeast1`	CO₂ Rendah
	Sao Paulo	`southamerica-east1`	CO₂ Rendah
	Salt Lake City	`us-west3`
	Santiago	`southamerica-west1`	CO Rendah₂
	South Carolina	`us-east1`
	Toronto	`northamerica-northeast2`	CO Rendah₂
	Multi-region AS	`us`
Afrika
	Johannesburg	`africa-south1`
MiddleEast
	Dammam	`me-central2`
	Doha	`me-central1`
	Israel	`me-west1`

Mengirim tugas terjemahan

Untuk mengirimkan tugas terjemahan menggunakan Translation API, gunakan metode projects.locations.workflows.create dan berikan instance resource MigrationWorkflow 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 tempat file input dan 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\"
              }
            },
            \"target_types\": \"TARGET_TYPES\",
        }
      }
  }
  }" \
  -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 output terjemahan.
BASE: URI dasar untuk semua file yang dibaca sebagai sumber terjemahan.
TARGET_TYPES (opsional): jenis output yang dihasilkan. Jika tidak ditentukan, SQL akan dibuat.
- sql (default): File kueri SQL yang diterjemahkan.
- suggestion: Saran yang dibuat AI.
Output disimpan dalam subfolder di direktori output. Subfolder diberi nama berdasarkan nilai di TARGET_TYPES.
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 yang diperbarui untuk alur kerja, jalankan kueri GET. Tugas akan mengirimkan output ke Cloud Storage seiring berjalannya tugas. state tugas berubah menjadi COMPLETED setelah semua target_types yang diminta dibuat. Jika tugas berhasil, Anda dapat menemukan kueri SQL yang diterjemahkan di gs://my_data_bucket/teradata/output.

Contoh terjemahan batch dengan saran AI

Contoh berikut menerjemahkan skrip Teradata SQL yang berada di direktori Cloud Storage gs://my_data_bucket/teradata/input/ dan menyimpan hasil di direktori Cloud Storage gs://my_data_bucket/teradata/output/ dengan saran AI tambahan:

{
  "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/"
             }
          },
          "target_types": "suggestion",
       }
    }
  }
}

Setelah tugas berhasil berjalan, saran AI dapat ditemukan di direktori Cloud Storage gs://my_data_bucket/teradata/output/suggestion.

Membuat tugas terjemahan interaktif dengan input dan output string literal

Perintah curl berikut membuat tugas terjemahan dengan input dan output literal string. 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 ingin ditampilkan langsung oleh pengguna 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 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.

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. Dalam hal ini, 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 yang diperbarui untuk alur kerja, jalankan kueri GET. Tugas selesai saat "state" berubah menjadi COMPLETED. Jika tugas 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 perintah 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.