REST API 1.2

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

本文介绍 REST API 1.2。 REST API 最新版本以及 REST API 2.12.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:图像文件名。 类型:stringarray

对于 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。

方案可以是 filehttp
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