التحديث من Jobs API 2.0 إلى 2.1

مقالة
03/01/2024

يمكنك الآن تنسيق مهام متعددة باستخدام وظائف Azure Databricks. توضح هذه المقالة بالتفصيل التغييرات التي تطرأ على واجهة برمجة تطبيقات الوظائف التي تدعم الوظائف ذات المهام المتعددة وتوفر إرشادات لمساعدتك في تحديث عملاء واجهة برمجة التطبيقات الحاليين للعمل مع هذه الميزة الجديدة.

توصي Databricks بوظائف API 2.1 للبرنامج النصي لواجهة برمجة التطبيقات والعملاء، خاصة عند استخدام الوظائف مع مهام متعددة.

تشير هذه المقالة إلى المهام المعرفة بمهمة واحدة بتنسيق مهمة واحدة والمهام المعرفة بمهام متعددة بتنسيق مهام متعددة.

تدعم واجهة برمجة تطبيقات الوظائف 2.0 و2.1 الآن طلب التحديث . update استخدم الطلب لتغيير مهمة موجودة بدلا من طلب إعادة التعيين لتقليل التغييرات بين مهام تنسيق مهمة واحدة ووظائف تنسيق متعددة المهام.

تغييرات واجهة برمجة التطبيقات (API)

تعرف واجهة برمجة تطبيقات الوظائف الآن كائنا TaskSettings لالتقاط الإعدادات لكل مهمة في وظيفة. بالنسبة إلى مهام التنسيق متعددة المهام، tasks يتم تضمين الحقل، وهو صفيف من TaskSettings بنيات البيانات، في JobSettings الكائن. أصبحت بعض الحقول التي سبق أن كانت جزءا منها JobSettings جزءا من إعدادات المهام لوظائف تنسيق المهام المتعددة. JobSettings يتم تحديث أيضا لتضمين format الحقل. format يشير الحقل إلى تنسيق المهمة وهو STRING قيمة تم تعيينها إلى SINGLE_TASK أو MULTI_TASK.

تحتاج إلى تحديث عملاء API الحاليين لهذه التغييرات إلى Job الإعدادات لوظائف تنسيق المهام المتعددة. راجع دليل عميل واجهة برمجة التطبيقات للحصول على مزيد من المعلومات حول التغييرات المطلوبة.

تدعم واجهة برمجة تطبيقات الوظائف 2.1 تنسيق المهام المتعددة. يجب أن تتوافق جميع طلبات API 2.1 مع تنسيق المهام المتعددة ويتم تنظيم الاستجابات بتنسيق متعدد المهام. يتم إصدار ميزات جديدة لواجهة برمجة التطبيقات 2.1 أولا.

يتم تحديث واجهة برمجة تطبيقات الوظائف 2.0 مع حقل إضافي لدعم مهام تنسيق المهام المتعددة. باستثناء الحالات التي تمت ملاحظتها، تستخدم الأمثلة في هذا المستند واجهة برمجة التطبيقات 2.0. ومع ذلك، توصي Databricks API 2.1 البرامج النصية والعملاء لواجهة برمجة التطبيقات الجديدة والموجودة.

مثال لمستند JSON يمثل مهمة تنسيق متعددة المهام لواجهة برمجة التطبيقات 2.0 و2.1:

{
  "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"
}

يدعم Jobs API 2.1 تكوين مجموعات مستوى المهمة أو مجموعة مهام مشتركة واحدة أو أكثر:

يتم إنشاء نظام مجموعة على مستوى المهمة وبدء تشغيله عند بدء مهمة وإنهائها عند اكتمال المهمة.
يسمح نظام مجموعة الوظائف المشتركة لمهام متعددة في نفس الوظيفة باستخدام نظام المجموعة. يتم إنشاء نظام المجموعة وبدء تشغيله عند بدء المهمة الأولى باستخدام نظام المجموعة وإنهاءها بعد اكتمال المهمة الأخيرة باستخدام نظام المجموعة. لا يتم إنهاء مجموعة المهام المشتركة عند الخمول ولكن يتم إنهاؤها فقط بعد اكتمال جميع المهام التي تستخدمها. يمكن أن تبدأ مهام متعددة غير تابعة تشارك مجموعة في نفس الوقت. إذا فشل نظام مجموعة مهام مشتركة أو تم إنهاؤها قبل انتهاء كافة المهام، يتم إنشاء نظام مجموعة جديد.

لتكوين مجموعات الوظائف المشتركة، قم بتضمين صفيف JobCluster في JobSettings العنصر . يمكنك تحديد 100 مجموعة كحد أقصى لكل وظيفة. فيما يلي مثال على استجابة API 2.1 لوظيفة تم تكوينها مع نظامي مجموعة مشتركين:

إشعار

إذا كانت المهمة تحتوي على تبعيات مكتبة، يجب تكوين المكتبات في task إعدادات الحقل؛ لا يمكن تكوين المكتبات في تكوين مجموعة مهام مشتركة. في المثال التالي، libraries يوضح الحقل في تكوين ingest_orders المهمة مواصفات تبعية مكتبة.

{
  "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"
}

بالنسبة إلى مهام تنسيق مهمة واحدة، JobSettings تظل بنية البيانات دون تغيير باستثناء إضافة format الحقل. لا يتم تضمين أي TaskSettings صفيف، وتظل إعدادات المهمة محددة في المستوى الأعلى من JobSettings بنية البيانات. لن تحتاج إلى إجراء تغييرات على عملاء API الحاليين لمعالجة مهام تنسيق المهمة الواحدة.

مثال لمستند JSON يمثل مهمة تنسيق مهمة واحدة لواجهة برمجة التطبيقات 2.0:

{
  "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"
}

دليل عميل واجهة برمجة التطبيقات

يوفر هذا القسم إرشادات وأمثلة والتغييرات المطلوبة لمكالمات واجهة برمجة التطبيقات المتأثرة بميزة تنسيق المهام المتعددة الجديدة.

انشاء

لإنشاء مهمة تنسيق مهمة واحدة من خلال إنشاء عملية مهمة جديدة (POST /jobs/create) في واجهة برمجة تطبيقات الوظائف، لا تحتاج إلى تغيير العملاء الحاليين.

لإنشاء مهمة تنسيق متعددة المهام، استخدم tasks الحقل في JobSettings لتحديد الإعدادات لكل مهمة. ينشئ المثال التالي مهمة مع مهمتين لدفتر الملاحظات. هذا المثال لواجهة برمجة التطبيقات 2.0 و2.1:

إشعار

يمكن تحديد 100 مهمة كحد أقصى لكل مهمة.

{
  "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
    }
  ]
}

إرسال عمليات التشغيل

لإرسال تشغيل لمرة واحدة لوظيفة تنسيق مهمة واحدة باستخدام إنشاء وتشغيل عملية تشغيل لمرة واحدة (POST /runs/submit) في واجهة برمجة تطبيقات الوظائف، لا تحتاج إلى تغيير العملاء الحاليين.

لإرسال تشغيل لمرة واحدة لمهمة تنسيق متعددة المهام، استخدم tasks الحقل في لتحديد الإعدادات لكل مهمة، بما في JobSettings ذلك المجموعات. يجب تعيين المجموعات على مستوى المهمة عند إرسال مهمة تنسيق متعددة المهام لأن runs submit الطلب لا يدعم مجموعات الوظائف المشتركة. راجع إنشاء للحصول على مثال JobSettings يحدد مهاما متعددة.

تحديث

لتحديث مهمة تنسيق مهمة واحدة مع التحديث الجزئي لعملية مهمة (POST /jobs/update) في واجهة برمجة تطبيقات الوظائف، لا تحتاج إلى تغيير العملاء الحاليين.

لتحديث إعدادات مهمة تنسيق متعددة المهام، يجب استخدام الحقل الفريد task_key لتحديد الإعدادات الجديدة task . راجع إنشاء للحصول على مثال JobSettings يحدد مهاما متعددة.

اعاده تعيين

للكتابة فوق إعدادات مهمة تنسيق مهمة واحدة مع الكتابة فوق كافة الإعدادات لعملية مهمة (POST /jobs/reset) في واجهة برمجة تطبيقات الوظائف، لا تحتاج إلى تغيير العملاء الحاليين.

للكتابة فوق إعدادات مهمة تنسيق متعددة المهام، حدد JobSettings بنية بيانات مع صفيف من TaskSettings بنيات البيانات. راجع إنشاء للحصول على مثال JobSettings يحدد مهاما متعددة.

استخدم التحديث لتغيير الحقول الفردية دون التبديل من تنسيق مهمة واحدة إلى تنسيق مهام متعددة.

قائمه

بالنسبة إلى مهام تنسيق المهمة الواحدة، لا يلزم إجراء تغييرات على العميل لمعالجة الاستجابة من عملية قائمة كافة المهام (GET /jobs/list) في واجهة برمجة تطبيقات الوظائف.

بالنسبة إلى مهام التنسيق متعددة المهام، يتم تعريف معظم الإعدادات على مستوى المهمة وليس على مستوى الوظيفة. قد يتم تعيين تكوين نظام المجموعة على مستوى المهمة أو الوظيفة. لتعديل العملاء للوصول إلى إعدادات نظام المجموعة أو المهمة لمهمة تنسيق متعددة المهام التي تم إرجاعها في Job البنية:

job_id تحليل الحقل لمهمة تنسيق المهام المتعددة.
job_id مرر إلى Get a job operation (GET /jobs/get) في Jobs API لاسترداد تفاصيل المهمة. راجع الحصول على مثال استجابة Get من استدعاء واجهة برمجة التطبيقات لمهمة تنسيق متعددة المهام.

يوضح المثال التالي استجابة تحتوي على مهام بتنسيق مهمة واحدة ومتعددة المهام. هذا المثال ل API 2.0:

{
  "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"
    }
  ]
}

الحصول

بالنسبة إلى مهام تنسيق المهمة الواحدة، لا يلزم إجراء تغييرات على العميل لمعالجة الاستجابة من عملية الحصول على وظيفة (GET /jobs/get) في واجهة برمجة تطبيقات الوظائف.

ترجع المهام متعددة المهام صفيفا من task بنيات البيانات التي تحتوي على إعدادات المهمة. إذا كنت بحاجة إلى الوصول إلى تفاصيل مستوى المهمة، فأنت بحاجة إلى تعديل العملاء للتكرار من خلال tasks الصفيف واستخراج الحقول المطلوبة.

يظهر التالي مثالا للاستجابة Get من استدعاء واجهة برمجة التطبيقات لمهمة تنسيق متعددة المهام. هذا المثال لواجهة برمجة التطبيقات 2.0 و2.1:

{
  "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"
}

الحصول على عمليات التشغيل

بالنسبة إلى مهام تنسيق مهمة واحدة، لا يلزم إجراء تغييرات على العميل لمعالجة الاستجابة من عملية الحصول على تشغيل مهمة (GET /jobs/runs/get) في واجهة برمجة تطبيقات الوظائف.

تحتوي الاستجابة لتشغيل مهمة تنسيق متعددة المهام على صفيف من TaskSettings. لاسترداد نتائج التشغيل لكل مهمة:

التكرار من خلال كل مهمة من المهام.
run_id تحليل لكل مهمة.
استدعاء الحصول على الإخراج لعملية تشغيل (GET /jobs/runs/get-output) مع run_id للحصول على تفاصيل حول التشغيل لكل مهمة. فيما يلي مثال على استجابة من هذا الطلب:

{
  "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"
}

تحصل عمليات التشغيل على الإخراج

بالنسبة إلى مهام تنسيق المهمة الواحدة، لا يلزم إجراء تغييرات على العميل لمعالجة الاستجابة من الحصول على الإخراج لعملية تشغيل (GET /jobs/runs/get-output) في واجهة برمجة تطبيقات الوظائف.

بالنسبة إلى مهام التنسيق متعددة المهام، يؤدي استدعاء Runs get output تشغيل أصل إلى حدوث خطأ حيث يتوفر إخراج التشغيل للمهام الفردية فقط. للحصول على الإخراج وبيانات التعريف لمهمة تنسيق متعددة المهام:

استدعاء الحصول على الإخراج لطلب تشغيل.
التكرار عبر الحقول التابعة run_id في الاستجابة.
استخدم القيم التابعة run_id لاستدعاء Runs get output.

قائمة عمليات التشغيل

بالنسبة إلى مهام تنسيق المهمة الواحدة، لا يلزم إجراء تغييرات على العميل لمعالجة الاستجابة من القائمة التي يتم تشغيلها لعملية مهمة (GET /jobs/runs/list).

بالنسبة إلى مهام التنسيق متعددة المهام، يتم إرجاع صفيف فارغ tasks . run_id مرر إلى عملية الحصول على تشغيل مهمة (GET /jobs/runs/get) لاسترداد المهام. يظهر التالي مثالا للاستجابة Runs list من استدعاء واجهة برمجة التطبيقات لمهمة تنسيق متعددة المهام:

{
  "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
}