Bildirim temelli Otomasyon Paketleri proje şablonları

Bildirim temelli Otomasyon Paketleri (eski adıyla Databricks Varlık Paketleri), işler, işlem hatları ve not defterleri gibi Databricks kaynaklarını kaynak dosya olarak tanımlar, altyapı ve diğer kaynakları sağlamak için bu kaynak dosyalara meta veriler eklemenize ve tümü tek bir dağıtılabilir proje olarak paketlenmiş bir projenin uçtan uca tanımını sağlamanıza olanak tanır. Bkz. Bildirim temelli Otomasyon Paketleri nelerdir?.

Paket şablonları, kullanıcıların bir dağıtım işlem hattında ortak olan klasör yapıları, derleme adımları ve görevleri, testleri ve diğer DevOps kod olarak altyapı (IaC) özniteliklerini oluşturarak tutarlı ve yinelenebilir bir şekilde paket oluşturmasına olanak tanır.

Örneğin, yüklemeden sonra zaman alan bir derleme adımıyla özel paketler gerektiren işleri düzenli olarak çalıştırırsanız, özel kapsayıcı ortamını belirten bir paket şablonu oluşturarak geliştirme döngünüzü hızlandırabilirsiniz.

Databricks, varsayılan paket şablonları kümesi sağlar, ancak özel paket şablonları da oluşturabilirsiniz. Kullanıcılar daha sonra bundle init komutunukullanarak varsayılan şablonu veya özel şablonunuzu belirterek paketleri başlatabilir.

Şablon kullanarak paket oluşturma

Paketinizi oluşturmak için Azure Databricks paket şablonu kullanmak için Databricks CLIbundle init komutunu kullanın, kullanılacak şablonun adını belirtin veya çalışma alanında paket oluştururken kullanılabilir bir şablon seçin. Bkz. Paket oluşturma.

Örneğin, aşağıdaki komut varsayılan Python paket şablonunu kullanarak bir paket oluşturur:

databricks bundle init default-python

Özel paket şablonu kullanmak için, şablonun yerel yolunu veya uzak URL'sini Databricks CLIbundle init komutuna geçirin.

Örneğin, aşağıdaki komut Özel Paket Şablonu Öğreticisi'nde dab-container-templateoluşturulan şablonu kullanır:

databricks bundle init /projects/my-custom-bundle-templates/dab-container-template

Bir şablon belirtmezseniz, bundle init komutu aralarından seçim yapabileceğiniz kullanılabilir varsayılan şablonlar kümesini ister.

Varsayılan paket şablonları

Azure Databricks aşağıdaki varsayılan paket şablonlarını sağlar:

Şablon	Açıklama
default-minimal	Boş paket oluşturmaya yönelik bir şablon. Bu şablon yalnızca gerekli dosyaları içerir ve örnek kod içermez ve ayrıca temel katalog değişkenlerini yapılandırılır. Bu, hızlı bir şekilde yeni paket projeleri oluşturmanıza olanak tanır. Bkz. varsayılan-en az.
default-python	Databricks ile Python kullanmaya yönelik bir şablon. Bu şablon bir iş ve ETL işlem hattı içeren bir paket oluşturur ve uv gerektirir. Bkz. default-python.
default-scala	Scala'nın Databricks ile kullanılmasına yönelik bir şablon. Bu şablon, sunucusuz işlem için dağıtılacak şekilde yapılandırılmış bir Scala JAR oluşturan bir paket oluşturur. Bkz. default-scala.
default-sql	Databricks ile SQL kullanmaya yönelik bir şablon. Bu şablon, SQL ambarı üzerinde SQL sorguları çalıştıran bir işi tanımlayan bir yapılandırma dosyası içerir. Bkz. default-sql.
dbt-sql	Yerel geliştirme için dbt-core ve dağıtım paketlerinden yararlanan bir şablon. Bu şablon, dbt görevi olan bir işi tanımlayan yapılandırmanın yanı sıra dağıtılan dbt işleri için dbt profillerini tanımlayan bir yapılandırma dosyasını içerir. Bkz. dbt-sql.
mlops-stacks	Yeni MLOps Stacks projelerini başlatmak için gelişmiş bir tam yığın şablonu. Bkz. mlops-stacks ve MLOps Yığınları İçin Bildirim Temelli Otomasyon Paketleri.
pydabs	YAML yerine default-python kullanan şablonun değiştirilmiş sürümü. Bkz. pydabs.

özel paket şablonları

Paket şablonları, oluşturabileceğiniz özel paket şablonlarında esneklik sağlayan Go paketi şablon oluşturma söz dizimini kullanır. Go paket şablonu belgelerine bakın.

Proje yapısı şablonu

En azından bir paket şablonu projesinin şunları içermesi gerekir:

• Proje kökünde paket proje adı için bir kullanıcı istemi özelliği tanımlayan bir databricks_template_schema.json dosyası. Bkz. Şablon şeması.
• databricks.yml.tmpl Şablonla oluşturulan tüm paketler için yapılandırmayı tanımlayan bir template klasörde bulunan dosya. Dosyanız databricks.yml.tmpl ek *.yml.tmpl yapılandırma şablonlarına başvuruda bulunuyorsa bunların eşlemedeki include konumunu belirtin. Bkz. Yapılandırma şablonları.

Ayrıca, klasör yapısı ve paket şablonu projesi template klasörünün dahil edilen dosyaları, şablonla oluşturulan paketlerle yansıtılır. Örneğin, şablonun src klasöründe basit bir not defteri ve resources klasöründe not defterini çalıştıran bir iş tanımı içeren bir paket oluşturmasını istiyorsanız, şablon projenizi şu şekilde düzenleyebilirsiniz:

basic-bundle-template
  ├── databricks_template_schema.json
  └── template
      └── {{.project_name}}
          ├── databricks.yml.tmpl
          ├── resources
          │   └── {{.project_name}}_job.yml.tmpl
          └── src
              └── simple_notebook.ipynb

İpucu

Bu paket şablonundaki proje klasörü adı ve iş tanımı dosyasının adı bir şablon değişkeni kullanır. Şablon yardımcıları ve değişkenleri hakkında bilgi için bkz. Şablon yardımcıları ve değişkenleri.

Şablon şeması

Özel paket şablonu projesi, proje kökündebir databricks_template_schema.json JSON dosyası içermelidir. Bu dosya, bundle init komutu çalıştırıldığında Databricks CLI tarafından kullanılan alanları (istem metni gibi) tanımlar.

Aşağıdaki temel databricks_template_schema.json dosyası, paket projesi için istem iletisini ve varsayılan değeri içeren bir giriş değişkeni project_name tanımlar. Ardından, iletinin içindeki giriş değişkeni değerini kullanan paket projesi başlatma için bir başarı iletisi tanımlar.

{
  "properties": {
    "project_name": {
      "type": "string",
      "default": "basic_bundle",
      "description": "What is the name of the bundle you want to create?",
      "order": 1
    }
  },
  "success_message": "\nYour bundle '{{.project_name}}' has been created."
}

Şablon şeması alanları

databricks_template_schema.json dosyası, properties alanı içinde kullanıcınızdan paket başlatma sırasında bilgi toplamak için giriş değişkenleri tanımlamayı ve başlatmayı özelleştirmek için ek alanları destekler.

Giriş değişkenleri, şablon şemasının properties alanında tanımlanır. Her giriş değişkeni, paket başlatma sırasında kullanıcıya istem sunmak için gereken meta verileri tanımlar. Değişkenin değerine daha sonra {{.project_name}}gibi şablon değişkeni söz dizimi kullanılarak erişilebilir.

Paket başlatma işlemini özelleştirmek için bazı alanların değerlerini de ayarlayabilirsiniz.

Desteklenen şema alanları aşağıdaki tabloda listelenmiştir.

Şema alanı	Açıklama
properties	Paket şablonu giriş değişkeni tanımları. Databricks, paket projesinin adı olan en az bir giriş değişkeni tanımlamanızı önerir.
properties.<variable_name>	Giriş değişkeninin adı.
properties.<variable_name>.default	Kullanıcının --config-file komutunun bir parçası olarak veya kendisine sorulduğunda komut satırında bundle init ile bir değer sağlamadığı durumda kullanılacak varsayılan bir değerdir.
properties.<variable_name>.description	Giriş değişkeniyle ilişkili kullanıcı istemi iletisi.
properties.<variable_name>.enum	özelliği için "enum": ["azure", "aws", "gcp"]gibi olası değerlerin listesi. Bu alan tanımlanmışsa Databricks CLI, kullanıcıdan bir değer seçmesini istemesi için komut satırındaki bir listede yer alan değerleri sunar.
properties.<variable_name>.order	Giriş özellikleri için göreli sırayı tanımlayan bir tamsayı. Bu, komut satırında bu giriş değişkenleri için istemlerin gösterilme sırasını denetler.
properties.<variable_name>.pattern	Kullanıcı girişini doğrulamak için kullanılacak regexp deseni, örneğin "pattern": "^[^ .\\\\/]{3,}$". Desteklenen regexp söz dizimi için bkz. https://github.com/google/re2/wiki/Syntax.
properties.<variable_name>.pattern_match_failure_message	Kullanıcı tarafından girilen değer belirtilen desenle eşleşmiyorsa kullanıcıya görüntülenen ileti, örneğin Project name must be at least 3 characters long and cannot contain the following characters: \"\\\", \"/\", \" \" and \".\".".
properties.<variable_name>.skip_prompt_if	Bu şema zaten var olan yapılandırmadan memnunsa giriş değişkenini sormayı atlayın. Bu durumda bunun yerine özelliğin varsayılan değeri kullanılır. Örneğin, mlops-stacks şablonuna bakın. Yalnızca const karşılaştırmaları desteklenir.
properties.<variable_name>.skip_prompt_if.properties.<previous_variable_name>.const	<previous_variable_name> değeri skip_prompt_ifiçinde yapılandırılan sabitle eşleşiyorsa, <variable_name> istemi atlanır.
template_dir	Şablon dizininin yolu, örneğin ../default. Bu, birden çok databricks_template_schema.json dosyaya aynı dizine başvurma izni vererek genel şablonları etkinleştirir.
welcome_message	Kullanıcıdan giriş istemeden önce gösterilecek ilk ileti.
success_message	Şablon başarıyla başlatıldıktan sonra yazdırılacak ileti.
min_databricks_cli_version	Bu Databricks CLI'nin şablonun ihtiyaç duyduğu en düşük semver versiyonu. CLI sürümü bu sürümden küçükse databricks bundle init başarısız olur.
version	Gelecekte kullanmak üzere ayrılmıştır. Şemanın sürümü. Bu, şemanın geçerli CLI sürümüyle uyumlu olup olmadığını belirlemek için kullanılır.

Yapılandırma şablonları

Özel paket şablonu, paket projesi databricks.yml.tmpl yapılandırma dosyasını oluşturmak için kullanılan paket şablonu projesindeki bir template klasöründe databricks.yml dosyası içermelidir. Kaynaklar için yapılandırma dosyaları için şablonlar resources klasöründe oluşturulabilir. Bu şablon dosyalarını yapılandırma şablonu YAML ile doldurun.

databricks.yml ve ilişkili *_job.yml için aşağıdaki basit örnek yapılandırma şablonları paket adını ve iki hedef ortamı oluşturur ve bu şablon kullanılarak oluşturulan paketler için pakette not defterini çalıştıran bir iş tanımlar. Bu yapılandırma şablonları, paket değişiklikleri ve paket şablonu yardımcıları'den yararlanıyor.

template/{{.project_name}}/databricks.yml.tmpl:

# databricks.yml
# This is the configuration for the bundle {{.project_name}}.

bundle:
  name: {{.project_name}}

include:
  - resources/*.yml

targets:
  # The deployment targets. See https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html
  dev:
    mode: development
    default: true
    workspace:
      host: {{workspace_host}}

  prod:
    mode: production
    workspace:
      host: {{workspace_host}}
      # Deploy to a folder whose write access is restricted to the deploying
      # identity. Avoid /Shared, which is writable by all workspace users.
      root_path: /Workspace/Production/.bundle/${bundle.name}
    {{- if not is_service_principal}}
    run_as:
      # This runs as {{user_name}} in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: {{user_name}}
    {{end -}}

template/{{.project_name}}/resources/{{.project_name}}_job.yml.tmpl:

# {{.project_name}}_job.yml
# The main job for {{.project_name}}

resources:
    jobs:
        {{.project_name}}_job:
        name: {{.project_name}}_job
        tasks:
            - task_key: notebook_task
            job_cluster_key: job_cluster
            notebook_task:
                notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
            new_cluster:
                node_type_id: i3.xlarge
                spark_version: 13.3.x-scala2.12

Şablonu yardımcıları ve değişkenleri

Şablon yardımcıları, Databricks tarafından sağlanan ve çalışma zamanında kullanıcıya özgü bilgileri almak veya şablon altyapısıyla etkileşime geçmek için şablon dosyalarınızda kullanabileceğiniz işlevlerdir. Kendi şablon değişkenlerinizi de tanımlayabilirsiniz.

Aşağıdaki şablon yardımcıları Databricks paket şablonu projelerinde kullanılabilir. Go şablonlarını ve değişkenlerini kullanma hakkında bilgi için bkz. Go şablonları.

Yardımcı	Açıklama
{{url}}	https://pkg.go.dev/net/url#Parseiçin bir diğer ad. Bu, url.URLtüm yöntemlerinin kullanımına izin verir.
{{regexp}}	https://pkg.go.dev/regexp#Compileiçin bir diğer ad. Bu, regexp.Regexptüm yöntemlerinin kullanımına izin verir.
{{random_int}}	(0,n) yarı açık aralığında negatif olmayan bir int tipinde sözde-rastgele sayıyı döndürür.
{{uuid}}	RFC 4122'de tanımlandığı gibi 128 bit (16 bayt) Evrensel Benzersiz Kimlik Belirleyicisi olan bir UUID dize olarak döndürür. Bu kimlik, şablon yürütme süresi boyunca kararlıdır ve şablon yazarları tarafından databricks.yml bundle.uuid alanını doldurmak için kullanılabilir.
{{bundle_uuid}}	Paket için benzersiz bir kimlik. Bu işlevin birden çok çağrısı aynı UUID değerini döndürür.
{{pair}}	Anahtar değer çifti. Bu, bir şablonun içinde kullanılacak haritalar oluşturmak için map yardımcısıyla birlikte kullanılır.
{{map}}	Çiftlerin listesini harita nesnesine dönüştürür. Bu, kitaplık dizininde tanımlanan şablonlara birden çok nesne geçirmek için yararlıdır. Bir şablonu çağırmak için Go metin şablonu söz dizimi yalnızca tek bir bağımsız değişken belirtmeye izin verdiğinden, bu işlev bu sınırlamaya geçici bir çözüm olarak kullanılabilir. Örneğin, aşağıdaki satırda {{template "my_template" (map (pair "foo" $arg1) (pair "bar" $arg2))}}, $arg1 ve $arg2my_template içinden .foo ve .barolarak ifade edilebilir.
{{smallest_node_type}}	En küçük düğüm türünü döndürür.
{{path_separator}}	İşletim sistemi için yol ayırıcı karakter. Bu, Unix tabanlı sistemler için / ve Windows için \'dir.
{{workspace_host}}	Kullanıcının şu anda kimliğinin doğrulandığı çalışma alanının ana bilgisayar URL'si.
{{user_name}}	Şablonu başlatan kullanıcının tam adı.
{{short_name}}	Şablonu başlatan kullanıcının kısa adı.
{{default_catalog}}	Varsayılan çalışma alanı kataloğunu döndürür. Varsayılan değer yoksa veya Unity Kataloğu etkin değilse, bu boş bir dize döndürür.
{{is_service_principal}}	Geçerli kullanıcının bir hizmet temsilcisi olup olmadığı.
{{ skip <glob-pattern-relative-to-current-directory> }}	Şablon altyapısının giriş glob deseni ile eşleşen tüm dosyaları ve dizinleri oluşturma işlemini atlamasına neden olur. Örneğin, mlops-stacks şablonuna bakın.

Özel şablon yardımcıları

Kendi şablon yardımcılarınızı tanımlamak için, şablon projesinin library klasöründe bir şablon dosyası oluşturun ve yardımcıları tanımlamak için Go şablon söz dizimini kullanın. Örneğin, bir library/variables.tmpl dosyasının aşağıdaki içeriği cli_version ve model_namedeğişkenlerini tanımlar. Bu şablon bir paketi başlatmak için kullanıldığında, model_name değişkeninin değeri şablon şema dosyasında tanımlanan input_project_name alanı kullanılarak oluşturulur. Bu alan değerinin değeri, bir istemden sonra kullanıcı girişidir.

{{ define `cli_version` -}}
    v0.240.0
{{- end }}

{{ define `model_name` -}}
    {{ .input_project_name }}-model
{{- end }}

Tam bir örneği görmek için mlops-stacks şablon değişkenleri dosyasına bakın.

Paket şablonunu test edin

Son olarak, şablonunuzu test etmeye özen gösterin. Örneğin, önceki bölümlerde tanımlanan şablonu kullanarak yeni bir paket başlatmak için Databricks CLI kullanın:

databricks bundle init basic-bundle-template

Komut istemi için What is your bundle project name? değerini girin, my_test_bundle yazın.

Test paketi oluşturulduktan sonra şema dosyasından gelen başarı iletisi çıkar. Klasörün içeriğini my_test_bundle incelerseniz aşağıdakileri görmeniz gerekir:

my_test_bundle
   ├── databricks.yml
   ├── resources
   │  └── my_test_bundle_job.yml
   └── src
      └── simple_notebook.ipynb

databricks.yml dosyası ve işi artık özelleştirilmiştir:

# databricks.yml
# This is the configuration for the bundle my-test-bundle.

bundle:
  name: my_test_bundle

include:
  - resources/*.yml

targets:
  # The 'dev' target, used for development purposes. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#development-mode)
  dev:
    mode: development
    default: true
    workspace:
      host: https://my-host.cloud.databricks.com

  # The 'prod' target, used for production deployment. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#production-mode)
  prod:
    mode: production
    workspace:
      host: https://my-host.cloud.databricks.com
      # Deploy to a folder whose write access is restricted to the deploying
      # identity. Avoid /Shared, which is writable by all workspace users.
      root_path: /Workspace/Production/.bundle/${bundle.name}
    run_as:
      # This runs as someone@example.com in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: someone@example.com

# my_test_bundle_job.yml
# The main job for my_test_bundle

resources:
    jobs:
        my_test_bundle_job:
        name: my_test_bundle_job
        tasks:
            - task_key: notebook_task
                job_cluster_key: job_cluster
                notebook_task:
                    notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
                new_cluster:
                    node_type_id: i3.xlarge
                    spark_version: 13.3.x-scala2.12

Özel şablon paylaşma

Paket şablonunu diğer kullanıcılarla paylaşmak istiyorsanız, bu şablonu Git'in desteklediği ve kullanıcılarınızın erişimi olan herhangi bir sağlayıcıyla sürüm denetiminde depolayabilirsiniz. Komutu bir Git URL'si bundle init ile çalıştırmak için, dosyanın bu databricks_template_schema.json Git URL'sine göre kök konumda olduğundan emin olun.

İpucu

Dosyayı, paketin databricks_template_schema.json köküne göre farklı bir klasöre yerleştirebilirsiniz. Ardından komutun bundle init--template-dir seçeneğini kullanarak dosyayı içeren databricks_template_schema.json klasöre başvurabilirsiniz.

Çalışma alanında özel şablon klasörü yapılandırma

Important

Bu özellik Beta sürümündedir.

Özel paket şablonları, çalışma alanında paket oluşturmak için kullanılabilir hale getirilebilir.

1. Paket şablonunuzu bir GitHub deposunda depolayın ve bağlanacak bir Git klasörü yapılandırın. Git klasörü yapılandırma hakkında bilgi için bkz. Depo kopyalama.

2. Hesap veya çalışma alanı yöneticisi olarak çalışma alanında Ayarlar'a gidin. bkz. çalışma alanınızı yönetme.

3. Geliştirme'ye tıklayın.

4. Bildirim temelli Otomasyon Paketleri'nin altında özel şablonlar için bir klasör seçin. Tüm özel paket şablonları klasörün kök düzeyinde kullanılabilir olmalıdır. Örneğin:

   folder-for-custom-templates/
   ├── example-custom-template
   ├── custom-template-2
   ├── custom-template-3
   ├── ...
   

   

5. İzinler iletişim kutusu görüntülendiğinde, bütün kullanıcılara özel şablonlar klasörüne görüntüleme izni verin veya daha ayrıntılı izinler belirlemek için Erişim vermemeyi seçin.

   1. Daha ayrıntılı izinler ayarlamak için herhangi bir klasördeki üç noktayı seçin ve Ayrıntıları görüntüle'ye tıklayın.

      

   2. Git klasörü ayrıntıları panelinde Paylaş'a tıklayın.

   3. Şablonları kimlerin düzenleyebileceğini (YÖNETebilir) ve şablonları kullanarak kimlerin paket oluşturabileceğini seçin (GÖRÜNTÜLEYEBILIR).

   İzinler hakkında daha fazla bilgi için bkz . Klasör ACL'leri ve Git klasörü ACL'leri.

Bu klasördeki şablonlar artık kullanıcılar çalışma alanında paket oluştururken kullanılabilir. Bkz. Paket oluşturma.

Sonraki adımlar

• Databricks tarafından oluşturulan ve bakımı yapılan ek şablonlara göz atın. GitHub'daki paket örnekleri deposuna bakın.
• MLOps Yığınlarını Bildirim temelli Otomasyon Paketleri şablonlarıyla kullanmak için bkz. MLOps Yığınları için Bildirim temelli Otomasyon Paketleri.
• Go paketi şablon oluşturma hakkında daha fazla bilgi edinin. Go paket şablonu belgelerine bakın.