REST API 1.2

Databricks REST API允许以编程方式访问 Azure Databricks,而不是通过 Web UI。

本文介绍 REST API 1.2。 此外REST API最新版本以及 REST API 2.12.0。

重要

重要

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

REST API 用例

  • 启动从现有生产系统或工作流系统触发的 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 <databricks-instance> URL。
  • 以下示例使用 curl 和.netrc 文件。 可以使用选择的 curl 编程语言中的 HTTP 库来调整这些示例。

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。

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

方法和路径:

POST /api/1.2/contexts/status

示例

请求:

curl --netrc --get \
  https://<databricks-instance>/api/1.2/contexts/status \
  --data clusterId=1234-567890-span123 \
  --data 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

要运行的命令字符串。

指定命令或
commandFile
commandFile

类型:string

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

请指定 commandFile
命令
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
后果

类型:object

命令的结果。

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

* error
* image
* images
* table
* text

对于 error

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

对于 image

* fileName:映像文件名。 类型:string

对于 images

* fileNames:映像的文件名。 类型:stringarray

对于 table

* data:表数据。 类型: array of arrayany

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

* truncatedtrue 如果返回部分结果,则为。 类别 true/false

* isJsonSchematrue 如果返回 JSON 架构而不是 Hive 类型的字符串表示形式,则为。 类别 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

Upload库到群集

重要

此操作已弃用。 请 改为使用 库 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