Migrasi CLI Databricks

Artikel ini menjelaskan cara bermigrasi dari Databricks CLI versi 0.18 atau di bawahnya ke Databricks CLI versi 0.205 atau lebih tinggi. Databricks CLI versi 0.205 ke atas berada di Pratinjau Umum.

Untuk brevity, artikel ini mengacu pada Databricks CLI versi 0.18 ke bawah sebagai CLI "warisan", dan Databricks CLI versi 0.205 ke atas sebagai CLI "baru".

Untuk informasi selengkapnya tentang WARIS dan BARU, lihat:

• Databricks CLI (warisan) untuk CLI warisan.
• Apa itu Databricks CLI? untuk CLI baru.

Menghapus instalan CLI warisan

Jika Anda telah menginstal CLI warisan dan ingin menghapus instalannya, gunakan pip (atau pip3, tergantung pada versi Python Anda) untuk menjalankan uninstall perintah, sebagai berikut:

pip uninstall databricks-cli

Menginstal CLI baru

Untuk mempelajari cara menginstal CLI baru, lihat Menginstal atau memperbarui Databricks CLI.

Memverifikasi penginstalan CLI Anda

Jika Anda tidak yakin apakah Anda menggunakan CLI baru, ikuti instruksi di bagian ini untuk memverifikasi dan menyesuaikan sesuai kebutuhan. Sebelum Anda mengikuti instruksi ini, pastikan untuk keluar dari lingkungan virtual Python, conda lingkungan, atau lingkungan serupa.

Untuk memeriksa versi penginstalan default CLI Anda, jalankan perintah berikut:

databricks -v

Jika nomor versi bukan yang Anda harapkan, lakukan salah satu hal berikut:

• Jika Anda hanya ingin menggunakan satu versi CLI: hapus instalan semua versi CLI sebelumnya yang tidak ingin Anda gunakan lagi. Anda mungkin perlu memperbarui sytem PATH operasi Anda sehingga jalur ke versi CLI yang tersisa yang ingin Anda gunakan tercantum.
• Jika Anda ingin terus menggunakan beberapa versi CLI: prepend jalur lengkap ke versi CLI yang ingin Anda gunakan untuk masing-masing dan setiap panggilan ke CLI.
• Jika Anda ingin terus menggunakan beberapa versi CLI, tetapi Anda tidak ingin terus menambahkan jalur lengkap ke versi CLI yang paling sering Anda gunakan: pastikan bahwa jalur lengkap ke versi tersebut tercantum terlebih dahulu di sistem PATHoperasi Anda. Perhatikan bahwa Anda masih harus menambahkan jalur lengkap ke versi CLI yang tidak tercantum terlebih dahulu di sistem PATHoperasi Anda.

Untuk memperbarui sistem PATHoperasi Anda, lakukan hal berikut:

MacOS atau Linux

1. Cantumkan jalur tempat databricks diinstal dengan menjalankan salah satu perintah berikut:

   which -a databricks
   
   # Or:
   where databricks
   

2. Dapatkan jalur ke penginstalan yang ingin Anda gunakan tanpa menambahkan jalur lengkap ke masing-masing dan setiap panggilan ke CLI. Jika Anda tidak yakin jalur mana ini, jalankan jalur lengkap ke setiap lokasi, diikuti oleh -v, misalnya:

   /usr/local/bin/databricks -v
   

3. Untuk menempatkan jalur ke penginstalan yang ingin Anda gunakan terlebih dahulu di , PATHjalankan perintah berikut, ganti /usr/local/bin dengan jalur yang ingin Anda gunakan. Jangan tambahkan databricks ke akhir jalur ini. Contohnya:

   export PATH="/usr/local/bin:$PATH"
   

4. Untuk memverifikasi bahwa PATH telah diatur dengan benar untuk sesi terminal saat ini, jalankan databricks diikuti dan -v periksa nomor versi:

   databricks -v
   

5. Untuk mengatur PATH cara ini setiap kali Anda menghidupkan ulang terminal, tambahkan perintah dari langkah 3 ke file inisialisasi shell Anda. Misalnya, untuk Zshell, file ini biasanya terletak di ~/.zshrc. Untuk Bash, file ini biasanya terletak di ~/.bashrc. Untuk shell lain, lihat dokumentasi penyedia shell Anda.

6. Setelah memperbarui file inisialisasi shell, Anda harus memulai ulang terminal untuk menerapkan nilai yang diperbarui PATH .

Windows

1. Klik kanan penginstalan databricks yang ingin Anda gunakan tanpa menambahkan jalur lengkap ke masing-masing dan setiap panggilan ke CLI.

2. Klik Buka lokasi file.

3. Perhatikan jalur ke databricks, misalnya C:\Windows.

4. Pada menu Mulai , cari variabel Lingkungan.

5. Klik Edit variabel lingkungan untuk akun Anda.

6. Pilih variabel Jalur<username>

7. Klik Edit.

8. Klik Baru.

9. Masukkan jalur yang ingin Anda tambahkan, tanpa databricks.exe (seperti C:\Windows).

10. Gunakan tombol Pindah ke Atas untuk memindahkan jalur yang baru saja Anda tambahkan ke awal daftar.

11. Klik OK.

12. Untuk memverifikasi bahwa PATH telah diatur dengan benar, buka Prompt Perintah baru, jalankan databricks diikuti oleh -v, dan periksa nomor versi:

    databricks -v
    

Gunakan jenis autentikasi tambahan

CLI warisan dan CLI baru mendukung autentikasi token akses pribadi Azure Databricks. Namun, Databricks merekomendasikan agar Anda menggunakan jenis autentikasi Azure Databricks lainnya jika memungkinkan, yang hanya didukung CLI baru.

Jika Anda harus menggunakan autentikasi token akses pribadi Azure Databricks, Databricks menyarankan agar Anda menggunakan yang terkait dengan perwakilan layanan, bukan akun Azure Databricks atau pengguna ruang kerja. Lihat Mengelola prinsipal layanan.

CLI baru mendukung token ID Microsoft Entra selain token akses pribadi Azure Databricks. Token tambahan ini lebih aman karena biasanya kedaluwarsa dalam satu jam, sedangkan token akses pribadi Azure Databricks dapat berlaku dari satu hari hingga tanpa batas waktu. Ini sangat penting jika token secara tidak sengaja diperiksa ke dalam sistem kontrol versi yang dapat diakses oleh orang lain. Selain itu, CLI baru dapat secara otomatis me-refresh token tambahan ini ketika kedaluwarsa, sedangkan me-refresh token akses pribadi Azure Databricks adalah proses manual atau mungkin sulit untuk diotomatisasi.

Untuk informasi selengkapnya, lihat Autentikasi untuk Databricks CLI.

Grup perintah dan perbandingan perintah

Tabel berikut mencantumkan grup perintah CLI warisan dan grup perintah CLI baru yang setara. Jika ada perbedaan signifikan antara CLI, tabel tambahan mencantumkan perintah atau opsi CLI warisan dan perintah atau opsi CLI baru yang setara.

Grup perintah

Opsi configure

fs Perintah

Semua fs perintah dalam CLI warisan sama di CLI baru, kecuali fs mv yang tidak tersedia di CLI baru.

groups Perintah

pipelines Perintah

runs Perintah

secrets Perintah

tokens Perintah

unity-catalog grup perintah

unity-catalog <command> di CLI warisan menjadi hanya <command> di CLI baru.

workspace Perintah

Argumen default dan posisi

Sebagian besar perintah CLI baru memiliki setidaknya satu argumen default yang tidak memiliki opsi yang menyertainya. Beberapa perintah CLI baru memiliki dua argumen posisi atau lebih yang harus ditentukan dalam urutan tertentu dan yang tidak memiliki opsi yang menyertainya. Ini berbeda dari CLI warisan, di mana sebagian besar perintah memerlukan opsi untuk ditentukan untuk semua argumen. Misalnya, perintah CLI clusters get baru mengambil ID kluster sebagai argumen default. Namun, perintah CLI clusers get warisan mengharuskan Anda menentukan --cluster-id opsi bersama dengan ID kluster. Contohnya:

Untuk CLI warisan:

# This works with the legacy CLI.
databricks clusters get --cluster-id 1234-567890-a1b23c4d

# This does **not** work with the legacy CLI - "Error:
#   Missing None. One of ['cluster-id', 'cluster-name'] must be provided."
databricks clusters get 1234-567890-a1b23c4d

Untuk CLI baru:

# This works with the new CLI.
databricks clusters get 1234-567890-a1b23c4d

# This does **not** work with the new CLI - "Error: unknown flag: --cluster-id"
databricks clusters get --cluster-id 1234-567890-a1b23c4d

Sebagai contoh lain, perintah CLI grants get baru mengambil dua argumen default: jenis yang dapat diamankan diikuti dengan nama lengkap yang dapat diamankan. Namun, perintah CLI unity-catalog permissions get warisan mengharuskan Anda menentukan --<securable-type> opsi bersama dengan nama lengkap yang dapat diamankan. Contohnya:

Untuk CLI warisan:

databricks unity-catalog permissions get --schema main.default

Untuk CLI baru:

# This works with the new CLI.
databricks grants get schema main.default

# This does **not** work with the new CLI - "Error: unknown flag: --schema"
databricks grants get --schema main.default

Mode debug

CLI warisan menyediakan --debug opsi untuk menampilkan jejak tumpukan penuh pada kesalahan. Untuk CLI baru, --debug opsi tidak dikenali. Sebagai gantinya, gunakan opsi berikut:

• Gunakan --log-file <path> untuk menulis informasi log ke file yang ditentukan dalam <path>. Jika opsi ini tidak disediakan, informasi log adalah output ke stderr. Menentukan --log-file tanpa juga menentukan --log-level hasil tidak ada informasi log yang ditulis ke file.
• Gunakan --log-format <type> untuk menentukan format informasi yang dicatat. <type> bisa ( text default, jika tidak ditentukan) atau json.
• Gunakan --log-level <format> untuk menentukan tingkat informasi yang dicatat. Nilai yang diizinkan adalah disabled (default, jika tidak ditentukan), trace, , debug, infowarn, dan error.

Untuk CLI warisan, contoh berikut menunjukkan jejak tumpukan penuh pada kesalahan:

databricks fs ls / --debug

# Output:
#
# HTTP debugging enabled
# NoneType: None
# Error: The path / must start with "dbfs:/"

Untuk CLI baru, contoh berikut mencatat jejak tumpukan penuh ke file bernama new-cli-errors.log di direktori kerja saat ini. Jejak tumpukan ditulis ke file dalam format JSON:

databricks fs ls / --log-file new-cli-errors.log --log-format json --log-level trace

# Output:
#
# Error: expected dbfs path (with the dbfs:/ prefix): /
#
# (The full stack trace is also written to the new-cli-errors.log file.)

Pertanyaan umum

Bagian ini mencantumkan pertanyaan umum tentang migrasi dari warisan ke CLI baru.

Apa yang terjadi pada CLI warisan?

CLI warisan masih tersedia tetapi tidak menerima pembaruan yang tidak penting. Dokumentasi CLI warisan mencerminkan hal ini. Databricks merekomendasikan agar pengguna bermigrasi ke CLI baru sesegera mungkin.

CLI warisan selalu dalam keadaan Eksperimental dengan penafian bahwa Databricks merencanakan tidak ada fitur baru yang berfungsi untuk CLI warisan, dan CLI warisan tidak didukung melalui saluran dukungan Databricks.

Kapan CLI warisan tidak digunakan lagi?

CLI warisan selalu dalam keadaan Eksperimental dengan penafian bahwa Databricks merencanakan tidak ada fitur baru yang berfungsi untuk CLI warisan, dan CLI warisan tidak didukung melalui saluran dukungan Databricks.

Databricks belum menetapkan tanggal atau garis waktu untuk menghentikan CLI warisan. Namun, Databricks merekomendasikan agar pengguna bermigrasi ke CLI baru sesegera mungkin.

Kapan CLI baru akan dirilis sebagai tersedia secara umum (GA)?

Tanggal rilis atau garis waktu untuk merilis CLI baru karena GA belum ditetapkan. Ini akan bergantung pada umpan balik yang diterima Databricks dari pengguna selama Pratinjau Umum.

Apa perbedaan utama antara CLI warisan dan baru?

• CLI warisan dirilis sebagai paket Python. CLI baru dirilis sebagai executable mandiri dan tidak memerlukan dependensi runtime yang diinstal.
• CLI baru memiliki cakupan lengkap API REST Databricks. CLI warisan tidak.
• CLI baru tersedia sebagai Pratinjau Publik. CLI warisan tetap dalam keadaan Eksperimental.

Apakah CLI baru memiliki paritas fitur lengkap dengan CLI warisan?

CLI baru memiliki cakupan untuk hampir semua perintah dari CLI warisan. Namun, terutama tidak ada dari CLI baru adalah stacks grup perintah di CLI warisan. Selain itu, beberapa grup perintah CLI warisan seperti unity-catalog dan runs telah direfaktorkan ke dalam grup perintah baru di CLI baru. Untuk panduan migrasi, lihat informasi yang disediakan sebelumnya di artikel ini.

Bagaimana cara bermigrasi dari warisan ke CLI baru?

Untuk panduan migrasi, lihat informasi yang disediakan sebelumnya di artikel ini. Perhatikan bahwa CLI baru bukan pengganti drop-in untuk CLI warisan dan memerlukan beberapa penyiapan untuk berpindah dari warisan ke CLI baru.

Dapatkah penginstalan warisan dan CLI baru ada di komputer yang sama?

Ya. Penginstalan warisan dan CLI baru dapat ada di komputer yang sama, tetapi harus terletak di direktori yang berbeda. Karena executable keduanya bernama databricks, Anda harus mengontrol executable mana yang dijalankan secara default dengan mengonfigurasi mesin PATHAnda. Jika Anda ingin menjalankan CLI baru tetapi entah bagaimana secara tidak sengaja menjalankan CLI warisan sebagai gantinya, secara default CLI warisan akan menjalankan CLI baru dengan argumen yang sama dan menampilkan pesan peringatan berikut:

Databricks CLI <new-version-number> found at <new-path>
Your current PATH prefers running CLI <old-version-number> at <old-path>

Because both are installed and available in PATH,
I assume you are trying to run the newer version.

If you want to disable this behavior you can set DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION=1.

Executing CLI <new-version-number>...
-------------------------------------
Databricks CLI <new-version-number>

Seperti yang ditunjukkan dalam pesan peringatan sebelumnya, Anda dapat mengatur DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION variabel lingkungan ke untuk 1 menonaktifkan perilaku ini dan menjalankan CLI warisan sebagai gantinya.

Dapatkan bantuan

Untuk mendapatkan bantuan terkait migrasi dari CLI warisan ke CLI baru, lihat sumber daya berikut:

• Pusat Bantuan Databricks
• Jam Kerja Databricks