Aracılığıyla paylaş

Jobs API 2.1'den 2.2'ye güncelleme

  • Makale

Bu makalede, İşler API'sinin 2.2 sürümündeki işlevlere yönelik güncelleştirmeler ve geliştirmeler ayrıntılı olarak verilmiştir. Mevcut API istemcilerinizi bu yeni sürümle çalışacak şekilde güncelleştirmenize yardımcı olacak bilgiler içerir. Bu güncellemeler, işlerin varsayılan kuyruğa alınması ve yanıtlar 100'den fazla öğe içeren alanlar içerdiğinde için daha iyi sayfalandırma desteği içerir. Sürüm 2.2 büyük sonuç kümelerini sayfalandırmak için mevcut desteği iyileştirdiğinden Databricks, özellikle yanıtlar birçok görev içerebileceğinden API betikleriniz ve istemcileriniz için bu desteğin kullanılmasını önerir.

API'nin 2.0 ve 2.1 sürümleri arasındaki değişiklikler hakkında bilgi edinmek için bkz. jobs API 2.0'dan 2.1'e güncelleştirme.

Databricks jobs API'sinin 2.1 sürümündeki değişikliklere ek olarak, sürüm 2.2'de aşağıdaki geliştirmeler bulunur:

İşler varsayılan olarak kuyruğa alınır

İstek üzerine etkinleştirilen iş kuyruğu özelliği, kaynaklar bir işlem için mevcut olmadığında işlerin harekete geçirilmesinin atlanmasını engeller. İş kuyruğu oluşturma, İşler API'sinin 2.0, 2.1 ve 2.2 sürümlerinde desteklenir ve kuyruk oluşturmanın varsayılan işlemesinde aşağıdaki farklar bulunur:

  • İşler API'si 2.2 ile oluşturulan işler için kuyruk oluşturma varsayılan olarak etkinleştirilir. bir iş oluşturduğunuzda veya güncelleştirdiğinizde queue alanını istek gövdelerinde false olarak ayarlayarak kuyruk oluşturmayı kapatabilirsiniz.
  • İşler API'sinin 2.0 ve 2.1 sürümleriyle oluşturulan işler için, kuyruğa alma varsayılan olarak etkinleştirilmez. Bu sürümlerle, bir iş oluşturduğunuzda veya güncelleştirdiğinizde queue alanını istek gövdelerinde true olarak ayarlayarak kuyruk oluşturmayı etkinleştirmeniz gerekir.

bir iş oluşturduğunuzda kuyruk oluşturmayı etkinleştirebilir veya devre dışı bırakabilirsiniz bir işi kısmen güncelleştirebilir veya tüm iş ayarlarını güncelleştirebilirsiniz.

bkz. İş kuyruğa alma.

Uzun görev ve görev çalıştırma listelerini sayfalama desteği

İşler API'si 2.2, çok sayıda görev veya görev çalıştırmasına sahip işleri desteklemek için aşağıdaki istekler için büyük sonuç kümelerinin döndürülme biçimini değiştirir:

İşler API'si 2.2, bu istekler için sayfalandırmayı aşağıdaki gibi değiştirir:

  • Görevler, parametreler, job_clusters veya ortamlar gibi öğe listelerini temsil eden alanlar yanıt başına 100 öğeyle sınırlıdır. 100'den fazla değer varsa, yanıt gövdesi bir sonraki sonuç sayfasını almak için belirteç içeren bir next_page_token alanı içerir.
  • Get a single job ve Get a single job run isteklerine verilen yanıtlar için sayfalandırma eklenir. List job ve List job runs isteğine verilen yanıtlar için sayfalandırma, İşler API 2.1 ile eklendi.

Aşağıda, 100'den fazla görev içeren bir iş için Get a single job isteğinden örnek bir yanıt gövdesi verilmiştir. Belirteç tabanlı sayfalama işlevini göstermek için, bu örnek yanıt gövdesine dahil edilen alanların çoğunu atlar:

{
  "job_id": 11223344,
  "settings": {
    "tasks": [
      {
        "task_key": "task-1"
      },
      {
        "task_key": "task-2"
      },
      {
        "task_key": "task-..."
      },
      {
        "task_key": "task-100"
      }
    ]
  },
  "next_page_token": "Z29...E="
}

Sonraki sonuç kümesini almak için, sonraki istekteki page_token sorgu parametresini next_page_token alanında döndürülen değere ayarlayın. Örneğin, /api/2.2/jobs/get?job_id=11223344&page_token=Z29...E=.

Başka sonuç yoksa, next_page_token alanı yanıta dahil değildir.

Aşağıdaki bölümlerde, list ve get isteklerinin her birine yönelik güncelleştirmeler hakkında daha fazla ayrıntı sağlanır.

'taki değişiklikler List jobs ve List job runs isteklerinde

Listesi işleri ve Listesi işi istekleri çalıştırırsa, yanıt nesnesinin kök düzeyindeki has_more parametresi kaldırılır. Bunun yerine, daha fazla sonuç olup olmadığını belirlemek için next_page_token varlığını kullanın. Aksi takdirde, sonuçları sayfalandırma işlevi değişmeden kalır.

Büyük yanıt gövdelerini önlemek için, her bir işlemin en üst düzey tasks ve job_clusters dizileri varsayılan olarak yanıtlardan hariç bırakılır. Bu isteklerin yanıt gövdesine dahil edilen her iş için bu dizileri eklemek için isteğe expand_tasks=true parametresini ekleyin. expand_tasks etkinleştirildiğinde, tasks ve job_clusters dizilerinde en fazla 100 öğe döndürülür. Bu dizilerden biri 100'den fazla öğeye sahipse, has_more nesnesinin içindeki bir has_more alanı (kaldırılan kök düzeyi job alanıyla karıştırılmamalıdır) true. olarak ayarlanır ancak yalnızca ilk 100 öğeye erişilebilir. Listesi işleri isteğiyle ilk 100'de ek görevleri veya kümeleri alamazsınız. Daha fazla öğe getirmek için, tek bir işi veya tek bir iş çalıştırmayı döndüren istekleri kullanın. Büyük yanıt alanlarını sayfalandırmayı destekleyen güncelleştirmeler aşağıdaki bölümlerde açıklanmıştır.

Tek bir iş edinin

İşler API'si 2.2'de, Tek bir işin detaylarını almak için yapılan istek, eğer bir alanın boyutu 100 öğeyi aşıyorsa, tasks ve job_clusters alanları için sayfa düzenleme desteği sağlar. Daha fazla sonuç olup olmadığını belirlemek için nesne kökündeki next_page_token alanını kullanın. Bu alanın değeri daha sonra gelen isteklerde page_token sorgu parametresinin değeri olarak kullanılır. Bir sayfada 100'den az öğe içeren dizi alanları sonraki sayfalarda boş olacaktır.

Tek çalıştırma alma

İşler API'si 2.2'de, tek bir çalıştırmanın ayrıntılarını almak için yapılan Tek bir çalıştırma isteği, herhangi birinin boyutu 100 öğeyi aştığında tasks ve job_clusters alanlarının sayfalandırmasını artık desteklemektedir. Daha fazla sonuç olup olmadığını belirlemek için nesne kökündeki next_page_token alanını kullanın. Bu alanın değeri daha sonra gelen isteklerde page_token sorgu parametresinin değeri olarak kullanılır. Bir sayfada 100'den az öğe içeren dizi alanları sonraki sayfalarda boş olacaktır.

İşler API'si 2.2, yalnızca only_latest dizisindeki en son çalıştırma girişimlerini göstermeyi etkinleştirmek için bu uç noktaya tasks sorgu parametresini de ekler. only_latest parametresi trueolduğunda, yeniden deneme veya onarım tarafından değiştirilen tüm çalıştırmalar yanıttan atlanır.

run_id bir ForEach görev çalıştırmasını ifade ettiğinde, yanıtta iterations adlı alan mevcuttur. iterations alanı, ForEach görevinin iç içe geçmiş görevinin tüm yürütmelerine ait ayrıntıları içeren bir dizidir ve aşağıdaki özelliklere sahiptir:

  • iterations dizisindeki her nesnenin şeması, tasks dizisindeki nesnelerin şemasıyla aynıdır.
  • only_latest sorgu parametresi trueolarak ayarlanırsa, iterations dizisine yalnızca en son çalıştırma denemeleri eklenir.
  • Sayfalandırma, iterations dizisi yerine tasks dizisine uygulanır.
  • tasks dizisi yanıta dahil olmaya devam etmektedir ve ForEach görev çalıştırmasını içerir.

ForEach görevi hakkında daha fazla bilgi edinmek için ForEach görev belgelerinebakın.

Örneğin, bazı alanları atlanmış bir ForEach görevi için aşağıdaki yanıta bakın:

{
  "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": "process_all_numbers",
  "run_type": "JOB_RUN",
  "tasks": [
    {
      "run_id": 759600,
      "task_key": "process_all_numbers",
      "description": "Process all numbers",
      "for_each_task": {
        "inputs": "[ 1, 2, ..., 101 ]",
        "concurrency": 10,
        "task": {
          "task_key": "process_number_iteration"
          "notebook_task": {
            "notebook_path": "/Users/user@databricks.com/process_single_number",
            "base_parameters": {
              "number": "{{input}}"
            }
          }
        },
        "stats": {
          "task_run_stats": {
            "total_iterations": 101,
            "scheduled_iterations": 101,
            "active_iterations": 0,
            "failed_iterations": 0,
            "succeeded_iterations": 101,
            "completed_iterations": 101
          }
        }
      }
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    }
  ],
  "iterations": [
    {
      "run_id": 759601,
      "task_key": "process_number_iteration",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/process_single_number",
        "base_parameters": {
          "number": "{{input}}"
        }
      },
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    },
    {
      "run_id": 759602,
      "task_key": "process_number_iteration",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/process_single_number",
        "base_parameters": {
          "number": "{{input}}"
        }
      },
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    }
  ],
  "format": "MULTI_TASK",
  "next_page_token": "eyJ..x9"
}