Migrasi CLI Databricks

Artikel
05/03/2024

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

Cantumkan jalur tempat databricks diinstal dengan menjalankan salah satu perintah berikut:
```
which -a databricks

# Or:
where databricks
```
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
```
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"
```
Untuk memverifikasi bahwa PATH telah diatur dengan benar untuk sesi terminal saat ini, jalankan databricks diikuti dan -v periksa nomor versi:
```
databricks -v
```
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.
Setelah memperbarui file inisialisasi shell, Anda harus memulai ulang terminal untuk menerapkan nilai yang diperbarui PATH .

Windows

Klik kanan penginstalan databricks yang ingin Anda gunakan tanpa menambahkan jalur lengkap ke masing-masing dan setiap panggilan ke CLI.
Klik Buka lokasi file.
Perhatikan jalur ke databricks, misalnya C:\Windows.
Pada menu Mulai , cari variabel Lingkungan.
Klik Edit variabel lingkungan untuk akun Anda.
Pilih variabel Jalur di bagian Variabel pengguna untuk<username>.
Klik Edit.
Klik Baru.
Masukkan jalur yang ingin Anda tambahkan, tanpa databricks.exe (seperti C:\Windows).
Gunakan tombol Pindah ke Atas untuk memindahkan jalur yang baru saja Anda tambahkan ke awal daftar.
Klik OK.
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

Grup perintah warisan	Grup perintah baru
`cluster-policies`	`cluster-policies`. Semua nama perintah sama.
`clusters`	`clusters`. Semua nama perintah sama.
`configure`	`configure`. Lihat opsi konfigurasi.
`fs`	`fs`. Lihat perintah fs.
`groups`	`groups`. Lihat perintah grup.
`instance-pools`	`instance-pools`. Semua nama perintah sama.
`jobs`	`jobs`. Semua nama perintah sama.
`libraries`	`libraries`. Semua nama perintah sama kecuali untuk `list`. Perintah `list` tidak lagi tersedia; gunakan perintah atau `cluster-status` sebagai gantinya`all-cluster-statuses`.
`pipelines`	`pipelines`. Lihat perintah alur.
`repos`	`repos`. Semua nama perintah sama.
`runs`	`jobs`. Lihat menjalankan perintah.
`secrets`	`secrets`. Lihat perintah rahasia.
`stack`	Tidak tersedia di CLI baru. Databricks merekomendasikan agar Anda menggunakan penyedia Databricks Terraform sebagai gantinya.
`tokens`	`tokens`. Lihat perintah token.
`unity-catalog`	Berbagai. Lihat grup perintah unity-catalog.
`workspace`	`workspace`. Lihat perintah ruang kerja.

Opsi `configure`

Opsi warisan	Opsi baru
`-o`	CLI warisan `-o` menggunakan untuk autentikasi OAuth. CLI baru menggunakan `-o` kembali untuk menentukan apakah output CLI dalam format teks atau JSON. Tidak berlaku untuk Azure Databricks.
`--oauth`	Tidak berlaku untuk Azure Databricks.
`-s` atau `--scope`	Tidak berlaku untuk Azure Databricks.
`-t` atau `--token`	`-t` atau `--token` (sama)
`-f` atau `--token-file`	Tidak tersedia di CLI baru.
`--host`	`--host` (sama)
`--aad-token`	Gunakan `--host` dan tentukan token ID Microsoft Entra (sebelumnya Azure Active Directory) saat diminta alih-alih token akses pribadi Azure Databricks.
`--insecure`	Tidak tersedia di CLI baru.
`--jobs-api-version`	Tidak tersedia di CLI baru. CLI baru hanya menggunakan Jobs API 2.1. Untuk memanggil Jobs API 2.0 warisan, gunakan CLI warisan dan lihat Jobs CLI (warisan).
`--debug`	Untuk penelusuran kesalahan dan pengelogan di CLI baru, lihat Mode debug.
`--profile`	`--profile` (sama) atau `-p`
`-h` atau `--help`	`-h` atau `--help` (sama)

`fs` Perintah

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

Perintah warisan	Perintah baru
`fs cat`	`fs cat` (sama)
`fs cp`	`fs cp` (sama)
`fs ls`	`fs ls` (sama)
`fs mkdirs`	`fs mkdir`
`fs mv`	Tidak tersedia di CLI baru.
`fs rm`	`fs rm` (sama)

`groups` Perintah

Perintah warisan	Perintah baru
`groups add-member`	`groups patch`
`groups create`	`groups create` (sama)
`groups delete`	`groups delete` (sama)
`groups list`	`groups list` (sama)
`groups list-members`	`groups list`
`groups list-parents`	`groups list`
`groups remove-member`	`groups patch`

`pipelines` Perintah

Perintah warisan	Perintah baru
`pipelines create`	`pipelines create` (sama)
`pipelines delete`	`pipelines delete` (sama)
`pipelines deploy`	`pipelines create`
`pipelines edit`	`pipelines update`
`pipelines get`	`pipelines get` (sama)
`pipelines list`	`pipelines list-pipeline-events` atau `pipelines list-pipelines` atau `pipelines list-updates`
`pipelines reset`	`pipelines reset` (sama)
`pipelines start`	`pipelines start update`
`pipelines stop`	`pipelines stop` (sama)
`pipelines update`	`pipelines update` (sama)

`runs` Perintah

Perintah warisan	Perintah baru
`runs cancel`	`jobs cancel-run`
`runs get`	`jobs get-run`
`runs get-output`	`jobs get-run-output`
`runs list`	`jobs list-runs`
`runs submit`	`jobs submit`

`secrets` Perintah

Perintah warisan	Perintah baru
`secrets create-scope`	`secrets create-scope` (sama)
`secrets delete`	`secrets delete-secret`
`secrets delete-acl`	`secrets delete-acl` (sama)
`secrets delete-scope`	`secrets delete-scope` (sama)
`secrets get-acl`	`secrets get-acl` (sama)
`secrets list`	`secrets list-secrets`
`secrets list-acls`	`secrets list-acls` (sama)
`secrets list-scopes`	`secrets list-scopes` (sama)
`secrets put`	`secrets put-secret`
`secrets put-acl`	`secrets put-acl` (sama)
`secrets write`	`secrets put-secret`
`secrets write-acl`	`secrets put-acl`

`tokens` Perintah

Perintah warisan	Perintah baru
`tokens create`	`tokens create` (sama)
`tokens list`	`tokens list` (sama)
`tokens revoke`	`tokens delete`

`unity-catalog` grup perintah

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

Grup perintah warisan	Grup perintah baru
`unity-catalog catalogs`	`catalogs` (sama tapi jatuhkan `unity-catalog`)
`unity-catalog external-locations`	`external-locations` (sama tapi jatuhkan `unity-catalog`)
`unity-catalog lineage`	Tidak tersedia di CLI baru. Lihat Mengambil silsilah data menggunakan DATA Lineage REST API.
`unity-catalog metastores`	`metastores` (sama tapi jatuhkan `unity-catalog`)
`unity-catalog permissions`	`grants`
`unity-catalog providers`	`providers` (sama tapi jatuhkan `unity-catalog`)
`unity-catalog recipients`	`recipients` (sama tapi jatuhkan `unity-catalog`)
`unity-catalog schemas`	`schemas` (sama tapi jatuhkan `unity-catalog`)
`unity-catalog shares`	`shares` (sama tapi jatuhkan `unity-catalog`)
`unity-catalog storage-credentials`	`storage-credentials` (sama tapi jatuhkan `unity-catalog`)
`unity-catalog tables`	`tables` (sama tapi jatuhkan `unity-catalog`)

`workspace` Perintah

Perintah warisan	Perintah baru
`workspace delete`	`workspace delete` (sama)
`workspace export`	`workspace export` (sama)
`workspace export-dir`	`workspace export`
`workspace import`	`workspace import` (sama)
`workspace import-dir`	`workspace import`
`workspace list`	`workspace list` (sama)
`workspace ls`	`workspace list`
`workspace mkdirs`	`workspace mkdirs` (sama)
`workspace rm`	`workspace delete`

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?

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:

Bagikan melalui

Migrasi CLI Databricks

Menghapus instalan CLI warisan

Menginstal CLI baru

Memverifikasi penginstalan CLI Anda

Macos atau linux

Windows

Gunakan jenis autentikasi tambahan

Grup perintah dan perbandingan perintah

Grup perintah

Opsi `configure`

`fs` Perintah

`groups` Perintah

`pipelines` Perintah

`runs` Perintah

`secrets` Perintah

`tokens` Perintah

`unity-catalog` grup perintah

`workspace` Perintah

Argumen default dan posisi

Mode debug

Pertanyaan umum

Apa yang terjadi pada CLI warisan?

Kapan CLI warisan tidak digunakan lagi?

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

Apa perbedaan utama antara CLI warisan dan baru?

Apakah CLI baru memiliki paritas fitur lengkap dengan CLI warisan?

Bagaimana cara bermigrasi dari warisan ke CLI baru?

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

Dapatkan bantuan

Saran dan Komentar

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Migrasi CLI Databricks

Menghapus instalan CLI warisan

Menginstal CLI baru

Memverifikasi penginstalan CLI Anda

Macos atau linux

Windows

Gunakan jenis autentikasi tambahan

Grup perintah dan perbandingan perintah

Grup perintah

Opsi configure

fs Perintah

groups Perintah

pipelines Perintah

runs Perintah

secrets Perintah

tokens Perintah

unity-catalog grup perintah

workspace Perintah

Argumen default dan posisi

Mode debug

Pertanyaan umum

Apa yang terjadi pada CLI warisan?

Kapan CLI warisan tidak digunakan lagi?

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

Apa perbedaan utama antara CLI warisan dan baru?

Apakah CLI baru memiliki paritas fitur lengkap dengan CLI warisan?

Bagaimana cara bermigrasi dari warisan ke CLI baru?

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

Dapatkan bantuan

Saran dan Komentar

Saran dan Komentar

Sumber Daya Tambahan:

Opsi `configure`

`fs` Perintah

`groups` Perintah

`pipelines` Perintah

`runs` Perintah

`secrets` Perintah

`tokens` Perintah

`unity-catalog` grup perintah

`workspace` Perintah