Databricks CLI geçişi

  • Makale

Bu makalede, Databricks CLI sürüm 0.18 veya altından Databricks CLI sürüm 0.205 veya üzeri sürüme nasıl geçiş yapılır açıklanmaktadır. Databricks CLI 0.205 ve üzeri sürümleri Genel Önizleme sürümündedir.

Kısa kullanım için bu makalede Databricks CLI 0.18 ve altı sürümleri "eski" CLI, Databricks CLI sürümleri ise 0.205 ve üzeri sürümleri "yeni" CLI olarak ifade eder.

Eski ve yeni CLI'ler hakkında daha fazla bilgi için bkz:

Eski CLI'yi kaldırma

Eski CLI yüklüyse ve kaldırmak istiyorsanız komutunu çalıştırmak uninstall için (veya pip3Python sürümünüze bağlı olarak) komutunu aşağıdaki gibi kullanın pip :

pip uninstall databricks-cli

Yeni CLI'yi yükleme

Yeni CLI'nın nasıl yükleneceğini öğrenmek için bkz . Databricks CLI'yı yükleme veya güncelleştirme.

CLI yüklemenizi doğrulama

Yeni CLI kullanıp kullanmadığınızdan emin değilseniz, gerektiği gibi doğrulamak ve ayarlamak için bu bölümdeki yönergeleri izleyin. Bu yönergeleri izlemeden önce Python sanal ortamlarından, conda ortamlarından veya benzer ortamlardan çıktığınıza emin olun.

VARSAYıLAN CLI yüklemenizin sürümünü denetlemek için aşağıdaki komutu çalıştırın:

databricks -v

Sürüm numarası beklediğiniz gibi değilse aşağıdakilerden birini yapın:

  • CLI'nin yalnızca bir sürümünü kullanmak istiyorsanız: CLI'nın artık kullanmak istemediğiniz önceki tüm sürümlerini kaldırın. Kullanmak istediğiniz CLI'nin PATH kalan sürümünün yolunun listelenmesi için işletim sisteminizi güncelleştirmeniz gerekebilir.
  • CLI'nin birden çok sürümünü kullanmaya devam etmek istiyorsanız: CLI'ya yapılan her çağrıda kullanmak istediğiniz CLI sürümünün tam yolunu belirtin.
  • CLI'nın birden çok sürümünü kullanmaya devam etmek istiyorsanız, ancak en sık kullandığınız CLI sürümüne tam yolu önceden göndermeye devam etmek istemiyorsanız: bu sürümün tam yolunun ilk olarak işletim sisteminizin PATHiçinde listelendiğinden emin olun. CLI'nın işletim sisteminizde PATHilk olarak listelenmeyen sürümlerine tam yolu eklemeye devam etmeniz gerektiğini unutmayın.

İşletim sisteminizin işletim sistemini PATHgüncelleştirmek için aşağıdakileri yapın:

Macos veya linux

  1. Aşağıdaki komutlardan birini çalıştırarak yüklendiği yolları databricks listeleyin:

    which -a databricks

# Or:
where databricks

  2. CLI'ya yapılan her çağrının tam yolunu önceden göndermeden kullanmak istediğiniz yükleme yolunu alın. Bunun hangi yol olduğundan emin değilseniz, her konumun tam yolunu ve ardından -vöğesini çalıştırın, örneğin:

    /usr/local/bin/databricks -v

  3. önce içinde PATHkullanmak istediğiniz yüklemenin yolunu koymak için aşağıdaki komutu çalıştırın ve yerine /usr/local/bin kullanmak istediğiniz yolu yazın. Bu yolun sonuna eklemeyin databricks . Örneğin:

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

  4. öğesinin PATH geçerli terminal oturumu için doğru ayarlandığını doğrulamak için komutunu çalıştırın databricks-v ve sürüm numarasını denetleyin:

    databricks -v

  5. Terminalinizi her yeniden başlattığınızda bu şekilde ayarlanmış olması PATH için, 3. adımdaki komutu kabuk başlatma dosyanıza ekleyin. Örneğin, Zshell için bu dosya genellikle konumunda ~/.zshrcbulunur. Bash için bu dosya genellikle konumunda ~/.bashrcbulunur. Diğer kabuklar için kabuk sağlayıcınızın belgelerine bakın.

  6. Kabuk başlatma dosyanızı güncelleştirdikten sonra, güncelleştirilmiş PATH değeri uygulamak için terminalinizi yeniden başlatmanız gerekir.

Windows

  1. CLI'ya yapılan her çağrının tam yolunu önceden göndermeden kullanmak istediğiniz yüklemesine databricks sağ tıklayın.

  2. Dosya konumunu aç'a tıklayın.

  3. örneğin databricksyolunu C:\Windowsnot edin.

  4. Başlat menüsünde Ortam değişkenlerini arayın.

  5. Hesabınız için ortam değişkenlerini düzenle'ye tıklayın.

  6. Için Kullanıcı değişkenleri <username> bölümünde Yol değişkenini seçin.

  7. Düzenle'yi tıklatın.

  8. Yeni'yi tıklatın.

  9. Eklemek istediğiniz yolu ( gibiC:\Windows) olmadan databricks.exe girin.

  10. Yeni eklediğiniz yolu listenin başına taşımak için Yukarı Taşı düğmesini kullanın.

  11. Tamam'a tıklayın.

  12. öğesinin PATH doğru ayarlandığını doğrulamak için yeni bir Komut İstemi açın, komutunu -vçalıştırın databricks ve sürüm numarasını denetleyin:

    databricks -v

Ek kimlik doğrulama türleri kullanma

Hem eski CLI hem de yeni CLI, Azure Databricks kişisel erişim belirteci kimlik doğrulamasını destekler. Ancak Databricks, mümkünse yalnızca yeni CLI tarafından desteklenen diğer Azure Databricks kimlik doğrulama türlerini kullanmanızı önerir.

Azure Databricks kişisel erişim belirteci kimlik doğrulamayı kullanmanız gerekiyorsa Databricks, Azure Databricks hesabı veya çalışma alanı kullanıcısı yerine hizmet sorumlusuyla ilişkili bir kimlik doğrulaması kullanmanızı önerir. Bkz. Hizmet sorumlularını yönetme.

Yeni CLI, Azure Databricks kişisel erişim belirteçlerine ek olarak Microsoft Entra Id belirteçlerini destekler. Bu ek belirteçler genellikle bir saat içinde süresi dolduğundan daha güvenlidir, ancak Azure Databricks kişisel erişim belirteçleri bir günden süresiz olarak geçerli olabilir. Bu, özellikle bir belirtecin başkaları tarafından erişilebilen sürüm denetim sistemlerine yanlışlıkla iade edilmesi durumunda önemlidir. Ayrıca yeni CLI, süresi dolduğunda bu ek belirteçleri otomatik olarak yenileyebilirken, Azure Databricks kişisel erişim belirteçlerini yenilemek el ile gerçekleştirilen bir işlemdir veya otomatikleştirmek zor olabilir.

Daha fazla bilgi için bkz . Databricks CLI için kimlik doğrulaması.

Komut grubu ve komut karşılaştırmaları

Aşağıdaki tabloda eski CLI komut grupları ve yeni CLI komut grubu eşdeğerleri listelemektedir. CLI'ler arasında önemli farklar varsa, ek tablolar eski CLI komutlarını veya seçeneklerini ve yeni CLI komutlarını veya seçenek eşdeğerlerini listeler.

Komut grupları

Eski komut grubu Yeni komut grubu
cluster-policies cluster-policies. Tüm komut adları aynıdır.
clusters clusters. Tüm komut adları aynıdır.
configure configure. Bkz . yapılandırma seçenekleri.
fs fs. Bkz . fs komutları.
groups groups. Bkz . grup komutları.
instance-pools instance-pools. Tüm komut adları aynıdır.
jobs jobs. Tüm komut adları aynıdır.
libraries libraries. dışındaki listtüm komut adları aynıdır. Komut list artık kullanılamıyor; bunun yerine veya cluster-status komutlarını kullanınall-cluster-statuses.
pipelines pipelines. Bkz. işlem hattı komutları.
repos repos. Tüm komut adları aynıdır.
runs jobs. Bkz . çalıştırma komutları.
secrets secrets. Bkz. gizli dizi komutları.
stack Yeni CLI'da kullanılamaz. Databricks bunun yerine Databricks Terraform sağlayıcısını kullanmanızı önerir.
tokens tokens. Bkz. belirteç komutları.
unity-catalog Çeşitli. Bkz . unity-catalog komut grupları.
workspace workspace. Bkz . çalışma alanı komutları.

configure Seçenekler

Eski seçenek Yeni seçenek
-o Eski CLI, OAuth kimlik doğrulaması için kullanır -o . Yeni CLI, CLI çıkışının metin mi yoksa JSON biçiminde mi olduğunu belirtmek için yeniden çalışır -o . Azure Databricks için geçerli değildir.
--oauth Azure Databricks için geçerli değildir.
-s veya --scope Azure Databricks için geçerli değildir.
-t veya --token -t veya --token (aynı)
-f veya --token-file Yeni CLI'da kullanılamaz.
--host --host (aynı)
--aad-token Azure Databricks kişisel erişim belirteci yerine istendiğinde bir Microsoft Entra Id (eski adıyla Azure Active Directory) belirteci kullanın --host ve belirtin.
--insecure Yeni CLI'da kullanılamaz.
--jobs-api-version Yeni CLI'da kullanılamaz. Yeni CLI yalnızca İşler API'sini 2.1 kullanır. Eski İşler API'sini 2.0 olarak çağırmak için eski CLI'yi kullanın ve bkz . İşler CLI'sı (eski).
--debug Yeni CLI'da hata ayıklama ve günlüğe kaydetme için bkz . Hata ayıklama modu.
--profile --profile (aynı) veya -p
-h veya --help -h veya --help (aynı)

fs Komut

Eski CLI'deki tüm fs komutlar, yeni CLI'da bulunmayanlar dışında fs mv yeni CLI'da aynıdır.

Eski komut Yeni komut
fs cat fs cat (aynı)
fs cp fs cp (aynı)
fs ls fs ls (aynı)
fs mkdirs fs mkdir
fs mv Yeni CLI'da kullanılamaz.
fs rm fs rm (aynı)

groups Komut

Eski komut Yeni komut
groups add-member groups patch
groups create groups create (aynı)
groups delete groups delete (aynı)
groups list groups list (aynı)
groups list-members groups list
groups list-parents groups list
groups remove-member groups patch

pipelines Komut

Eski komut Yeni komut
pipelines create pipelines create (aynı)
pipelines delete pipelines delete (aynı)
pipelines deploy pipelines create
pipelines edit pipelines update
pipelines get pipelines get (aynı)
pipelines list pipelines list-pipeline-eventsveya veya pipelines list-pipelinespipelines list-updates
pipelines reset pipelines reset (aynı)
pipelines start pipelines start update
pipelines stop pipelines stop (aynı)
pipelines update pipelines update (aynı)

runs Komut

Eski komut Yeni komut
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 Komut

Eski komut Yeni komut
secrets create-scope secrets create-scope (aynı)
secrets delete secrets delete-secret
secrets delete-acl secrets delete-acl (aynı)
secrets delete-scope secrets delete-scope (aynı)
secrets get-acl secrets get-acl (aynı)
secrets list secrets list-secrets
secrets list-acls secrets list-acls (aynı)
secrets list-scopes secrets list-scopes (aynı)
secrets put secrets put-secret
secrets put-acl secrets put-acl (aynı)
secrets write secrets put-secret
secrets write-acl secrets put-acl

tokens Komut

Eski komut Yeni komut
tokens create tokens create (aynı)
tokens list tokens list (aynı)
tokens revoke tokens delete

unity-catalog komut grupları

unity-catalog <command> eski CLI <command> yalnızca yeni CLI olur.

Eski komut grubu Yeni komut grubu
unity-catalog catalogs catalogs (aynı ama bırak unity-catalog)
unity-catalog external-locations external-locations (aynı ama bırak unity-catalog)
unity-catalog lineage Yeni CLI'da kullanılamaz. Bkz. Veri kökeni API'si.
unity-catalog metastores metastores (aynı ama bırak unity-catalog)
unity-catalog permissions grants
unity-catalog providers providers (aynı ama bırak unity-catalog)
unity-catalog recipients recipients (aynı ama bırak unity-catalog)
unity-catalog schemas schemas (aynı ama bırak unity-catalog)
unity-catalog shares shares (aynı ama bırak unity-catalog)
unity-catalog storage-credentials storage-credentials (aynı ama bırak unity-catalog)
unity-catalog tables tables (aynı ama bırak unity-catalog)

workspace Komut

Eski komut Yeni komut
workspace delete workspace delete (aynı)
workspace export workspace export (aynı)
workspace export-dir workspace export
workspace import workspace import (aynı)
workspace import-dir workspace import
workspace list workspace list (aynı)
workspace ls workspace list
workspace mkdirs workspace mkdirs (aynı)
workspace rm workspace delete

Varsayılan ve konumsal bağımsız değişkenler

Yeni CLI komutlarının çoğunda eşlik eden seçeneği olmayan en az bir varsayılan bağımsız değişken bulunur. Bazı yeni CLI komutlarında belirli bir sırada belirtilmesi gereken ve eşlik eden seçenekleri olmayan iki veya daha fazla konumsal bağımsız değişken bulunur. Bu, çoğu komutun tüm bağımsız değişkenler için seçeneklerin belirtilmesi gereken eski CLI'dan farklıdır. Örneğin, yeni CLI'nın clusters get komutu varsayılan bağımsız değişken olarak bir küme kimliği alır. Ancak, eski CLI'nin clusers get komutu küme kimliğiyle birlikte bir --cluster-id seçenek belirtmenizi gerektirir. Örneğin:

Eski CLI için:

# 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

Yeni CLI için:

# 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

Başka bir örnek olarak, yeni CLI'nın grants get komutu iki varsayılan bağımsız değişken alır: güvenliği sağlanabilir tür ve ardından güvenli hale getirilebilir tam adı. Ancak, eski CLI'nin unity-catalog permissions get komutu, güvenli hale getirilebilir tam adıyla birlikte bir --<securable-type> seçenek belirtmenizi gerektirir. Örneğin:

Eski CLI için:

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

Yeni CLI için:

# 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

Hata ayıklama modu

Eski CLI, hatada tam yığın izlemesini gösterme seçeneği sağlar --debug . Yeni CLI için --debug seçenek tanınmaz. Bunun yerine aşağıdaki seçenekleri kullanın:

  • günlük bilgilerini içinde <path>belirtilen dosyaya yazmak için kullanın--log-file <path>. Bu seçenek sağlanmazsa, günlük bilgileri stderr'a verilir. --log-file Ayrıca belirtilmeden belirtilmesi--log-level, dosyaya hiçbir günlük bilgisi yazılmamasıyla sonuçlanıyor.
  • Günlüğe kaydedilen bilgilerin biçimini belirtmek için kullanın --log-format <type> . <type>(belirtilmemişse varsayılan) veya jsonolabilir text .
  • Günlüğe kaydedilen bilgi düzeyini belirtmek için kullanın --log-level <format> . İzin verilen değerler (belirtilmezse varsayılan), trace, debug, info, warnve errordeğerleridir disabled .

Eski CLI için aşağıdaki örnekte hata üzerinde tam yığın izlemesi gösterilmektedir:

databricks fs ls / --debug

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

Yeni CLI için aşağıdaki örnek, tam yığın izlemesini geçerli çalışma dizininde adlı new-cli-errors.log bir dosyaya günlüğe kaydeder. Yığın izlemesi dosyaya JSON biçiminde yazılır:

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.)

Sık sorulan sorular

Bu bölümde, eskiden yeni CLI'ya geçişle ilgili sık sorulan sorular listelenir.

Eski CLI'ye ne oluyor?

Eski CLI hala kullanılabilir ancak kritik olmayan güncelleştirmeleri almıyor. Eski CLI belgeleri bunu yansıtır. Databricks, kullanıcıların yeni CLI'ya en kısa sürede geçişlerini önerir.

Eski CLI, Databricks'in eski CLI için yeni özellik çalışması planlamadığını ve eski CLI'nin Databricks destek kanalları aracılığıyla desteklenmediğini bildiren bir bildirimle her zaman Deneysel bir durumda olmuştur.

Eski CLI ne zaman kullanım dışı bırakılacak?

Eski CLI, Databricks'in eski CLI için yeni özellik çalışması planlamadığını ve eski CLI'nin Databricks destek kanalları aracılığıyla desteklenmediğini bildiren bir bildirimle her zaman Deneysel bir durumda olmuştur.

Databricks, eski CLI'yi kullanımdan kaldırmaya yönelik bir tarih veya zaman çizelgesi oluşturmadı. Ancak Databricks, kullanıcıların yeni CLI'ya en kısa sürede geçişlerini önerir.

Yeni CLI ne zaman genel kullanıma sunulacak (GA) olacak?

Yeni CLI'yi GA olarak yayınlamak için bir yayın tarihi veya zaman çizelgesi oluşturulmadı. Bu, Databricks'in Genel Önizleme sırasında kullanıcılardan aldığı geri bildirimlere bağlıdır.

Eski ve yeni CLI'ler arasındaki temel farklar nelerdir?

  • Eski CLI bir Python paketi olarak yayımlandı. Yeni CLI tek başına yürütülebilir dosya olarak yayınlanır ve herhangi bir çalışma zamanı bağımlılığının yüklenmesi gerekmez.
  • Yeni CLI, Databricks REST API'lerinin tam kapsamına sahiptir. Eski CLI bunu yapmaz.
  • Yeni CLI, Genel Önizleme olarak kullanılabilir. Eski CLI Deneysel durumda kalır.

Yeni CLI,eski CLI ile tam özellik eşliğine sahip mi?

Yeni CLI, eski CLI'dan neredeyse tüm komutların kapsamına sahiptir. Ancak, özellikle yeni CLI'da bulunmayanlar, eski CLI'daki komut grubudur stacks . Ayrıca ve gibi unity-catalogruns birkaç eski CLI komut grubu yeni CLI'da yeni komut grupları halinde yeniden düzenlenmiş durumdadır. Geçiş kılavuzu için bu makalenin önceki bölümlerinde sağlanan bilgilere bakın.

Eski sürümden yeni CLI'ya geçiş Nasıl yaparım??

Geçiş kılavuzu için bu makalenin önceki bölümlerinde sağlanan bilgilere bakın. Yeni CLI'nın eski CLI'nin yerine geçilmediğini ve eski CLI'dan yeni CLI'ye geçmek için bazı ayarların gerekli olduğunu unutmayın.

Eski ve yeni CLI'lerin yüklemeleri aynı makinede bulunabilir mi?

Evet. Eski ve yeni CLI'lerin yüklemeleri aynı makinede bulunabilir, ancak farklı dizinlerde bulunmaları gerekir. Yürütülebilirlerin her ikisi de olarak adlandırıldığından databricks, makinenizin PATHöğesini yapılandırarak hangi yürütülebilir dosyanın varsayılan olarak çalıştırıldığından denetleyebilirsiniz. Yeni CLI'yı çalıştırmak ancak bunun yerine bir şekilde yanlışlıkla eski CLI'yi çalıştırmak istiyorsanız, varsayılan olarak eski CLI yeni CLI'yi aynı bağımsız değişkenlerle çalıştırır ve aşağıdaki uyarı iletisini gösterir:

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>

Yukarıdaki uyarı iletisinde gösterildiği gibi, ortam değişkenini DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION bu davranışı devre dışı bırakmak ve bunun yerine eski CLI'yi çalıştırmak için 1 olarak ayarlayabilirsiniz.

Yardım alın

Eski CLI'dan yeni CLI'ya geçiş konusunda yardım almak için aşağıdaki kaynaklara bakın: