REST API 1.2

  • 项目

如果不使用 Web UI，可以通过 Databricks REST API 以编程方式访问 Azure Databricks。

本文介绍 REST API 1.2。 REST API 最新版本以及 REST API 2.1 和 2.0 也可用。

重要

重要

要访问 Databricks REST API，必须进行身份验证。

REST API 用例

  • 启动从现有生产系统或 Airflow 触发的 Apache Spark 作业。
  • 以编程方式在一天的固定时间启动某种大小的群集，并在夜间将其关闭。

API 类别

  • 执行上下文：创建可在其中调用 Spark 命令的唯一变量命名空间。
  • 命令执行：在特定的执行上下文中运行命令。

详细信息

  • 此 REST API 通过 HTTPS 运行。
  • 若要检索信息，请使用 HTTP GET。
  • 若要修改状态，请使用 HTTP POST。
  • 若要上传文件，请使用 multipart/form-data。 否则使用 application/json。
  • 响应内容类型为 JSON。
  • 使用基本身份验证对每个 API 调用用户进行身份验证。
  • 用户凭据经过 base64 编码，位于每个 API 调用的 HTTP 标头中。 例如，Authorization: Basic YWRtaW46YWRtaW4=。 如果使用 curl，也可将用户凭据存储在 .netrc 文件中。
  • 有关 Databricks REST API 的详细信息，请参阅 Databricks REST API 参考。

入门

  • 若要试用本文中的示例，请将 <databricks-instance> 替换为 Azure Databricks 部署的工作区 URL。
  • 以下示例使用 curl 和 文件。 可以使用所选编程语言的 HTTP 库来调整这些 curl 示例。

API 参考

获取群集列表

方法和路径：

GET /api/1.2/clusters/list

示例

请求：

curl --netrc --request GET \
  https://<databricks-instance>/api/1.2/clusters/list

响应：

[
  {
    "id": "1234-567890-span123",
    "name": "MyCluster",
    "status": "Terminated",
    "driverIp": "",
    "jdbcPort": 10000,
    "numWorkers":0
  },
  {
    "..."
  }
]

请求架构

无。

响应架构

一组对象，其中每个对象表示群集相关信息，如下所示：

字段
id

类型：string

群集的 ID。
name

类型：string

群集的名称。
status

类型：string

群集的状态。 下列其中一项：

* Error
* Pending
* Reconfiguring
* Restarting
* Running
* Terminated
* Terminating
* Unknown
driverIp

类型：string

驱动程序的 IP 地址。
jdbcPort

类型：number

JDBC 端口号。
numWorkers

类型：number

群集的工作进程数。

获取有关群集的信息

方法和路径：

GET /api/1.2/clusters/status

示例

请求：

curl --netrc --get \
  https://<databricks-instance>/api/1.2/clusters/status \
  --data clusterId=1234-567890-span123

响应：

{
  "id": "1234-567890-span123",
  "name": "MyCluster",
  "status": "Terminated",
  "driverIp": "",
  "jdbcPort": 10000,
  "numWorkers": 0
}

请求架构

字段
clusterId

类型：string

群集的 ID。

响应架构

一个表示群集相关信息的对象。

字段
id

类型：string

群集的 ID。
name

类型：string

群集的名称。
status

类型：string

群集的状态。 下列其中一项：

* Error
* Pending
* Reconfiguring
* Restarting
* Running
* Terminated
* Terminating
* Unknown
driverIp

类型：string

驱动程序的 IP 地址。
jdbcPort

类型：number

JDBC 端口号。
numWorkers

类型：number

群集的工作进程数。

重启群集

方法和路径：

POST /api/1.2/clusters/restart

示例

请求：

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/clusters/restart \
  --data clusterId=1234-567890-span123

响应：

{
  "id": "1234-567890-span123"
}

请求架构

字段
clusterId

类型：string

要重启的群集的 ID。

响应架构

字段
id

类型：string

群集的 ID。

创建执行上下文

方法和路径：

POST /api/1.2/contexts/create

示例

请求：

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/contexts/create \
  --data clusterId=1234-567890-span123 \
  --data language=sql

响应：

{
  "id": "1234567890123456789"
}

请求架构

字段
clusterId

类型：string

要为其创建上下文的群集的 ID。
clusterId

类型：string

上下文的语言。 下列其中一项：

* python
* scala
* sql

响应架构

字段
id

类型：string

执行上下文的 ID。

获取有关执行上下文的信息

方法和路径：

GET /api/1.2/contexts/status

示例

请求：

curl --netrc https://<databricks-instance>/api/1.2/contexts/status?clusterId=1234-567890-span123&contextId=1234567890123456789

响应：

{
  "id": "1234567890123456789",
  "status": "Running"
}

请求架构

字段
clusterId

类型：string

要获取其执行上下文信息的群集的 ID。
contextId

类型：string

执行上下文的 ID。

响应架构

字段
id

类型：string

执行上下文的 ID。
status

类型：string

执行上下文的状态。 下列其中一项：

* Error
* Pending
* Running

删除执行上下文

方法和路径：

POST /api/1.2/contexts/destroy

示例

请求：

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/contexts/destroy \
  --data clusterId=1234-567890-span123 \
  --data contextId=1234567890123456789

响应：

{
  "id": "1234567890123456789"
}

请求架构

字段
clusterId

类型：string

要销毁其执行上下文的群集的 ID。
contextId

类型：string

要销毁的执行上下文的 ID。

响应架构

字段
id

类型：string

执行上下文的 ID。

运行命令

方法和路径：

POST /api/1.2/commands/execute

示例

请求：

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/commands/execute \
  --header 'Content-Type: application/json' \
  --data @execute-command.json

execute-command.json:

{
   "clusterId": "1234-567890-span123",
   "contextId": "1234567890123456789",
   "language": "python",
   "command": "print('Hello, World!')"
}

响应：

{
  "id": "1234ab56-7890-1cde-234f-5abcdef67890"
}

请求架构

字段
clusterId

类型：string

要对其运行命令的群集的 ID。
contextId

类型：string

要在其中运行命令的执行上下文的 ID。
语言

类型：string

命令的语言。
command

类型：string

要运行的命令字符串。

指定 command 或
commandFile。
commandFile

类型：string

包含要运行的命令的文件的路径。

指定 commandFile 或
command。
options

类型：string

下游使用的值的可选映射。 例如 displayRowLimit 重写（用于测试）。

响应架构

字段
id

类型：string

命令的 ID。

获取有关命令的信息

方法和路径：

GET /api/1.2/commands/status

示例

请求：

curl --netrc --get \
  https://<databricks-instance>/api/1.2/commands/status \
  --data clusterId=1234-567890-span123 \
  --data contextId=1234567890123456789 \
  --data commandId=1234ab56-7890-1cde-234f-5abcdef67890

响应：

{
  "id": "1234ab56-7890-1cde-234f-5abcdef67890",
  "status": "Finished",
  "results": {
    "resultType": "text",
    "data": "Hello, World!"
  }
}

请求架构

字段
clusterId

类型：string

要获取其命令信息的群集的 ID。
contextId

类型：string

与命令关联的执行上下文的 ID。
commandId

类型：string

要获取其相关信息的命令的 ID。

响应架构

字段
id

类型：string

命令的 ID。
status

类型：string

命令的状态。 下列其中一项：

* Cancelled
* Cancelling
* Error
* Finished
* Queued
* Running
results

类型：object

命令的结果。

* resultType：结果的类型。 类型：string 以下类型之一：

* error
* image
* images
* table
* text

对于 error：

* cause：错误的原因。 类型：string

对于 image：

* fileName：图像文件名。 类型：string

对于 images：

* fileNames：图像文件名。 类型：string 的 array

对于 table：

* data：表数据。 类型：array of array of any

* schema：表架构。 类型：array of array of (string, any)

* truncated：如果返回部分结果，则为 true。 类型：true/false

* isJsonSchema：如果返回的是 JSON 架构而不是 Hive 类型的字符串表示形式，则为 true。 类型：true/false

对于 text：

* data：文本。 类型：string

取消命令

方法和路径：

POST/api/1.2/commands/cancel

示例

请求：

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/commands/cancel \
  --data clusterId=1234-567890-span123 \
  --data contextId=1234567890123456789 \
  --data commandId=1234ab56-7890-1cde-234f-5abcdef67890

响应：

{
  "id": "1234ab56-7890-1cde-234f-5abcdef67890"
}

请求架构

字段
clusterId

类型：string

与要取消的命令关联的群集的 ID。
contextId

类型：string

与要取消的命令关联的执行上下文的 ID。
commandId

类型：string

要取消的命令的 ID。

响应架构

字段
id

类型：string

命令的 ID。

获取某个群集的库列表

重要

此操作已弃用。 请改用库 API 中的群集状态操作。

方法和路径：

GET /api/1.2/libraries/list

示例

请求：

curl --netrc --get \
  https://<databricks-instance>/api/1.2/libraries/list \
  --data clusterId=1234-567890-span123

请求架构

字段
clusterId

类型：string

群集的 ID。

响应架构

一组对象，其中每个对象表示库相关信息，如下所示：

字段
name

类型：string

库的名称。
status

类型：string

库的状态。 下列其中一项：

* LibraryError
* LibraryLoaded
* LibraryPending

将库上传到群集

重要

此操作已弃用。 请改用库 API 中的安装操作。

方法和路径：

POST /api/1.2/libraries/upload

请求架构

字段
clusterId

类型：string

要将库上传到的群集的 ID。
name

类型：string

库的名称。
语言

类型：string

库的语言。
uri

类型：string

库的 URI。

方案可以是 file、http 或
https.

响应架构

有关上传的库的信息。

字段
语言

类型：string

库的语言。
uri

类型：string

库的 URI。

其他示例

下面的附加示例提供可用于 curl 的命令，也可使用所选编程语言的 HTTP 库进行调整。

创建执行上下文

按给定的编程语言在指定的群集上创建执行上下文：

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/contexts/create \
  --header 'Content-Type: application/json' \
  --data '{ "language": "scala", "clusterId": "1234-567890-span123" }'

获取有关执行上下文的信息：

curl --netrc --get \
  https://<databricks-instance>/api/1.2/contexts/status \
  --data 'clusterId=1234-567890-span123&contextId=1234567890123456789'

删除执行上下文：

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/contexts/destroy \
  --header 'Content-Type: application/json' \
  --data '{ "contextId": "1234567890123456789", "clusterId": "1234-567890-span123" }'

运行命令

已知限制：命令执行不支持 %run。

运行命令字符串：

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/commands/execute \
  --header 'Content-Type: application/json' \
  --data '{ "language": "scala", "clusterId": "1234-567890-span123", "contextId": "1234567890123456789", "command": "sc.parallelize(1 to 10).collect" }'

运行文件：

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/commands/execute \
  --header 'Content-Type: multipart/form-data' \
  --form language=python \
  --form clusterId=1234-567890-span123 \
  --form contextId=1234567890123456789 \
  --form command=@myfile.py

显示命令的状态和结果：

curl --netrc --get \
  https://<databricks-instance>/api/1.2/commands/status \
  --data 'clusterId=1234-567890-span123&contextId=1234567890123456789&commandId=1234ab56-7890-1cde-234f-5abcdef67890'

取消命令：

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/commands/cancel \
  --data 'clusterId=1234-567890-span123&contextId=1234567890123456789&commandId=1234ab56-7890-1cde-234f-5abcdef67890' \

上传和运行 Spark JAR

上传 JAR

使用 REST API（最新）上传 JAR 并将其附加到群集。

运行 JAR

  1. 创建执行上下文。

    curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/contexts/create \
  --data "language=scala&clusterId=1234-567890-span123"

    {
  "id": "1234567890123456789"
}

  2. 执行使用 JAR 的命令。

    curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/commands/execute \
  --data 'language=scala&clusterId=1234-567890-span123&contextId=1234567890123456789&command=println(com.databricks.apps.logs.chapter1.LogAnalyzer.processLogFile(sc,null,"dbfs:/somefile.log"))'

    {
  "id": "1234ab56-7890-1cde-234f-5abcdef67890"
}

  3. 检查命令的状态。 如果运行冗长的 Spark 作业，该命令可能不会立即返回。

    curl --netrc 'https://<databricks-instance>/api/1.2/commands/status?clusterId=1234-567890-span123&contextId=1234567890123456789&commandId=1234ab56-7890-1cde-234f-5abcdef67890'

    {
   "id": "1234ab56-7890-1cde-234f-5abcdef67890",
   "results": {
     "data": "Content Size Avg: 1234, Min: 1234, Max: 1234",
     "resultType": "text"
   },
   "status": "Finished"
}

    resultType 允许的值包括：

    • error
    • image
    • images
    • table
    • text