作业 API 2.0

利用作业 API，可以创建、编辑和删除作业。 对作业 API 的请求的最大允许大小为 10MB。

如需详细了解支持使用 Azure Databricks 作业协调多个任务的作业 API 更新，请参阅从作业 API 2.0 更新到 2.1。

创建

端点	HTTP 方法
2.0/jobs/create	POST

创建新作业。

示例

此示例创建一个每天晚上 10:15 运行 JAR 任务的作业。

请求

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/jobs/create \
--data @create-job.json \
| jq .

create-job.json:

{
  "name": "Nightly model training",
  "new_cluster": {
    "spark_version": "7.3.x-scala2.12",
    "node_type_id": "Standard_D3_v2",
    "num_workers": 10
  },
  "libraries": [
    {
      "jar": "dbfs:/my-jar.jar"
    },
    {
      "maven": {
        "coordinates": "org.jsoup:jsoup:1.7.2"
      }
    }
  ],
  "timeout_seconds": 3600,
  "max_retries": 1,
  "schedule": {
    "quartz_cron_expression": "0 15 22 * * ?",
    "timezone_id": "America/Los_Angeles"
  },
  "spark_jar_task": {
    "main_class_name": "com.databricks.ComputeModels"
  }
}

将：

• <databricks-instance> 替换为 Azure Databricks 工作区实例名称，例如 adb-1234567890123456.7.databricks.azure.cn。
• create-job.json 的内容替换为适用于解决方案的字段。

此示例使用 .netrc 文件和 jq。

响应

{
  "job_id": 1
}

请求结构

字段名称	类型	说明
existing_cluster_id 或 new_cluster	STRING 或 NewCluster	如果是 existing_cluster_id，则该项是将用于此作业的所有运行的现有群集的 ID。 在现有群集上运行作业时，如果该群集停止响应，则可能需要手动重启该群集。 建议在新群集上运行作业，以获得更高的可靠性。 如果是 new_cluster，则该项是将为每个运行创建的群集的说明。 如果指定 PipelineTask，则此字段可为空。
notebook_task 或 spark_jar_task 或 spark_python_task 或 spark_submit_task 或 pipeline_task 或 run_job_task	NotebookTask 或 SparkJarTask 或 SparkPythonTask 或 SparkSubmitTask 或 PipelineTask 或 RunJobTask	如果是 notebook_task，则表明此作业应该运行笔记本。 此字段不能与 spark_jar_task 一起指定。 如果是 spark_jar_task，则表明此作业应该运行 JAR。 如果是 spark_python_task，则表明此作业应该运行 Python 文件。 如果是 spark_submit_task，则表明此作业应通过 spark submit 脚本启动。 如果是 pipeline_task，则表明此作业应该运行增量实时表管道。 如果是 run_job_task，则表明此作业应运行另一个作业。
name	STRING	可选的作业名称。 默认值是 Untitled。
libraries	一个由库构成的数组	可选的库列表，这些库会安装在将要执行该作业的群集上。 默认值为空列表。
email_notifications	JobEmailNotifications	一组可选的电子邮件地址，在此作业的运行开始和完成时，以及在删除此作业时，这些地址会收到通知。 默认行为是不发送任何电子邮件。
webhook_notifications	WebhookNotifications	一组可选的系统目标，用于在此作业的运行开始、完成或失败时发送通知。
notification_settings	JobNotificationSettings	向此作业的每个 email_notifications 和 webhook_notifications 发送通知时使用的可选通知设置。
timeout_seconds	INT32	可选的超时设置，应用于此作业的每个运行。 默认行为是没有任何超时。
max_retries	INT32	对未成功的运行进行重试的最大次数，可选。 如果运行在完成时其以下状态为 FAILED，则会被视为未成功：result_state 或 INTERNAL_ERROR life_cycle_state。 值 -1 表示要无限次重试，而值 0 则表示从不重试。 默认行为是从不重试。
min_retry_interval_millis	INT32	可选的最小间隔（失败运行的开始时间与随后的重试运行开始时间之间的间隔），以毫秒为单位。 默认行为是立即重试未成功的运行。
retry_on_timeout	BOOL	一个可选的策略，用于指定在作业超时是否重试该作业。默认行为是在超时发生时不重试。
schedule	CronSchedule	此作业的可选定期计划。 默认行为是，在通过单击作业 UI 中的“立即运行”或向 runNow 发送 API 请求来触发作业时，该作业会运行。
max_concurrent_runs	INT32	允许的作业最大并发运行数，可选。 如果希望能够以并发方式执行同一作业的多个运行，请设置此值。 设置此值适用于这样的情形：例如，如果你按计划频繁触发作业并希望允许连续的运行彼此重叠，或者，如果你希望触发多个在输入参数方面有区别的运行。 此设置只影响新的运行。 例如，假定作业的并发数为 4，并且存在 4 个并发的活动运行。 那么，将该并发数设置为 3 则不会终止任何活动的运行。 但是，从此之后，除非活动的运行少于 3 个，否则会跳过新的运行。 此值不能超过 1000。 将此值设置为 0 会导致跳过所有新的运行。 默认行为是只允许 1 个并发运行。

响应结构

字段名称	类型	说明
job_id	INT64	新创建的作业的规范标识符。

列表

端点	HTTP 方法
2.0/jobs/list	GET

列出所有作业。

示例

请求

curl --netrc --request GET \
https://<databricks-instance>/api/2.0/jobs/list \
| jq .

将 <databricks-instance> 替换为 Azure Databricks 工作区实例名称，例如 adb-1234567890123456.7.databricks.azure.cn。

此示例使用 .netrc 文件和 jq。

响应

{
  "jobs": [
    {
      "job_id": 1,
      "settings": {
        "name": "Nightly model training",
        "new_cluster": {
          "spark_version": "7.3.x-scala2.12",
          "node_type_id": "Standard_D3_v2",
          "num_workers": 10
        },
        "libraries": [
          {
            "jar": "dbfs:/my-jar.jar"
          },
          {
            "maven": {
              "coordinates": "org.jsoup:jsoup:1.7.2"
            }
          }
        ],
        "timeout_seconds": 100000000,
        "max_retries": 1,
        "schedule": {
          "quartz_cron_expression": "0 15 22 * * ?",
          "timezone_id": "America/Los_Angeles",
          "pause_status": "UNPAUSED"
        },
        "spark_jar_task": {
          "main_class_name": "com.databricks.ComputeModels"
        }
      },
      "created_time": 1457570074236
    }
  ]
}

响应结构

字段名称	类型	说明
jobs	一个由作业构成的数组	作业的列表。

删除

端点	HTTP 方法
2.0/jobs/delete	POST

删除某个作业并向 JobSettings.email_notifications 中指定的地址发送电子邮件。 如果已删除该作业，则不会执行任何操作。 删除该作业后，作业 UI 或 API 中均无法查看其详细信息或其运行历史记录。 在此请求完成时，该作业一定会被删除。 但是，在接收此请求之前处于活动状态的运行可能仍会处于活动状态。 它们将会被异步终止。

示例

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/jobs/delete \
--data '{ "job_id": <job-id> }'

将：

• <databricks-instance> 替换为 Azure Databricks 工作区实例名称，例如 adb-1234567890123456.7.databricks.azure.cn。
• <job-id> 替换为作业的 ID，例如 123。

此示例使用 .netrc 文件。

请求结构

字段名称	类型	说明
job_id	INT64	要删除的作业的规范标识符。 此字段为必需字段。

Get

端点	HTTP 方法
2.0/jobs/get	GET

检索有关某一个作业的信息。

示例

请求

curl --netrc --request GET \
'https://<databricks-instance>/api/2.0/jobs/get?job_id=<job-id>' \
| jq .

或：

curl --netrc --get \
https://<databricks-instance>/api/2.0/jobs/get \
--data job_id=<job-id> \
| jq .

将：

• <databricks-instance> 替换为 Azure Databricks 工作区实例名称，例如 adb-1234567890123456.7.databricks.azure.cn。
• <job-id> 替换为作业的 ID，例如 123。

此示例使用 .netrc 文件和 jq。

响应

{
  "job_id": 1,
  "settings": {
    "name": "Nightly model training",
    "new_cluster": {
      "spark_version": "7.3.x-scala2.12",
      "node_type_id": "Standard_D3_v2",
      "num_workers": 10
    },
    "libraries": [
      {
        "jar": "dbfs:/my-jar.jar"
      },
      {
        "maven": {
          "coordinates": "org.jsoup:jsoup:1.7.2"
        }
      }
    ],
    "timeout_seconds": 100000000,
    "max_retries": 1,
    "schedule": {
      "quartz_cron_expression": "0 15 22 * * ?",
      "timezone_id": "America/Los_Angeles",
      "pause_status": "UNPAUSED"
    },
    "spark_jar_task": {
      "main_class_name": "com.databricks.ComputeModels"
    }
  },
  "created_time": 1457570074236
}

请求结构

字段名称	类型	说明
job_id	INT64	要检索其相关信息的作业的规范标识符。 此字段为必需字段。

响应结构

字段名称	类型	说明
job_id	INT64	此作业的规范标识符。
creator_user_name	STRING	创建者用户名。 如果已将该用户删除，响应中将不会包含此字段。
settings	JobSettings	此作业及其所有运行的设置。 可以使用重置或更新终结点更新这些设置。
created_time	INT64	此作业的创建时间，以 epoch 毫秒表示（自 UTC 1970 年 1 月 1 日起的毫秒数）。

重置

端点	HTTP 方法
2.0/jobs/reset	POST

覆盖特定作业的所有设置。 使用更新终结点部分更新作业设置。

示例

此示例请求使作业 2 与创建示例中的作业 1 相同。

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/jobs/reset \
--data @reset-job.json \
| jq .

reset-job.json:

{
  "job_id": 2,
  "new_settings": {
    "name": "Nightly model training",
    "new_cluster": {
      "spark_version": "7.3.x-scala2.12",
      "node_type_id": "Standard_D3_v2",
      "num_workers": 10
    },
    "libraries": [
      {
        "jar": "dbfs:/my-jar.jar"
      },
      {
        "maven": {
          "coordinates": "org.jsoup:jsoup:1.7.2"
        }
      }
    ],
    "timeout_seconds": 100000000,
    "max_retries": 1,
    "schedule": {
      "quartz_cron_expression": "0 15 22 * * ?",
      "timezone_id": "America/Los_Angeles",
      "pause_status": "UNPAUSED"
    },
    "spark_jar_task": {
      "main_class_name": "com.databricks.ComputeModels"
    }
  }
}

将：

• <databricks-instance> 替换为 Azure Databricks 工作区实例名称，例如 adb-1234567890123456.7.databricks.azure.cn。
• reset-job.json 的内容替换为适用于解决方案的字段。

此示例使用 .netrc 文件和 jq。

请求结构

字段名称	类型	说明
job_id	INT64	要重置的作业的规范标识符。 此字段为必需字段。
new_settings	JobSettings	作业的新设置。 这些设置完全替代了旧设置。 对字段 JobSettings.timeout_seconds 的更改会应用于活动运行。 对其他字段的更改仅应用于未来运行。

更新

端点	HTTP 方法
2.0/jobs/update	POST

添加、更改或删除现有作业的特定设置。 使用重置终结点覆盖所有作业设置。

示例

此示例请求删除库并将电子邮件通知设置添加到在创建示例中定义的作业 1。

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/jobs/update \
--data @update-job.json \
| jq .

update-job.json:

{
  "job_id": 1,
  "new_settings": {
    "existing_cluster_id": "1201-my-cluster",
    "email_notifications": {
      "on_start": [ "someone@example.com" ],
      "on_success": [],
      "on_failure": []
    }
  },
  "fields_to_remove": ["libraries"]
}

将：

• <databricks-instance> 替换为 Azure Databricks 工作区实例名称，例如 adb-1234567890123456.7.databricks.azure.cn。
• update-job.json 的内容替换为适用于解决方案的字段。

此示例使用 .netrc 文件和 jq。

请求结构

字段名称	类型	说明
job_id	INT64	要更新的作业的规范标识符。 此字段为必需字段。
new_settings	JobSettings	作业的新设置。 new_settings 中指定的顶级字段（数组除外）都将完全被替换。 数组根据相应的键字段（如 task_key 或 job_cluster_key）合并，具有相同键的数组条目将被完全替换。 除了数组合并之外，部分更新嵌套字段不受支持。 对字段 JobSettings.timeout_seconds 的更改会应用于活动运行。 对其他字段的更改仅应用于未来运行。
fields_to_remove	一个由 STRING 构成的数组	删除作业设置中的顶级字段。 删除嵌套字段不受支持，但 tasks 和 job_clusters 数组中的条目除外。 例如，下面是此字段的有效参数： ["libraries", "schedule", "tasks/task_1", "job_clusters/Default"] 此字段可选。

立即运行

端点	HTTP 方法
2.0/jobs/run-now	POST

立即运行作业，并返回已触发的运行的 run_id。

示例

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/jobs/run-now \
--data @run-job.json \
| jq .

run-job.json:

笔记本作业的示例请求：

{
  "job_id": 1,
  "notebook_params": {
    "name": "john doe",
    "age": "35"
  }
}

JAR 作业的示例请求：

{
  "job_id": 2,
  "jar_params": [ "john doe", "35" ]
}

将：

• <databricks-instance> 替换为 Azure Databricks 工作区实例名称，例如 adb-1234567890123456.7.databricks.azure.cn。
• run-job.json 的内容替换为适用于解决方案的字段。

此示例使用 .netrc 文件和 jq。

请求结构

字段名称	类型	说明
job_id	INT64
jar_params	一个由 STRING 构成的数组	具有 JAR 任务的作业的参数列表，例如 "jar_params": ["john doe", "35"]。 这些参数将用于调用 Spark JAR 任务中指定的 main 类的 main 函数。 如果未在调用 run-now 时指定，该项将默认为空列表。 jar_params 不能与 notebook_params 一起指定。 此字段的 JSON 表示形式（即 {"jar_params":["john doe","35"]}）不能超过 10,000 字节。
notebook_params	ParamPair 的映射	具有笔记本任务的作业的从键到值的映射，例如 "notebook_params": {"name": "john doe", "age": "35"}。 该映射会传递到笔记本，并且可通过 dbutils.widgets.get 函数访问。 如果未在调用 run-now 时指定，已触发的运行会使用该作业的基参数。 无法将 notebook_params 与 jar_params 一起指定。 此字段的 JSON 表示形式（即 {"notebook_params":{"name":"john doe","age":"35"}}）不能超过 10,000 字节。
python_params	一个由 STRING 构成的数组	具有 Python 任务的作业的参数列表，例如 "python_params": ["john doe", "35"]。 这些参数将会作为命令行参数传递到 Python 文件。 如果在调用 run-now 时指定，则此项会覆盖作业设置中指定的参数。 此字段的 JSON 表示形式（即 {"python_params":["john doe","35"]}）不能超过 10,000 字节。
spark_submit_params	一个由 STRING 构成的数组	具有“Spark 提交”任务的作业的参数列表，例如 "spark_submit_params": ["--class", "org.apache.spark.examples.SparkPi"]。 这些参数将会作为命令行参数传递到 spark-submit 脚本。 如果在调用 run-now 时指定，则此项会覆盖作业设置中指定的参数。 此字段的 JSON 表示形式不能超过 10,000 字节。
idempotency_token	STRING	可选令牌，用于保证作业运行请求的幂等性。 如果已存在具有提供的令牌的运行，该请求将不会创建新运行，而是会返回现有运行的 ID。 如果删除具有提供的令牌的运行，则返回错误。 如果指定幂等性令牌，则可在失败时重试，直到该请求成功。 Azure Databricks 会确保只有一个运行通过该幂等性令牌启动。 此令牌最多只能包含 64 个字符。 有关详细信息，请参阅如何确保作业的幂等性。

响应结构

字段名称	类型	说明
run_id	INT64	新触发的运行的全局唯一 ID。
number_in_job	INT64	此运行在该作业的所有运行中的序列号。

运行提交

端点	HTTP 方法
2.0/jobs/runs/submit	POST

提交一次性运行。 通过此终结点，你无需创建作业即可直接提交工作负载。 在提交作业后使用 jobs/runs/get API 查看运行状态。

示例

请求

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/jobs/runs/submit \
--data @submit-job.json \
| jq .

submit-job.json:

{
  "run_name": "my spark task",
  "new_cluster": {
    "spark_version": "7.3.x-scala2.12",
    "node_type_id": "Standard_D3_v2",
    "num_workers": 10
  },
  "libraries": [
    {
      "jar": "dbfs:/my-jar.jar"
    },
    {
      "maven": {
        "coordinates": "org.jsoup:jsoup:1.7.2"
      }
    }
  ],
  "spark_jar_task": {
    "main_class_name": "com.databricks.ComputeModels"
  }
}

将：

• <databricks-instance> 替换为 Azure Databricks 工作区实例名称，例如 adb-1234567890123456.7.databricks.azure.cn。
• submit-job.json 的内容替换为适用于解决方案的字段。

此示例使用 .netrc 文件和 jq。

响应

{
  "run_id": 123
}

请求结构

字段名称	类型	说明
existing_cluster_id 或 new_cluster	STRING 或 NewCluster	如果是 existing_cluster_id，则该项是将用于此作业的所有运行的现有群集的 ID。 在现有群集上运行作业时，如果该群集停止响应，则可能需要手动重启该群集。 建议在新群集上运行作业，以获得更高的可靠性。 如果是 new_cluster，则该项是将为每个运行创建的群集的说明。 如果指定 PipelineTask，那么此字段可为空。
notebook_task 或 spark_jar_task 或 spark_python_task 或 spark_submit_task 或 pipeline_task 或 run_job_task	NotebookTask 或 SparkJarTask 或 SparkPythonTask 或 SparkSubmitTask 或 PipelineTask 或 RunJobTask	如果是 notebook_task，则表明此作业应该运行笔记本。 此字段不能与 spark_jar_task 一起指定。 如果是 spark_jar_task，则表明此作业应该运行 JAR。 如果是 spark_python_task，则表明此作业应该运行 Python 文件。 如果是 spark_submit_task，则表明此作业应通过 spark submit 脚本启动。 如果是 pipeline_task，则表明此作业应该运行增量实时表管道。 如果是 run_job_task，则表明此作业应运行另一个作业。
run_name	STRING	可选的作业名称。 默认值是 Untitled。
webhook_notifications	WebhookNotifications	一组可选的系统目标，用于在此作业的运行开始、完成或失败时发送通知。
notification_settings	JobNotificationSettings	向此运行的每个 webhook_notifications 发送通知时使用的可选通知设置。
libraries	一个由库构成的数组	可选的库列表，这些库会安装在将要执行该作业的群集上。 默认值为空列表。
timeout_seconds	INT32	可选的超时设置，应用于此作业的每个运行。 默认行为是没有任何超时。
idempotency_token	STRING	可选令牌，用于保证作业运行请求的幂等性。 如果已存在具有提供的令牌的运行，该请求将不会创建新运行，而是会返回现有运行的 ID。 如果删除具有提供的令牌的运行，则返回错误。 如果指定幂等性令牌，则可在失败时重试，直到该请求成功。 Azure Databricks 会确保只有一个运行通过该幂等性令牌启动。 此令牌最多只能包含 64 个字符。 有关详细信息，请参阅如何确保作业的幂等性。

响应结构

字段名称	类型	说明
run_id	INT64	新提交的运行的规范标识符。

运行列表

端点	HTTP 方法
2.0/jobs/runs/list	GET

列表按开始时间以降序顺序运行。

示例

请求

curl --netrc --request GET \
'https://<databricks-instance>/api/2.0/jobs/runs/list?job_id=<job-id>&active_only=<true-false>&offset=<offset>&limit=<limit>&run_type=<run-type>' \
| jq .

或：

curl --netrc --get \
https://<databricks-instance>/api/2.0/jobs/runs/list \
--data 'job_id=<job-id>&active_only=<true-false>&offset=<offset>&limit=<limit>&run_type=<run-type>' \
| jq .

将：

• <databricks-instance> 替换为 Azure Databricks 工作区实例名称，例如 adb-1234567890123456.7.databricks.azure.cn。
• <job-id> 替换为作业的 ID，例如 123。
• “<true-false> 替换为 true 或 false”。
• <offset> 替换为 offset 值。
• <limit> 替换为 limit 值。
• <run-type> 替换为 run_type 值。

此示例使用 .netrc 文件和 jq。

响应

{
  "runs": [
    {
      "job_id": 1,
      "run_id": 452,
      "number_in_job": 5,
      "state": {
        "life_cycle_state": "RUNNING",
        "state_message": "Performing action"
      },
      "task": {
        "notebook_task": {
          "notebook_path": "/Users/donald@duck.com/my-notebook"
        }
      },
      "cluster_spec": {
        "existing_cluster_id": "1201-my-cluster"
      },
      "cluster_instance": {
        "cluster_id": "1201-my-cluster",
        "spark_context_id": "1102398-spark-context-id"
      },
      "overriding_parameters": {
        "jar_params": ["param1", "param2"]
      },
      "start_time": 1457570074236,
      "end_time": 1457570075149,
      "setup_duration": 259754,
      "execution_duration": 3589020,
      "cleanup_duration": 31038,
      "run_duration": 3879812,
      "trigger": "PERIODIC"
    }
  ],
  "has_more": true
}

请求结构

字段名称	类型	说明
active_only 或 completed_only	BOOL 或 BOOL	如果 active_only 为 true，则结果中只包括活动运行；否则会将活动运行和已完成的运行都列出。 活动运行是 RunLifecycleState 为 PENDING、RUNNING 或 TERMINATING 的运行。 在 completed_only 为 true 时，此字段不能为 true。 如果 completed_only 为 true，则结果中仅包括已完成的运行；否则会将活动运行和已完成的运行都列出。 在 active_only 为 true 时，此字段不能为 true。
job_id	INT64	要列出其运行的作业。 如果省略，作业服务将会列出所有作业中的运行。
offset	INT32	要返回的第一个运行的偏移量（相对于最近的运行）。
limit	INT32	要返回的运行数。 此值应大于 0 且小于 1000。 默认值为 20。 如果请求将限制指定为 0，该服务将会改用最大限制。
run_type	STRING	要返回的运行类型。 有关运行类型的说明，请参阅运行。

响应结构

字段名称	类型	说明
runs	一个由运行构成的数组	运行的列表，按启动时间（由近到远）列出。
has_more	BOOL	如果为 true，则可以列出与提供的筛选器匹配的其他运行。

运行获取

端点	HTTP 方法
2.0/jobs/runs/get	GET

检索运行的元数据。

示例

请求

curl --netrc --request GET \
'https://<databricks-instance>/api/2.0/jobs/runs/get?run_id=<run-id>' \
| jq .

或：

curl --netrc --get \
https://<databricks-instance>/api/2.0/jobs/runs/get \
--data run_id=<run-id> \
| jq .

将：

• <databricks-instance> 替换为 Azure Databricks 工作区实例名称，例如 adb-1234567890123456.7.databricks.azure.cn。
• <run-id> 替换为运行的 ID，例如 123。

此示例使用 .netrc 文件和 jq。

响应

{
  "job_id": 1,
  "run_id": 452,
  "number_in_job": 5,
  "state": {
    "life_cycle_state": "RUNNING",
    "state_message": "Performing action"
  },
  "task": {
    "notebook_task": {
      "notebook_path": "/Users/someone@example.com/my-notebook"
    }
  },
  "cluster_spec": {
    "existing_cluster_id": "1201-my-cluster"
  },
  "cluster_instance": {
    "cluster_id": "1201-my-cluster",
    "spark_context_id": "1102398-spark-context-id"
  },
  "overriding_parameters": {
    "jar_params": ["param1", "param2"]
  },
  "start_time": 1457570074236,
  "end_time": 1457570075149,
  "setup_duration": 259754,
  "execution_duration": 3589020,
  "cleanup_duration": 31038,
  "run_duration": 3879812,
  "trigger": "PERIODIC"
}

请求结构

字段名称	类型	说明
run_id	INT64	要检索其元数据的运行的规范标识符。 此字段为必需字段。

响应结构

字段名称	类型	说明
job_id	INT64	包含此运行的作业的规范标识符。
run_id	INT64	该运行的规范标识符。 此 ID 在所有作业的所有运行中都是唯一的。
number_in_job	INT64	此运行在该作业的所有运行中的序列号。 此值从 1 开始。
original_attempt_run_id	INT64	如果此运行是对之前某次运行尝试的重试，则此字段会包含原始尝试的 run_id；否则此字段与本次运行的 run_id 相同。
state	RunState	运行的结果和生命周期状态。
schedule	CronSchedule	触发此运行的 cron 计划（如果此运行已由定期计划程序触发）。
task	JobTask	由该运行执行的任务（如果有）。
cluster_spec	ClusterSpec	创建此运行时作业的群集规范的快照。
cluster_instance	ClusterInstance	用于此运行的群集。 如果将该运行指定为使用新群集，则在作业服务已为该运行请求群集后，将会设置此字段。
overriding_parameters	RunParameters	用于此运行的参数。
start_time	INT64	启动此运行的时间，以epoch 毫秒表示（自 UTC 1970 年 1 月 1 日起的毫秒数）。 此时间可能不是作业任务开始执行的时间，例如，如果该作业已计划在新群集上运行，则此时间是发出群集创建调用的时间。
end_time	INT64	此运行结束的时间，以 epoch 毫秒表示（自 UTC 1970/1/1 起的毫秒数）。 如果作业仍在运行，则此字段将设置为 0。
setup_duration	INT64	设置群集所花费的时间（以毫秒为单位）。 对于在新群集上运行的运行，此时间是群集创建时间，对于在现有群集上运行的运行，此时间应该很短。 该运行的总持续时间是 setup_duration、 execution_duration 和 cleanup_duration 的总和。 对于多任务作业运行，setup_duration 字段设置为 0。 多任务作业运行的总持续时间为 run_duration 字段的值。
execution_duration	INT64	执行 JAR 或笔记本中的命令（直到这些命令已完成、失败、超时、被取消或遇到意外错误）所花费的时间（以毫秒为单位）。 该运行的总持续时间是 setup_duration 加 execution_duration，再加 cleanup_duration。 对于多任务作业运行，execution_duration 字段设置为 0。 作业多任务作业运行的总持续时间是 run_duration 字段的值。
cleanup_duration	INT64	终止该群集并清理任何关联项目所花费的时间（以毫秒为单位）。 该运行的总持续时间是 setup_duration、execution_duration 和 cleanup_duration 的总和。 对于多任务作业运行，cleanup_duration 字段设置为 0。 作业多任务作业运行的总持续时间是 run_duration 字段的值。
run_duration	INT64	运行作业及完成其所有修复所花费的时间（以毫秒为单位）。 此字段仅为多任务作业运行设置，而不针对任务运行设置。 任务运行的持续时间是 setup_duration、execution_duration 和 cleanup_duration 的总和。
trigger	TriggerType	触发此运行的触发器类型。
creator_user_name	STRING	创建者用户名。 如果已将该用户删除，响应中将不会包含此字段
run_page_url	STRING	运行的详细信息页的 URL。

运行导出

端点	HTTP 方法
2.0/jobs/runs/export	GET

导出并检索作业运行任务。

示例

请求

curl --netrc --request GET \
'https://<databricks-instance>/api/2.0/jobs/runs/export?run_id=<run-id>' \
| jq .

或：

curl --netrc --get \
https://<databricks-instance>/api/2.0/jobs/runs/export \
--data run_id=<run-id> \
| jq .

将：

• <databricks-instance> 替换为 Azure Databricks 工作区实例名称，例如 adb-1234567890123456.7.databricks.azure.cn。
• <run-id> 替换为运行的 ID，例如 123。

此示例使用 .netrc 文件和 jq。

响应

{
  "views": [ {
    "content": "<!DOCTYPE html><html><head>Head</head><body>Body</body></html>",
    "name": "my-notebook",
    "type": "NOTEBOOK"
  } ]
}

若要从 JSON 响应中提取 HTML 笔记本，请下载并运行此 Python 脚本。

请求结构

字段名称	类型	说明
run_id	INT64	该运行的规范标识符。 此字段为必需字段。
views_to_export	ViewsToExport	要导出哪些视图（CODE、DASHBOARDS 或 ALL）。 默认为“CODE”。

响应结构

字段名称	类型	说明
views	一个由 ViewItem 构成的数组	HTML 格式的导出内容（每个视图项一个）。

运行取消

端点	HTTP 方法
2.0/jobs/runs/cancel	POST

取消作业运行。 该运行会被异步取消，因此，在此请求完成时，该运行可能仍在运行。 该运行稍后将会被终止。 如果该运行已处于最终的 life_cycle_state，则此方法为无操作。

此终结点会验证 run_id 参数是否有效，如果参数无效，则会返回 HTTP 状态代码 400。

示例

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/jobs/runs/cancel \
--data '{ "run_id": <run-id> }'

将：

• <databricks-instance> 替换为 Azure Databricks 工作区实例名称，例如 adb-1234567890123456.7.databricks.azure.cn。
• <run-id> 替换为运行的 ID，例如 123。

此示例使用 .netrc 文件。

请求结构

字段名称	类型	说明
run_id	INT64	要取消的运行的规范标识符。 此字段为必需字段。

运行取消全部

端点	HTTP 方法
2.0/jobs/runs/cancel-all	POST

取消作业的所有活动运行。 由于运行以异步方式取消，因此不会阻止启动新运行。

此终结点会验证 job_id 参数是否有效，如果参数无效，则会返回 HTTP 状态代码 400。

示例

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/jobs/runs/cancel-all \
--data '{ "job_id": <job-id> }'

将：

• <databricks-instance> 替换为 Azure Databricks 工作区实例名称，例如 adb-1234567890123456.7.databricks.azure.cn。
• <job-id> 替换为作业的 ID，例如 123。

此示例使用 .netrc 文件。

请求结构

字段名称	类型	说明
job_id	INT64	要取消所有运行的作业的规范标识符。 此字段为必需字段。

运行获取输出

端点	HTTP 方法
2.0/jobs/runs/get-output	GET

检索单个任务运行的输出和元数据。 在笔记本任务通过 dbutils.notebook.exit() 调用返回一个值时，可以使用此终结点来检索该值。 Azure Databricks 将此 API 限制为返回输出中的前 5 MB。 若要返回更大的结果，可将作业结果存储在云存储服务中。

此终结点会验证 run_id 参数是否有效，如果参数无效，则会返回 HTTP 状态代码 400。

运行在 60 天之后会自动删除。 如果在 60 天之后还需要引用这些运行，则应在它们过期之前保存旧运行结果。 若要使用 UI 导出，请参阅导出作业运行结果。 若要使用作业 API 导出，请参阅运行导出。

示例

请求

curl --netrc --request GET \
'https://<databricks-instance>/api/2.0/jobs/runs/get-output?run_id=<run-id>' \
| jq .

或：

curl --netrc --get \
https://<databricks-instance>/api/2.0/jobs/runs/get-output \
--data run_id=<run-id> \
| jq .

将：

• <databricks-instance> 替换为 Azure Databricks 工作区实例名称，例如 adb-1234567890123456.7.databricks.azure.cn。
• <run-id> 替换为运行的 ID，例如 123。

此示例使用 .netrc 文件和 jq。

响应

{
  "metadata": {
    "job_id": 1,
    "run_id": 452,
    "number_in_job": 5,
    "state": {
      "life_cycle_state": "TERMINATED",
      "result_state": "SUCCESS",
      "state_message": ""
    },
    "task": {
      "notebook_task": {
        "notebook_path": "/Users/someone@example.com/my-notebook"
      }
    },
    "cluster_spec": {
      "existing_cluster_id": "1201-my-cluster"
    },
    "cluster_instance": {
      "cluster_id": "1201-my-cluster",
      "spark_context_id": "1102398-spark-context-id"
    },
    "overriding_parameters": {
      "jar_params": ["param1", "param2"]
    },
    "start_time": 1457570074236,
    "setup_duration": 259754,
    "execution_duration": 3589020,
    "cleanup_duration": 31038,
    "run_duration": 3879812,
    "trigger": "PERIODIC"
  },
  "notebook_output": {
    "result": "the maybe truncated string passed to dbutils.notebook.exit()"
  }
}

请求结构

字段名称	类型	说明
run_id	INT64	该运行的规范标识符。 对于具有多个任务的作业，这是任务运行的 run_id。 请参阅运行获取输出。 此字段为必需字段。

响应结构

字段名称	类型	说明
notebook_output 或 error	NotebookOutput 或 STRING	如果是 notebook_output，则该项是笔记本任务的输出（如果可用）。 在未调用的情况下终止（成功或失败）的笔记本任务 dbutils.notebook.exit() 被视为会有一个空输出。 此字段将会被设置，但其结果值将为空。 如果是 error，则此项是一个错误消息，指示输出不可用的原因。 该消息是非结构化的，且其确切格式随时可能发生变更。
metadata	运行	该运行的全部详细信息（其输出除外）。

运行删除

端点	HTTP 方法
2.0/jobs/runs/delete	POST

删除非活动运行。 如果该运行处于活动状态，则返回错误。

示例

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/jobs/runs/delete \
--data '{ "run_id": <run-id> }'

将：

• <databricks-instance> 替换为 Azure Databricks 工作区实例名称，例如 adb-1234567890123456.7.databricks.azure.cn。
• <run-id> 替换为运行的 ID，例如 123。

此示例使用 .netrc 文件。

请求结构

字段名称	类型	说明
run_id	INT64	要检索其元数据的运行的规范标识符。

数据结构

本节内容：

• ABFSSStorageInfo
• 自动缩放
• AzureAttributes
• AzureAvailability
• ClusterInstance
• ClusterLogConf
• ClusterSpec
• ClusterTag
• CronSchedule
• DbfsStorageInfo
• FileStorageInfo
• InitScriptInfo
• 作业
• JobEmailNotifications
• JobNotificationSettings
• JobSettings
• JobTask
• JobsHealthRule
• JobsHealthRules
• Library
• MavenLibrary
• NewCluster
• NotebookOutput
• NotebookTask
• ParamPair
• PipelineTask
• PythonPyPiLibrary
• RCranLibrary
• 运行
• RunJobTask
• RunLifeCycleState
• RunParameters
• RunResultState
• RunState
• SparkConfPair
• SparkEnvPair
• SparkJarTask
• SparkPythonTask
• SparkSubmitTask
• TriggerType
• ViewItem
• ViewType
• ViewsToExport
• Webhook
• WebhookNotifications
• WorkspaceStorageInfo

ABFSSStorageInfo

Azure Data Lake Storage (ADLS) 存储信息。

字段名称	类型	说明
destination	STRING	文件目标。 示例： abfss://...

自动缩放

定义群集工作器的最小数量和最大数量的范围。

字段名称	类型	说明
min_workers	INT32	群集在未充分利用时可纵向缩减到的最小工作器数。 此数量也是群集在创建后将会具有的初始工作器的数量。
max_workers	INT32	群集在负载过高时可纵向扩展到的最大工作器数。 max_workers 必须严格大于 min_workers。

AzureAttributes

在群集创建过程中与 Azure 相关的属性集。

字段名称	类型	说明
first_on_demand	INT32	群集的前 first_on_demand 个节点将被放置在按需实例上。 该值必须大于 0，否则群集创建验证会失败。 如果该值大于或等于当前群集大小，则所有节点都将放置在按需实例上。 如果该值小于当前群集大小，则 first_on_demand 节点将被放置在按需实例上，其余节点则放置在可用性实例上。 该值不影响群集大小，并且无法在群集的整个生存期内进行更改。
availability	AzureAvailability	first_on_demand 节点之后所有后续节点所使用的可用性类型。
spot_bid_max_price	DOUBLE	Azure 竞价实例所使用的最高出价。 可以将其设置为大于或等于当前竞价。 也可将其设置为 -1（默认值），该值指定不能根据价格收回实例。 实例的价格将是竞价实例的当前价格或标准实例的价格。 可以在 Azure 门户中查看历史定价和收回率。

AzureAvailability

Azure 实例可用性类型行为。

类型	说明
SPOT_AZURE	使用竞价实例。
ON_DEMAND_AZURE	使用按需实例。
SPOT_WITH_FALLBACK_AZURE	最好使用竞价实例，但如果无法获取竞价实例（例如，如果 Azure 竞价太高或超出配额），则改用按需实例。 不适用于池可用性。

ClusterInstance

某个运行所使用的群集和 Spark 上下文的标识符。 这两个值总是会共同标识执行上下文。

字段名称	类型	说明
cluster_id	STRING	某个运行所使用的群集的规范标识符。 此字段始终可用于现有群集上的运行。 对于新群集上的运行，此字段会在创建群集后变为可用。 可使用此值来查看日志，具体方法是浏览到 /#setting/sparkui/$cluster_id/driver-logs。 在运行完成之后，日志将继续可用。 如果此标识符尚不可用，响应将不包含此字段。
spark_context_id	STRING	某个运行所使用的 Spark 上下文的规范标识符。 该运行开始执行后，此字段将会被填充。 可使用此值来查看 Spark UI，具体方法是浏览到 /#setting/sparkui/$cluster_id/$spark_context_id。 在运行完成之后，Spark UI 将继续可用。 如果此标识符尚不可用，响应将不包含此字段。

ClusterLogConf

群集日志的路径。

字段名称	类型	说明
dbfs	DbfsStorageInfo	群集日志的 DBFS 位置。 必须提供目标。 例如，应用于对象的 { "dbfs" : { "destination" : "dbfs:/home/cluster_log" } }

ClusterSpec

字段名称	类型	说明
existing_cluster_id 或 new_cluster	STRING 或 NewCluster	如果是 existing_cluster_id，则该项是将用于此作业的所有运行的现有群集的 ID。 在现有群集上运行作业时，如果该群集停止响应，则可能需要手动重启该群集。 建议在新群集上运行作业，以获得更高的可靠性。 如果是 new_cluster，则该项是将为每个运行创建的群集的说明。 如果指定 PipelineTask，那么此字段可为空。
libraries	一个由库构成的数组	可选的库列表，这些库会安装在将要执行该作业的群集上。 默认值为空列表。

ClusterTag

群集标记定义。

类型	描述
STRING	标记的键。 该键必须符合以下要求： * 长度介于 1 到 512 个字符之间 * 未包含 <>%*&+?\\/ 中的任何字符 * 不以 azure、microsoft 或 windows 开头
STRING	标记的值。 值的长度必须小于或等于 256 个 UTF-8 字符。

CronSchedule

字段名称	类型	说明
quartz_cron_expression	STRING	一个使用 Quartz 语法的 Cron 表达式，用于描述作业的计划。 有关详细信息，请参阅 Cron 触发器。 此字段为必需字段。
timezone_id	STRING	Java 时区 ID。 将根据此时区解析作业的计划。 有关详细信息，请参阅 Java 时区。 此字段为必需字段。
pause_status	STRING	指示此计划是否已暂停。 值为“PAUSED”或“UNPAUSED”。

DbfsStorageInfo

DBFS 存储信息。

字段名称	类型	说明
destination	STRING	DBFS 目标。 示例： dbfs:/my/path

FileStorageInfo

文件存储信息。

字段名称	类型	说明
destination	STRING	文件目标。 示例： file:/my/file.sh

InitScriptInfo

初始化脚本的路径。

若要了解如何将初始化脚本与 Databricks 容器服务配合使用，请参阅使用初始化脚本。

字段名称	类型	说明
workspace OR dbfs（已弃用） OR abfss	WorkspaceStorageInfo DbfsStorageInfo（已弃用） ABFSSStorageInfo	init 脚本的工作区位置。 必须提供目标。 例如，应用于对象的 { "workspace" : { "destination" : "/Users/someone@domain.com/init_script.sh" } } （已弃用）init 脚本的 DBFS 位置。 必须提供目标。 例如，应用于对象的 { "dbfs" : { "destination" : "dbfs:/home/init_script" } } init 脚本的 Azure Data Lake Storage (ADLS) 位置。 必须提供目标。 例如，{ "abfss": { "destination" : "abfss://..." } }

作业

字段名称	类型	说明
job_id	INT64	此作业的规范标识符。
creator_user_name	STRING	创建者用户名。 如果已将该用户删除，响应中将不会包含此字段。
run_as	STRING	作业运行时所用的用户名。 run_as 基于当前作业设置，如果禁用了作业访问控制，则设置为作业的创建者，如果启用了作业访问控制，则设置为 is_owner 权限。
settings	JobSettings	此作业及其所有运行的设置。 可以使用 resetJob 方法来更新这些设置。
created_time	INT64	此作业的创建时间，以 epoch 毫秒表示（自 UTC 1970 年 1 月 1 日起的毫秒数）。

JobEmailNotifications

字段名称	类型	说明
on_start	一个由 STRING 构成的数组	一个电子邮件地址列表，其中的电子邮件地址在运行开始时会收到通知。 如果在创建、重置或更新作业时未指定该列表，则该列表为空，并且不发送通知。
on_success	一个由 STRING 构成的数组	一个电子邮件地址列表，其中的电子邮件地址在运行成功完成时会收到通知。 如果运行以 TERMINATED life_cycle_state 和 SUCCESSFUL result_state 结束，则该运行被视为已成功完成。 如果在创建、重置或更新作业时未指定该列表，则该列表为空，并且不发送通知。
on_failure	一个由 STRING 构成的数组	一个电子邮件地址列表，其中的电子邮件地址在运行未成功完成时会收到通知。 如果运行在结束时有 INTERNAL_ERROR life_cycle_state，或者有 SKIPPED、FAILED 或 TIMED_OUT result_state，则该运行会被视为未成功完成。 如果在创建、重置或更新作业时未指定此项，则列表为空，并且不发送通知。
on_duration_warning_threshold_exceeded	一个由 STRING 构成的数组	当运行持续时间超过 health 字段中为 RUN_DURATION_SECONDS 指标指定的阈值时，要向其发送通知的电子邮件地址列表。 如果未在作业的 health 字段中为 RUN_DURATION_SECONDS 指标指定规则，则不发送通知。
no_alert_for_skipped_runs	BOOL	如果为 true，则在该运行被跳过的情况下不会向 on_failure 中指定的收件人发送电子邮件。

字段名称	类型	说明
on_start	Webhook 的数组	运行开始时要向其发送通知的可选系统目标列表。 如果在创建、重置或更新作业时未指定该列表，则该列表为空，并且不发送通知。 最多可为 on_start 属性指定 3 个目标。
on_success	Webhook 的数组	运行成功完成时要向其发送通知的可选系统目标列表。 如果运行以 TERMINATED life_cycle_state 和 SUCCESSFUL result_state 结束，则该运行被视为已成功完成。 如果在创建、重置或更新作业时未指定该列表，则该列表为空，并且不发送通知。 最多可为 on_success 属性指定 3 个目标。
on_failure	Webhook 的数组	运行未成功完成时要向其发送通知的可选系统目标列表。 如果运行在结束时有 INTERNAL_ERROR life_cycle_state，或者有 SKIPPED、FAILED 或 TIMED_OUT result_state，则该运行会被视为未成功完成。 如果在创建、重置或更新作业时未指定此项，则列表为空，并且不发送通知。 最多可为 on_failure 属性指定 3 个目标。
on_duration_warning_threshold_exceeded	Webhook 的数组	当运行持续时间超过 health 字段中为 RUN_DURATION_SECONDS 指标指定的阈值时，要向其发送通知的可选系统目标列表。 最多可为 on_duration_warning_threshold_exceeded 属性指定 3 个目标。

JobNotificationSettings

字段名称	类型	说明
no_alert_for_skipped_runs	BOOL	如果为 true，则在该运行被跳过的情况下不会向 on_failure 中指定的收件人发送通知。
no_alert_for_canceled_runs	BOOL	如果为 true，则在该运行被取消的情况下不会向 on_failure 中指定的收件人发送通知。
alert_on_last_attempt	BOOL	如果为 true，则不向 on_start 中指定的收件人发送重试运行的通知，直到最后一次重试运行时才向 on_failure 中指定的收件人发送通知。

JobSettings

作业的设置。 可以使用 resetJob 方法来更新这些设置。

字段名称	类型	说明
existing_cluster_id 或 new_cluster	STRING 或 NewCluster	如果是 existing_cluster_id，则该项是将用于此作业的所有运行的现有群集的 ID。 在现有群集上运行作业时，如果该群集停止响应，则可能需要手动重启该群集。 建议在新群集上运行作业，以获得更高的可靠性。 如果是 new_cluster，则该项是将为每个运行创建的群集的说明。 如果指定 PipelineTask，那么此字段可为空。
notebook_task 或 spark_jar_task 或 spark_python_task 或 spark_submit_task 或 pipeline_task 或 run_job_task	NotebookTask 或 SparkJarTask 或 SparkPythonTask 或 SparkSubmitTask 或 PipelineTask 或 RunJobTask	如果是 notebook_task，则表明此作业应该运行笔记本。 此字段不能与 spark_jar_task 一起指定。 如果是 spark_jar_task，则表明此作业应该运行 JAR。 如果是 spark_python_task，则表明此作业应该运行 Python 文件。 如果是 spark_submit_task，则表明此作业应通过 spark submit 脚本启动。 如果是 pipeline_task，则表明此作业应该运行增量实时表管道。 如果是 run_job_task，则表明此作业应运行另一个作业。
name	STRING	可选的作业名称。 默认值是 Untitled。
libraries	一个由库构成的数组	可选的库列表，这些库会安装在将要执行该作业的群集上。 默认值为空列表。
email_notifications	JobEmailNotifications	可选的一组电子邮件地址，在此作业的运行开始或完成时，以及在删除此作业时，这些电子邮件地址将会收到通知。 默认行为是不发送任何电子邮件。
webhook_notifications	WebhookNotifications	一组可选的系统目标，用于在此作业的运行开始、完成或失败时发送通知。
notification_settings	JobNotificationSettings	向此作业的每个 email_notifications 和 webhook_notifications 发送通知时使用的可选通知设置。
timeout_seconds	INT32	可选的超时设置，应用于此作业的每个运行。 默认行为是没有任何超时。
max_retries	INT32	对未成功的运行进行重试的最大次数，可选。 如果运行在完成时其以下状态为 FAILED，则会被视为未成功：result_state 或 INTERNAL_ERROR life_cycle_state。 值 -1 表示要无限次重试，而值 0 则表示从不重试。 默认行为是从不重试。
min_retry_interval_millis	INT32	可选的最小时间间隔（介于两次尝试之间），以毫秒为单位。 默认行为是立即重试未成功的运行。
retry_on_timeout	BOOL	一个可选的策略，用于指定在作业超时是否重试该作业。默认行为是在超时发生时不重试。
schedule	CronSchedule	此作业的可选定期计划。 默认行为是该作业将只在通过以下方式被触发时运行：在作业 UI 中单击“立即运行”，或将 API 请求发送到 runNow。
max_concurrent_runs	INT32	允许的作业最大并发运行数，可选。 如果希望能够以并发方式执行同一作业的多个运行，请设置此值。 设置此值适用于这样的情形：例如，如果你按计划频繁触发作业并希望允许连续的运行彼此重叠，或者，如果你希望触发多个在输入参数方面有区别的运行。 此设置只影响新的运行。 例如，假定作业的并发数为 4，并且存在 4 个并发的活动运行。 那么，将该并发数设置为 3 则不会终止任何活动的运行。 但是，从此之后，除非活动的运行少于 3 个，否则将会跳过新的运行。 此值不能超过 1000。 将此值设置为 0 会导致跳过所有新的运行。 默认行为是只允许 1 个并发运行。
health	JobsHealthRules	为作业定义的一组可选运行状况规则。

JobTask

字段名称	类型	说明
notebook_task 或 spark_jar_task 或 spark_python_task 或 spark_submit_task 或 pipeline_task 或 run_job_task	NotebookTask 或 SparkJarTask 或 SparkPythonTask 或 SparkSubmitTask 或 PipelineTask 或 RunJobTask	如果是 notebook_task，则表明此作业应该运行笔记本。 此字段不能与 spark_jar_task 一起指定。 如果是 spark_jar_task，则表明此作业应该运行 JAR。 如果是 spark_python_task，则表明此作业应该运行 Python 文件。 如果是 spark_submit_task，则表明此作业应通过 spark submit 脚本启动。 如果是 pipeline_task，则表明此作业应该运行增量实时表管道。 如果是 run_job_task，则表明此作业应运行另一个作业。

JobsHealthRule

字段名称	类型	描述
metric	STRING	指定要针对特定运行状况规则评估的运行状况指标。 有效值为：RUN_DURATION_SECONDS。
operator	STRING	指定用于将运行状况指标值与指定阈值进行比较的运算符。 有效值为：GREATER_THAN。
value	INT32	指定运行状况指标为符合运行状况规则而应满足的阈值。

JobsHealthRules

字段名称	类型	描述
rules	JobsHealthRule 的数组	可为作业定义的一组可选运行状况规则。

库

字段名称	类型	说明
jar 或 egg 或 whl 或 pypi 或 maven 或 cran	STRING、STRING、STRING、PythonPyPiLibrary、MavenLibrary 或 RCranLibrary	如果是 jar，则为要安装的 JAR 的 URI。 支持 DBFS 和 ADLS (abfss) URI。 例如：{ "jar": "dbfs:/mnt/databricks/library.jar" } 或 { "jar": "abfss://<container-path>/library.jar" }。 如果使用的是 ADLS，请确保群集对库具有读取访问权限。 如果是 egg，则为要安装的 egg 的 URI。 支持 DBFS 和 ADLS URI。 例如：{ "egg": "dbfs:/my/egg" } 或 { "egg": "abfss://<container-path>/egg" }。 如果 whl，则为要安装的 wheel 或已压缩 wheels 的 URI。 支持 DBFS 和 ADLS URI。 例如：{ "whl": "dbfs:/my/whl" } 或 { "whl": "abfss://<container-path>/whl" }。 如果使用的是 ADLS，请确保群集对库具有读取访问权限。 另外，wheel 文件名需要使用正确的约定。 如果要安装压缩的 wheels，文件名后缀应为 .wheelhouse.zip。 如果是 pypi，则为要安装的 PyPI 库的规范。 指定 repo 字段是可选的，如果未指定，则使用默认的 pip 索引。 例如： { "package": "simplejson", "repo": "https://my-repo.com" } 如果是 maven，则为要安装的 Maven 库的规范。 例如： { "coordinates": "org.jsoup:jsoup:1.7.2" } 如果是 cran，则为要安装的 CRAN 库的规范。

MavenLibrary

字段名称	类型	说明
coordinates	STRING	Gradle 样式的 Maven 坐标。 例如：org.jsoup:jsoup:1.7.2。 此字段为必需字段。
repo	STRING	要从中安装 Maven 包的 Maven 存储库。 如果省略此项，则同时搜索 Maven 中央存储库和 Spark 包。
exclusions	一个由 STRING 构成的数组	要排除的依赖项的列表。 例如：["slf4j:slf4j", "*:hadoop-client"]。 Maven 依赖项排除：https://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html。

NewCluster

字段名称	类型	说明
num_workers 或 autoscale	INT32 或 AutoScale	如果是 num_workers，则此项为此群集应该具有的工作器节点数。 一个群集有一个 Spark 驱动程序和 num_workers 个执行程序用于总共 (num_workers + 1) 个 Spark 节点。 注意：在读取群集的属性时，此字段反映的是所需的工作器数，而不是当前实际的工作器数。 例如，如果将群集的大小从 5 个工作器调整到 10 个工作器，此字段将会立即更新，以反映 10 个工作器的目标大小，而 spark_info 中列出的工作器会随着新节点的预配，逐渐从 5 个增加到 10 个。 如果是 autoscale，则会需要参数，以便根据负载自动纵向扩展或缩减群集。
spark_version	STRING	群集的 Spark 版本。 可以通过使用 GET 2.0/clusters/spark-versions 调用来检索可用 Spark 版本的列表。 此字段为必需字段。
spark_conf	SparkConfPair	一个对象，其中包含一组可选的由用户指定的 Spark 配置键值对。 你也可以分别通过以下属性，将额外 JVM 选项的字符串传入到驱动程序和执行程序： spark.driver.extraJavaOptions 和 spark.executor.extraJavaOptions。 示例 Spark 配置： {"spark.speculation": true, "spark.streaming.ui.retainedBatches": 5} 或 {"spark.driver.extraJavaOptions": "-verbose:gc -XX:+PrintGCDetails"}
node_type_id	STRING	此字段通过单个值对提供给此群集中的每个 Spark 节点的资源进行编码。 例如，可以针对内存密集型或计算密集型的工作负载来预配和优化 Spark 节点。通过使用 GET 2.0/clusters/list-node-types 调用可以检索可用节点类型的列表。 此字段、instance_pool_id 字段或指定节点类型 ID 或实例池 ID 的群集策略是必需的。
driver_node_type_id	STRING	Spark 驱动程序的节点类型。 此字段为可选；如果未设置，驱动程序节点类型会被设置为与上面定义的 node_type_id 相同的值。
custom_tags	ClusterTag	一个对象，其中包含群集资源的一组标记。 Databricks 会使用这些标记以及 default_tags 来标记所有的群集资源（如 VM）。 注意： * 旧版节点类型（如计算优化和内存优化）不支持标记 * Databricks 最多允许 45 个自定义标记
cluster_log_conf	ClusterLogConf	用于将 Spark 日志传递到长期存储目标的配置。 对于一个群集，只能指定一个目标。 如果提供该配置，则会每隔 5 mins 向目标发送一次日志。 驱动程序日志的目标是 <destination>/<cluster-id>/driver，而执行程序日志的目标是 <destination>/<cluster-id>/executor。
init_scripts	一个由 InitScriptInfo 构成的数组	用于存储初始化脚本的配置。 可以指定任意数量的脚本。 这些脚本会按照所提供的顺序依次执行。 如果指定了 cluster_log_conf，初始化脚本日志将会发送到 <destination>/<cluster-id>/init_scripts。
spark_env_vars	SparkEnvPair	一个对象，其中包含一组可选的由用户指定的环境变量键值对。 在启动驱动程序和工作器时，(X,Y) 形式的键值对会按原样导出（即 export X='Y'）。 若要额外指定一组 SPARK_DAEMON_JAVA_OPTS，建议将其追加到 $SPARK_DAEMON_JAVA_OPTS，如以下示例中所示。 这样就确保了还会包含所有默认的 databricks 托管环境变量。 Spark 环境变量示例： {"SPARK_WORKER_MEMORY": "28000m", "SPARK_LOCAL_DIRS": "/local_disk0"} 或 {"SPARK_DAEMON_JAVA_OPTS": "$SPARK_DAEMON_JAVA_OPTS -Dspark.shuffle.service.enabled=true"}
enable_elastic_disk	BOOL	自动缩放本地存储：启用后，此群集在其 Spark 工作器磁盘空间不足时会动态获取更多磁盘空间。 有关详细信息，请参阅启用自动缩放本地存储。
driver_instance_pool_id	STRING	要用于驱动程序节点的实例池的可选 ID。 另外还必须指定 instance_pool_id。 有关详细信息，请参阅实例池 API。
instance_pool_id	STRING	要用于群集节点的实例池的可选 ID。 如果 driver_instance_pool_id 存在， 则 instance_pool_id 仅用于工作器节点。 否则，它将同时用于驱动程序节点和工作器节点。 有关详细信息，请参阅实例池 API。

NotebookOutput

字段名称	类型	说明
result	STRING	传递到 dbutils.notebook.exit() 的值。 Azure Databricks 将此 API 限制为返回该值的前 1 MB。 若要返回更大的结果，你的作业可以将结果存储在云存储服务中。 如果从未调用 dbutils.notebook.exit()，此字段将不会存在。
truncated	BOOLEAN	结果是否已截断。

NotebookTask

所有输出单元均受大小 8MB 的约束。 如果单元的输出具有更大的大小，该运行的剩余部分将会被取消，并且该运行将会被标记为失败。 在这种情况下，可能还会缺少其他单元中的一些内容输出。

如果需要帮助查找超出限制的单元，请针对通用群集运行该笔记本，并使用这项笔记本自动保存技术。

字段名称	类型	说明
notebook_path	STRING	要在 Azure Databricks 工作区中运行的笔记本的绝对路径。 此路径必须以斜杠开头。 此字段为必需字段。
revision_timestamp	LONG	笔记本的修订的时间戳。
base_parameters	ParamPair 的映射	要用于此作业每个运行的基参数。 如果该运行由指定了参数的 run-now 调用启动，将会合并这两个参数映射。 如果在 base_parameters 和 run-now 中指定了相同密钥，将会使用来自 run-now 的值。 使用将有关作业运行的上下文传递到作业任务中来设置包含作业运行相关信息的参数。 如果笔记本采用未在作业的 base_parameters 或 run-now 重写参数中指定的参数，则将会使用笔记本中的默认值。 请使用 dbutils.widgets.get 来检索笔记本中的这些参数。

ParamPair

基于名称的参数，用于运行笔记本任务的作业。

类型	描述
STRING	参数名称。 传递到 dbutils.widgets.get 以检索值。
STRING	参数值。

PipelineTask

字段名称	类型	说明
pipeline_id	STRING	要执行的增量实时表管道任务的全名。

PythonPyPiLibrary

字段名称	类型	说明
package	STRING	要安装的 PyPI 包的名称。 另外还支持可选的确切版本规范。 示例：simplejson 和 simplejson==3.8.0。 此字段为必需字段。
repo	STRING	可在其中找到该包的存储库。 如果此项未指定，则使用默认的 pip 索引。

RCranLibrary

字段名称	类型	说明
package	STRING	要安装的 CRAN 包的名称。 此字段为必需字段。
repo	STRING	可在其中找到该包的存储库。 如果此项未指定，则使用默认的 CRAN 存储库。

运行

有关运行的所有信息（其输出除外）。 可以使用 getRunOutput 方法单独检索输出。

字段名称	类型	说明
job_id	INT64	包含此运行的作业的规范标识符。
run_id	INT64	该运行的规范标识符。 此 ID 在所有作业的所有运行中都是唯一的。
creator_user_name	STRING	创建者用户名。 如果已将该用户删除，响应中将不会包含此字段。
number_in_job	INT64	此运行在该作业的所有运行中的序列号。 此值从 1 开始。
original_attempt_run_id	INT64	如果此运行是对之前某次运行尝试的重试，则此字段会包含原始尝试的 run_id；否则此字段与本次运行的 run_id 相同。
state	RunState	运行的结果和生命周期状态。
schedule	CronSchedule	触发此运行的 cron 计划（如果此运行已由定期计划程序触发）。
task	JobTask	由该运行执行的任务（如果有）。
cluster_spec	ClusterSpec	创建此运行时作业的群集规范的快照。
cluster_instance	ClusterInstance	用于此运行的群集。 如果将该运行指定为使用新群集，则在作业服务已为该运行请求群集后，将会设置此字段。
overriding_parameters	RunParameters	用于此运行的参数。
start_time	INT64	启动此运行的时间，以epoch 毫秒表示（自 UTC 1970 年 1 月 1 日起的毫秒数）。 此时间可能不是作业任务开始执行的时间，例如，如果该作业已计划在新群集上运行，则此时间是发出群集创建调用的时间。
setup_duration	INT64	设置该群集所花费的时间（以毫秒为单位）。 对于在新群集上运行的运行，此时间是群集创建时间，对于在现有群集上运行的运行，此时间应该很短。
execution_duration	INT64	执行 JAR 或笔记本中的命令（直到这些命令已完成、失败、超时、被取消或遇到意外错误）所花费的时间（以毫秒为单位）。
cleanup_duration	INT64	终止该群集并清理任何关联项目所花费的时间（以毫秒为单位）。 该运行的总持续时间为 setup_duration、execution_duration 以及 cleanup_duration 之和。
end_time	INT64	此运行结束的时间，以 epoch 毫秒表示（自 UTC 1970/1/1 起的毫秒数）。 如果作业仍在运行，则此字段将设置为 0。
trigger	TriggerType	触发此运行的触发器类型。
run_name	STRING	可选的作业名称。 默认值是 Untitled。 允许的最大长度为采用 UTF-8 编码的 4096 个字节。
run_page_url	STRING	运行的详细信息页的 URL。
run_type	STRING	运行的类型。 * JOB_RUN - 正常的作业运行。 使用立即运行创建的运行。 * WORKFLOW_RUN - 工作流运行。 使用 dbutils.notebook.run 创建的运行。 * SUBMIT_RUN - 提交运行。 使用立即运行创建的运行。
attempt_number	INT32	此运行尝试对触发的作业运行的序列号。 运行的初始尝试的 attempt_number 为 0。 如果初始运行尝试失败，并且作业有重试策略 (max_retries> 0)，后续运行将以原始尝试的 ID 的 original_attempt_run_id 和递增 attempt_number 来创建。 运行在成功完成前会一直重试，并且最大 attempt_number 与作业的 max_retries 值相同。

RunJobTask

字段名称	类型	描述
job_id	INT32	要运行的作业的唯一标识符。 此字段为必填字段。

RunLifeCycleState

运行的生命周期状态。 允许的状态转换为：

• QUEUED ->PENDING
• PENDING ->RUNNING ->TERMINATING ->TERMINATED
• PENDING ->SKIPPED
• PENDING ->INTERNAL_ERROR
• RUNNING ->INTERNAL_ERROR
• TERMINATING ->INTERNAL_ERROR

状态	说明
QUEUED	运行已触发但正在排队，因为它达到了以下限制之一： * 工作区中的最大并发活动运行数。 * 工作区中的最大并发 Run Job 任务运行数。 * 作业的最大并发运行数。 作业或运行必须先启用排队才能达到此状态。
PENDING	已触发该运行。 如果已达到该作业的已配置最大并发运行数，则运行会立即转换为“SKIPPED”状态，而不准备任何资源。 否则就会进行群集准备和执行。
RUNNING	正在执行此运行的任务。
TERMINATING	此运行的任务已经完成，正在清理群集和执行上下文。
TERMINATED	此运行的任务已经完成，已经清理了群集和执行上下文。 此状态为最终状态。
SKIPPED	已中止此运行，因为同一作业以前的运行已处于活动状态。 此状态为最终状态。
INTERNAL_ERROR	一个异常状态，指示作业服务中存在故障（如长时间的网络故障）。 如果新群集上的运行以 INTERNAL_ERROR 状态结束，作业服务会尽快终止该群集。 此状态为最终状态。

RunParameters

适用于此运行的参数。 在 run-now 请求中，只应根据作业任务类型的不同指定 jar_params、python_params 或 notebook_params 之一。 具有 Spark JAR 任务或 Python 任务的作业采用基于位置的参数的列表，而具有笔记本任务的作业则采用键值映射。

字段名称	类型	说明
jar_params	一个由 STRING 构成的数组	具有 Spark JAR 任务的作业的参数的列表，例如 "jar_params": ["john doe", "35"]。 这些参数将用于调用 Spark JAR 任务中指定的 main 类的 main 函数。 如果未在调用 run-now 时指定，该项将默认为空列表。 jar_params 不能与 notebook_params 一起指定。 此字段的 JSON 表示形式（即 {"jar_params":["john doe","35"]}）不能超过 10,000 字节。 使用将有关作业运行的上下文传递到作业任务中来设置包含作业运行相关信息的参数。
notebook_params	ParamPair 的映射	具有笔记本任务的作业的从键到值的映射，例如 "notebook_params": {"name": "john doe", "age": "35"}。 该映射会传递到笔记本，并且可通过 dbutils.widgets.get 函数访问。 如果未在调用 run-now 时指定，已触发的运行会使用该作业的基参数。 notebook_params 不能与 jar_params 一起指定。 使用将有关作业运行的上下文传递到作业任务中来设置包含作业运行相关信息的参数。 此字段的 JSON 表示形式（即 {"notebook_params":{"name":"john doe","age":"35"}}）不能超过 10,000 字节。
python_params	一个由 STRING 构成的数组	具有 Python 任务的作业的参数列表，例如 "python_params": ["john doe", "35"]。 这些参数会作为命令行参数传递到 Python 文件。 如果在调用 run-now 时指定，则此项会覆盖作业设置中指定的参数。 此字段的 JSON 表示形式（即 {"python_params":["john doe","35"]}）不能超过 10,000 字节。 使用将有关作业运行的上下文传递到作业任务中来设置包含作业运行相关信息的参数。 > [!IMPORTANT] >> 这些参数只接受拉丁字符（ASCII 字符集）。 > 使用非 ASCII 字符将会返回错误。 例如，中文、日文汉字和表情符号 > 都属于无效的非 ASCII 字符。
spark_submit_params	一个由 STRING 构成的数组	具有“Spark 提交”任务的作业的参数列表，例如 "spark_submit_params": ["--class", "org.apache.spark.examples.SparkPi"]。 这些参数会作为命令行参数传递到 spark-submit 脚本。 如果在调用 run-now 时指定，则此项会覆盖作业设置中指定的参数。 此字段的 JSON 表示形式（即 {"python_params":["john doe","35"]}）不能超过 10,000 字节。 使用将有关作业运行的上下文传递到作业任务中来设置包含作业运行相关信息的参数。 > [!IMPORTANT] >> 这些参数只接受拉丁字符（ASCII 字符集）。 > 使用非 ASCII 字符将会返回错误。 例如，中文、日文汉字和表情符号 > 都属于无效的非 ASCII 字符。

RunResultState

运行的结果状态。

• 如果 life_cycle_state = TERMINATED：在该运行有任务的情况下，一定会提供结果，并且该状态指示任务的结果。
• 如果 life_cycle_state = PENDING、RUNNING 或 SKIPPED，则不会提供结果状态。
• 如果 life_cycle_state = TERMINATING 或 lifecyclestate = INTERNAL_ERROR：在该运行有任务并已成功启动该任务的情况下，将会提供结果状态。

结果状态在提供之后不会再改变。

状态	说明
SUCCESS	已成功完成任务。
FAILED	任务已完成，但有错误。
TIMEDOUT	该运行在达到超时后已停止。
CANCELED	该运行已应用户请求而取消。

RunState

字段名称	类型	说明
life_cycle_state	RunLifeCycleState	运行在运行生命周期中当前所处位置的说明。 此字段在响应中始终可用。
result_state	RunResultState	运行的结果状态。 如果此字段不可用，响应将不会包含此字段。 有关 result_state 可用性的详细信息，请参阅 RunResultState。
user_cancelled_or_timedout	BOOLEAN	运行是由用户手动取消还是由于运行时超时而由计划程序取消。
state_message	STRING	当前状态的描述性消息。 此字段是非结构化的，且其确切格式随时可能发生变更。

SparkConfPair

Spark 配置键值对。

类型	描述
STRING	配置属性名称。
STRING	配置属性值。

SparkEnvPair

Spark 环境变量键值对。

类型	描述
STRING	环境变量名称。
STRING	环境变量值。

SparkJarTask

字段名称	类型	说明
jar_uri	STRING	自 2016 年 4 月起已弃用。 改为通过 libraries 字段提供 jar。 有关示例，请参阅创建。
main_class_name	STRING	类的全名，包含要执行的主要方法。 此类必须包含在作为库提供的 JAR 中。 该代码应使用 SparkContext.getOrCreate 来获取 Spark 上下文；否则，作业的运行将会失败。
parameters	一个由 STRING 构成的数组	传递给 main 方法的参数。 使用将有关作业运行的上下文传递到作业任务中来设置包含作业运行相关信息的参数。

SparkPythonTask

字段名称	类型	说明
python_file	STRING	要执行的 Python 文件的 URI。 支持 DBFS 路径。 此字段为必需字段。
parameters	一个由 STRING 构成的数组	传递到 Python 文件的命令行参数。 使用将有关作业运行的上下文传递到作业任务中来设置包含作业运行相关信息的参数。

SparkSubmitTask

例如，假定 JAR 上传到了 DBFS，则可通过设置以下参数来运行 SparkPi。

{
  "parameters": [
    "--class",
    "org.apache.spark.examples.SparkPi",
    "dbfs:/path/to/examples.jar",
    "10"
  ]
}

字段名称	类型	说明
parameters	一个由 STRING 构成的数组	传递到 spark-submit 的命令行参数。 使用将有关作业运行的上下文传递到作业任务中来设置包含作业运行相关信息的参数。

TriggerType

这些是可以触发运行的触发器的类型。

类型	说明
PERIODIC	定期触发运行的计划，如 cron 计划程序。
ONE_TIME	触发单个运行的一次性触发器。 这在你通过 UI 或 API 按需触发单个运行时发生。
RETRY	指示一个作为先前失败的运行的重试而被触发的运行。 如果在出现故障时请求重新运行作业，则会发生这种触发。

ViewItem

导出的内容采用 HTML 格式。 例如，如果要导出的视图是仪表板，则会为每个仪表板返回一个 HTML 字符串。

字段名称	类型	说明
content	STRING	视图的内容。
name	STRING	视图项的名称。 对于代码视图，该项为笔记本的名称。 对于仪表板视图，该项为仪表板的名称。
type	ViewType	视图项的类型。

ViewType

类型	说明
NOTEBOOK	笔记本视图项。
DASHBOARD	仪表板视图项。

ViewsToExport

要导出的视图：代码、所有仪表板，或全部。

类型	说明
CODE	笔记本的代码视图。
DASHBOARDS	笔记本的所有仪表板视图。
ALL	笔记本的所有视图。

Webhook

字段名称	类型	说明
id	STRING	引用系统通知目标的标识符。 此字段为必需字段。

WebhookNotifications

字段名称	类型	说明
on_start	Webhook 的数组	运行开始时要向其发送通知的可选系统目标列表。 如果在创建、重置或更新作业时未指定该列表，则该列表为空，并且不发送通知。 最多可为 on_start 属性指定 3 个目标。
on_success	Webhook 的数组	运行成功完成时要向其发送通知的可选系统目标列表。 如果运行以 TERMINATED life_cycle_state 和 SUCCESSFUL result_state 结束，则该运行被视为已成功完成。 如果在创建、重置或更新作业时未指定该列表，则该列表为空，并且不发送通知。 最多可为 on_success 属性指定 3 个目标。
on_failure	Webhook 的数组	运行未成功完成时要向其发送通知的可选系统目标列表。 如果运行在结束时有 INTERNAL_ERROR life_cycle_state 或 SKIPPED、FAILED 或 TIMED_OUT result_state。 如果在创建、重置或更新作业时未指定此项，则列表为空，并且不发送通知。 最多可为 on_failure 属性指定 3 个目标。
on_duration_warning_threshold_exceeded	Webhook 的数组	当运行持续时间超过 health 字段中为 RUN_DURATION_SECONDS 指标指定的阈值时，要向其发送通知的可选系统目标列表。 最多可为 on_duration_warning_threshold_exceeded 属性指定 3 个目标。

WorkspaceStorageInfo

工作区存储信息。

字段名称	类型	说明
destination	STRING	文件目标。 示例： /Users/someone@domain.com/init_script.sh