Aracılığıyla paylaş

İşler API 2.0'dan 2.1'e güncelleştirme

  • Makale

Artık Azure Databricks işleri ile birden çok görevi düzenleyebilirsiniz. Bu makalede, birden çok görevi olan işleri destekleyen İşler API'sinde yapılan değişiklikler ayrıntılı olarak anlatılarak mevcut API istemcilerinizi bu yeni özellikle çalışacak şekilde güncelleştirmenize yardımcı olacak yönergeler sağlanır.

Databricks, özellikle birden çok görevi olan işleri kullanırken API betikleriniz ve istemcileriniz için İşler API 2.1'i önerir.

Bu makale, tek bir görevle tek görev biçimi olarak tanımlanan işleri ve birden çok görevle birden çok görev biçimi olarak tanımlanan işleri ifade eder.

İşler API'si 2.0 ve 2.1 artık güncelleştirme isteğini destekliyor. Tek görev biçimli update işler ile çok görevli biçim işleri arasındaki değişiklikleri en aza indirmek için sıfırlama isteği yerine mevcut işi değiştirmek için isteği kullanın.

API değişiklikleri

İşler API'sinde artık bir TaskSettings işteki her görevin ayarlarını yakalamak için bir nesne tanımlıyor. Çok görevli biçim işleri için, nesneye tasks bir veri yapıları dizisi TaskSettings olan alan eklenir JobSettings . Daha önce öğesinin JobSettings bir parçası olan bazı alanlar artık çok görevli biçim işleri için görev ayarlarının bir parçasıdır. JobSettings alanı içerecek format şekilde de güncelleştirilir. alanı format işin biçimini gösterir ve veya MULTI_TASKolarak ayarlanmış SINGLE_TASK bir STRING değerdir.

Çok görevli biçim işleri için JobSettings'de yapılan bu değişiklikler için mevcut API istemcilerinizi güncelleştirmeniz gerekir. Gerekli değişiklikler hakkında daha fazla bilgi için API istemci kılavuzuna bakın.

İşler API'si 2.1, çok görevli biçimi destekler. Tüm API 2.1 istekleri çok görevli biçime uygun olmalıdır ve yanıtlar çok görevli biçimde yapılandırılır. İlk olarak API 2.1 için yeni özellikler kullanıma sunulur.

İşler API'si 2.0, çok görevli biçim işlerini desteklemek için ek bir alanla güncelleştirilir. Belirtildiği durumlar dışında, bu belgedeki örneklerde API 2.0 kullanılır. Ancak Databricks, yeni ve mevcut API betikleri ve istemcileri için API 2.1'i önerir.

API 2.0 ve 2.1 için çok görevli biçim işini temsil eden örnek bir JSON belgesi:

{
  "job_id": 53,
  "settings": {
    "name": "A job with multiple tasks",
    "email_notifications": {},
    "timeout_seconds": 0,
    "max_concurrent_runs": 1,
    "tasks": [
      {
        "task_key": "clean_data",
        "description": "Clean and prepare the data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/clean-data"
        },
        "existing_cluster_id": "1201-my-cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      },
      {
        "task_key": "analyze_data",
        "description": "Perform an analysis of the data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/analyze-data"
        },
        "depends_on": [
          {
            "task_key": "clean_data"
          }
        ],
        "existing_cluster_id": "1201-my-cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      }
    ],
    "format": "MULTI_TASK"
  },
  "created_time": 1625841911296,
  "creator_user_name": "user@databricks.com",
  "run_as_user_name": "user@databricks.com"
}

İşler API'si 2.1, görev düzeyi kümelerinin veya bir veya daha fazla paylaşılan iş kümesinin yapılandırmasını destekler:

  • Görev tamamlandığında görev başlatıldığında ve sonlandırıldığında bir görev düzeyi kümesi oluşturulur ve başlatılır.
  • Paylaşılan iş kümesi, aynı işteki birden çok görevin kümeyi kullanmasına izin verir. Kümeyi kullanan ilk görev başlatıldığında ve kümeyi kullanan son görev tamamlandıktan sonra sonlandırıldığında küme oluşturulur ve başlatılır. Paylaşılan iş kümesi boşta olduğunda sonlandırılmaz, ancak yalnızca kullanan tüm görevler tamamlandıktan sonra sonlandırılır. Bir kümeyi paylaşan birden çok bağımlı olmayan görev aynı anda başlayabilir. Paylaşılan bir iş kümesi başarısız olursa veya tüm görevler tamamlanmadan sonlandırılırsa yeni bir küme oluşturulur.

Paylaşılan iş kümelerini yapılandırmak için nesnesine JobSettings bir JobCluster dizi ekleyin. İş başına en fazla 100 küme belirtebilirsiniz. Aşağıda, iki paylaşılan kümeyle yapılandırılmış bir iş için API 2.1 yanıtı örneği verilmiştir:

Not

Bir görevin kitaplık bağımlılıkları varsa, kitaplıkları task alan ayarlarında yapılandırmanız gerekir; kitaplıklar paylaşılan bir iş kümesi yapılandırmasında yapılandırılamaz. Aşağıdaki örnekte, libraries görevin yapılandırmasındaki ingest_orders alan bir kitaplık bağımlılığının belirtimini gösterir.

{
  "job_id": 53,
  "settings": {
    "name": "A job with multiple tasks",
    "email_notifications": {},
    "timeout_seconds": 0,
    "max_concurrent_runs": 1,
    "job_clusters": [
      {
        "job_cluster_key": "default_cluster",
        "new_cluster": {
          "spark_version": "7.3.x-scala2.12",
          "node_type_id": "i3.xlarge",
          "spark_conf": {
            "spark.speculation": true
          },
          "aws_attributes": {
            "availability": "SPOT",
            "zone_id": "us-west-2a"
          },
          "autoscale": {
            "min_workers": 2,
            "max_workers": 8
          }
        }
      },
      {
        "job_cluster_key": "data_processing_cluster",
        "new_cluster": {
          "spark_version": "7.3.x-scala2.12",
          "node_type_id": "r4.2xlarge",
          "spark_conf": {
            "spark.speculation": true
          },
          "aws_attributes": {
            "availability": "SPOT",
            "zone_id": "us-west-2a"
          },
          "autoscale": {
            "min_workers": 8,
            "max_workers": 16
          }
        }
      }
    ],
    "tasks": [
      {
        "task_key": "ingest_orders",
        "description": "Ingest order data",
        "depends_on": [ ],
        "job_cluster_key": "auto_scaling_cluster",
        "spark_jar_task": {
          "main_class_name": "com.databricks.OrdersIngest",
          "parameters": [
            "--data",
            "dbfs:/path/to/order-data.json"
          ]
        },
        "libraries": [
          {
            "jar": "dbfs:/mnt/databricks/OrderIngest.jar"
          }
        ],
        "timeout_seconds": 86400,
        "max_retries": 3,
        "min_retry_interval_millis": 2000,
        "retry_on_timeout": false
      },
      {
        "task_key": "clean_orders",
        "description": "Clean and prepare the order data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/clean-data"
        },
        "job_cluster_key": "default_cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      },
      {
        "task_key": "analyze_orders",
        "description": "Perform an analysis of the order data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/analyze-data"
        },
        "depends_on": [
          {
            "task_key": "clean_data"
          }
        ],
        "job_cluster_key": "data_processing_cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      }
    ],
    "format": "MULTI_TASK"
  },
  "created_time": 1625841911296,
  "creator_user_name": "user@databricks.com",
  "run_as_user_name": "user@databricks.com"
}

Tek görev biçimli işler için veri yapısı, JobSettings alanın eklenmesi format dışında değişmeden kalır. Dizi TaskSettings dahil değildir ve görev ayarları veri yapısının en üst düzeyinde JobSettings tanımlanmış olarak kalır. Tek görev biçimli işleri işlemek için mevcut API istemcilerinizde değişiklik yapmanız gerekmez.

API 2.0 için tek görev biçimli işi temsil eden örnek bir JSON belgesi:

{
  "job_id": 27,
  "settings": {
    "name": "Example notebook",
    "existing_cluster_id": "1201-my-cluster",
    "libraries": [
      {
        "jar": "dbfs:/FileStore/jars/spark_examples.jar"
      }
    ],
    "email_notifications": {},
    "timeout_seconds": 0,
    "schedule": {
      "quartz_cron_expression": "0 0 0 * * ?",
      "timezone_id": "US/Pacific",
      "pause_status": "UNPAUSED"
    },
    "notebook_task": {
      "notebook_path": "/notebooks/example-notebook",
      "revision_timestamp": 0
    },
    "max_concurrent_runs": 1,
    "format": "SINGLE_TASK"
  },
  "created_time": 1504128821443,
  "creator_user_name": "user@databricks.com"
}

API istemci kılavuzu

Bu bölümde, yeni çok görevli biçim özelliğinden etkilenen API çağrıları için yönergeler, örnekler ve gerekli değişiklikler sağlanır.

Bu bölümde:

Yaratmak

İşler API'sindeki Yeni iş oluşturma işlemi (POST /jobs/create) aracılığıyla tek görev biçimli bir iş oluşturmak için mevcut istemcileri değiştirmeniz gerekmez.

Çok görevli biçimli bir iş oluşturmak için içindeki alanını JobSettings kullanarak tasks her görevin ayarlarını belirtin. Aşağıdaki örnek, iki not defteri görevi içeren bir iş oluşturur. Bu örnek API 2.0 ve 2.1 içindir:

Not

İş başına en fazla 100 görev belirtilebilir.

{
  "name": "Multi-task-job",
  "max_concurrent_runs": 1,
  "tasks": [
    {
      "task_key": "clean_data",
      "description": "Clean and prepare the data",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/clean-data"
      },
      "existing_cluster_id": "1201-my-cluster",
      "timeout_seconds": 3600,
      "max_retries": 3,
      "retry_on_timeout": true
    },
    {
      "task_key": "analyze_data",
      "description": "Perform an analysis of the data",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/analyze-data"
      },
      "depends_on": [
        {
          "task_key": "clean_data"
        }
      ],
      "existing_cluster_id": "1201-my-cluster",
      "timeout_seconds": 3600,
      "max_retries": 3,
      "retry_on_timeout": true
    }
  ]
}

Gönderme çalıştırmaları

İşler API'sinde Bir kerelik çalıştırma işlemiPOST /runs/submit () oluşturma ve tetikleme ile tek seferlik bir görev biçimi işi göndermek için, var olan istemcileri değiştirmeniz gerekmez.

Çok görevli biçimli bir işin tek seferlik çalışmasını göndermek için içindeki alanını JobSettings kullanarak tasks kümeler de dahil olmak üzere her görevin ayarlarını belirtin. İstek paylaşılan iş kümelerini desteklemediğinden runs submit , çok görev biçimli bir iş gönderilirken kümeler görev düzeyinde ayarlanmalıdır. Birden çok görev belirtme örneği JobSettings için bkz. Oluşturma.

Güncelleştirmek

İşler API'sindeki bir işi kısmen güncelleştirme işlemiyle (POST /jobs/update) tek görev biçimli bir işi güncelleştirmek için mevcut istemcileri değiştirmeniz gerekmez.

Çok görevli biçim işinin ayarlarını güncelleştirmek için, yeni task ayarları tanımlamak için benzersiz task_key alanı kullanmanız gerekir. Birden çok görev belirtme örneği JobSettings için bkz. Oluşturma.

Sıfırlama

İşler API'sindeki bir iş işleminin (POST /jobs/reset) tüm ayarlarının üzerine yaz ile tek görev biçimli bir işin ayarlarının üzerine yazmak için var olan istemcileri değiştirmeniz gerekmez.

Çok görevli biçim işinin ayarlarının üzerine yazmak için bir veri yapısı dizisiyle TaskSettings bir veri yapısı belirtinJobSettings. Birden çok görev belirtme örneği JobSettings için bkz. Oluşturma.

Tek görevden çok görevli biçime geçmeden tek tek alanları değiştirmek için Güncelleştir'i kullanın.

Liste

Tek görev biçimli işler için, İşler API'sindeki Tüm işleri listele işleminden (GET /jobs/list) gelen yanıtı işlemek için istemci değişikliği gerekmez.

Çok görevli biçim işleri için çoğu ayar iş düzeyinde değil görev düzeyinde tanımlanır. Küme yapılandırması görev veya iş düzeyinde ayarlanabilir. İstemcileri, yapıda döndürülen çok görev biçimli bir işin küme veya görev ayarlarına erişecek Job şekilde değiştirmek için:

  • Çok görevli biçim işi için alanı ayrıştırın job_id .
  • job_id İş ayrıntılarını almak için öğesini İşler API'sindeki İş alma işlemine (GET /jobs/get) geçirin. Çok görevli biçim işi için API çağrısından Get örnek yanıt için bkz. Alma.

Aşağıdaki örnekte tek görevli ve çok görevli biçim işleri içeren bir yanıt gösterilmektedir. Bu örnek API 2.0 içindir:

{
  "jobs": [
    {
      "job_id": 36,
      "settings": {
        "name": "A job with a single task",
        "existing_cluster_id": "1201-my-cluster",
        "email_notifications": {},
        "timeout_seconds": 0,
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/example-notebook",
          "revision_timestamp": 0
        },
        "max_concurrent_runs": 1,
        "format": "SINGLE_TASK"
      },
      "created_time": 1505427148390,
      "creator_user_name": "user@databricks.com"
    },
    {
      "job_id": 53,
      "settings": {
        "name": "A job with multiple tasks",
        "email_notifications": {},
        "timeout_seconds": 0,
        "max_concurrent_runs": 1,
        "format": "MULTI_TASK"
      },
      "created_time": 1625841911296,
      "creator_user_name": "user@databricks.com"
    }
  ]
}

Al

Tek görev biçimli işler için, İşler API'sindeki İş al işleminden (GET /jobs/get) gelen yanıtı işlemek için istemci değişikliği gerekmez.

Çok görevli biçim işleri, görev ayarlarını içeren bir veri yapıları dizisi task döndürür. Görev düzeyi ayrıntılarına erişmeniz gerekiyorsa, dizide tasks yineleme yapmak ve gerekli alanları ayıklamak için istemcilerinizi değiştirmeniz gerekir.

Aşağıda, çok görevli biçim işi için API çağrısından Get alınan örnek bir yanıt gösterilmektedir. Bu örnek API 2.0 ve 2.1 içindir:

{
  "job_id": 53,
  "settings": {
    "name": "A job with multiple tasks",
    "email_notifications": {},
    "timeout_seconds": 0,
    "max_concurrent_runs": 1,
    "tasks": [
      {
        "task_key": "clean_data",
        "description": "Clean and prepare the data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/clean-data"
        },
        "existing_cluster_id": "1201-my-cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      },
      {
        "task_key": "analyze_data",
        "description": "Perform an analysis of the data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/analyze-data"
        },
        "depends_on": [
          {
            "task_key": "clean_data"
          }
        ],
        "existing_cluster_id": "1201-my-cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      }
    ],
    "format": "MULTI_TASK"
  },
  "created_time": 1625841911296,
  "creator_user_name": "user@databricks.com",
  "run_as_user_name": "user@databricks.com"
}

Çalıştırmalar get

Tek görev biçimli işler için, İşler API'sindeki İş çalıştırması alma işleminden (GET /jobs/runs/get) gelen yanıtı işlemek için istemci değişikliği gerekmez.

Çok görevli biçimli bir iş çalıştırmasının yanıtı bir dizi TaskSettingsiçerir. Her görevin çalıştırma sonuçlarını almak için:

{
  "job_id": 53,
  "run_id": 759600,
  "number_in_job": 7,
  "original_attempt_run_id": 759600,
  "state": {
    "life_cycle_state": "TERMINATED",
    "result_state": "SUCCESS",
    "state_message": ""
  },
  "cluster_spec": {},
  "start_time": 1595943854860,
  "setup_duration": 0,
  "execution_duration": 0,
  "cleanup_duration": 0,
  "trigger": "ONE_TIME",
  "creator_user_name": "user@databricks.com",
  "run_name": "Query logs",
  "run_type": "JOB_RUN",
  "tasks": [
    {
      "run_id": 759601,
      "task_key": "query-logs",
      "description": "Query session logs",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/log-query"
      },
      "existing_cluster_id": "1201-my-cluster",
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    },
    {
      "run_id": 759602,
      "task_key": "validate_output",
      "description": "Validate query output",
      "depends_on": [
        {
          "task_key": "query-logs"
        }
      ],
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/validate-query-results"
      },
      "existing_cluster_id": "1201-my-cluster",
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    }
  ],
  "format": "MULTI_TASK"
}

Çalıştırmalar çıktıyı alır

Tek görev biçimli işler için İşler API'sindeki Çalıştırma işleminin (GET /jobs/runs/get-output) çıktısını alma bölümünden gelen yanıtı işlemek için istemci değişikliği gerekmez.

Çok görevli biçim işleri için, bir üst çalıştırmada çağrılması Runs get output , çalıştırma çıkışı yalnızca tek tek görevler için kullanılabilir olduğundan hatayla sonuçlanır. Çok görevli biçim işinin çıktısını ve meta verilerini almak için:

  • Çalıştırma isteğinin çıkışını al'ı çağırın.
  • Yanıttaki alt run_id alanlar üzerinde yineleme yapın.
  • çağırmak Runs get outputiçin alt run_id değerleri kullanın.

Çalıştırmalar listesi

Tek görev biçimli işler için, bir iş işlemi (GET /jobs/runs/list) için Liste çalıştırmalarından gelen yanıtı işlemek için istemci değişikliği gerekmez.

Çok görevli biçim işleri için boş tasks bir dizi döndürülür. run_id Görevleri almak için öğesini İş çalıştırması alma işlemine (GET /jobs/runs/get) geçirin. Aşağıda, çok görevli biçim işi için API çağrısından Runs list örnek bir yanıt gösterilmektedir:

{
  "runs": [
    {
      "job_id": 53,
      "run_id": 759600,
      "number_in_job": 7,
      "original_attempt_run_id": 759600,
      "state": {
          "life_cycle_state": "TERMINATED",
          "result_state": "SUCCESS",
          "state_message": ""
      },
      "cluster_spec": {},
      "start_time": 1595943854860,
      "setup_duration": 0,
      "execution_duration": 0,
      "cleanup_duration": 0,
      "trigger": "ONE_TIME",
      "creator_user_name": "user@databricks.com",
      "run_name": "Query logs",
      "run_type": "JOB_RUN",
      "tasks": [],
      "format": "MULTI_TASK"
    }
  ],
  "has_more": false
}