Aracılığıyla paylaş

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

  • Makale

Artık Azure Databricks görevleriile birden çok işi düzenleyebilirsiniz. Bu makalede, birden çok görevi olan işleri destekleyen İşleri API'sindeki değişiklikler ayrıntılı olarak anlatılmıştır ve mevcut API istemcilerinizi bu yeni özellikle çalışacak şekilde güncelleştirmenize yardımcı olacak yönergeler vardı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çok görevli biçim olarak birden çok görevle tanımlanan işleri ifade eder.

Jobs API 2.0 ve 2.1 artık güncelleştirme isteğini destekler. Tek görev biçimli işler ile çok görevli biçim işleri arasındaki değişiklikleri en aza indirmek için update isteği yerine var olan bir işi değiştirmek için isteğini kullanın.

API değişiklikleri

İşler API'si artık bir işteki her görevin ayarlarını yakalamak için bir TaskSettings nesnesi tanımlıyor. Çok görevli biçim işleri için, bir dizi tasks veri yapısından oluşan TaskSettings alanı JobSettings nesnesine dahil edilir. Daha önce JobSettings 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, format alanını içerecek şekilde de güncelleştirilir. format alanı işin biçimini gösterir ve STRING veya SINGLE_TASKolarak ayarlanmış bir MULTI_TASK değeridir.

Ç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 bu biçime uygun olmalıdır ve yanıtlar bu biçimde yapılandırılmıştır.

İş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:

  • Bir görev başladığında, bir görev düzeyi kümesi oluşturulur ve başlatılır; görev tamamlandığında ise sonlandırı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 JobCluster nesnesine bir JobSettings dizisi 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, task alan ayarlarında kitaplıkları 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örevinin yapılandırmasındaki ingest_orders alanı 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, JobSettings alanının eklenmesi dışında format veri yapısı değişmeden kalır. hiçbir TaskSettings dizisi dahil değildir ve görev ayarları JobSettings veri yapısının en üst düzeyinde 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 müşteri 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:

Oluştur

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

Birden çok görev biçimli bir iş oluşturmak için tasks'daki JobSettings alanını kullanarak 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
    }
  ]
}

Çalıştırmaları gönderme

Tek seferlik bir görev biçimi işi göndermek için İşler API'sinde Oluşturma ve tetikleme işlemini (POST /runs/submit) kullanarak var olan istemcileri değiştirmeniz gerekmez.

Çok görevli biçim işinin tek seferlik bir çalıştırmasını göndermek için, kümeler de dahil olmak üzere her görevin ayarlarını belirtmek üzere tasks'daki JobSettings alanını kullanın. runs submit isteği paylaşılan iş kümelerini desteklemediğinden, çok görev biçimli bir iş gönderirken kümelerin görev düzeyinde ayarlanması gerekir. Birden çok görev belirtmeye örnek için bkz. JobSettings.

Güncelleştirmesi

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

Çok görevli biçim işinin ayarlarını güncellemek için, benzersiz task_key alanını kullanarak yeni task ayarlarını tanımlamanız gerekir. Birden çok görev belirtmeye örnek için bkz. JobSettings.

sıfırla

Job API'sinde, bir iş için tüm ayarları üzerine yazma işlemi (POST /jobs/reset) yaparak tek görev biçimli bir işin ayarlarının üzerine yazmak istiyorsanız, mevcut istemcilerde değişiklik yapmanıza gerek yoktur.

Çoklu görev format işinin ayarlarının üzerine yazmak için, JobSettings veri yapısını, TaskSettings veri yapılarından oluşan bir diziyle belirtin. Birden çok görev belirtmeye örnek için bkz. JobSettings.

Update kullanarak tek tek görev biçiminden çok görevli biçime geçmeden tek tek alanları değiştirin.

Listesi

Tek görev biçimli işler için, İşler API'sindeki Tüm işleri listele işlemi (GET /jobs/list) yanıtını 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. istemcileri, Job yapısında döndürülen çok görev biçimli bir işin küme veya görev ayarlarına erişebilmesi için değiştirmek üzere:

  • job_id alanını çoklu görev formatlı iş için ayrıştırın.
  • İş ayrıntılarını almak için İşler API'sinden Job alma işlemi için 'i 'a iletin (). Çok görevli biçim işi için API çağrısından örnek bir yanıtı görmek için bkz. Get alma.

Aşağıdaki örnekte tek görevli biçimdeki ve çok görevli biçimdeki işler 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"
    }
  ]
}

İndir

Tek görev formatlı işler için, İşler API'sindeki İş Al işlemi () yanıtını işlemek için istemci değişikliği gerekmez.

Çoklu görev formatı işleri, görev ayarlarını içeren task veri yapıları dizisi döndürür. Görev düzeyi ayrıntılarına erişmeniz gerekiyorsa, istemcilerinizi tasks dizisinde dolaşacak şekilde değiştirip, gerekli alanları çıkarmanız gerekir.

Aşağıda, çok görevli biçim işi için Get API çağrısından ö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ı al

Tek görev biçimli işler için İşler API'sindeki İş çalıştır işlemi () yanıt işlemek için istemci değişikliği gerekmez.

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

  • Görevlerin her birinde yineleme yapın.
  • Her bir görevi için run_id'ı ayrıştırın.
  • işleminin (GET /jobs/runs/get-output) çıktısını alın. Bu istekten örnek bir yanıt aşağıda verilmiştir:
{
  "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ı çıkış alır

Tek görev formatlı işler için, İşler API'sindeki ) çıkışını almak için istemci değişikliği gerekmez.

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

  • Çağırın , çalıştırma isteğinin çıktısını alın.
  • Yanıttaki alt run_id alanları üzerinde yineleme yapın.
  • run_idçağırmak için alt Runs get output değerlerini kullanın.

Koşular listesi

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

Çoklu görev format işlevleri için boş bir tasks dizisi döndürülür. Görevleri almak için run_id'ı 'e geçirerek işi al çalıştırma işlemini (GET /jobs/runs/get) başlatın. Aşağıda, çok görevli biçim işi için Runs list API çağrısından ö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
}