Databricks REST API 参考

Azure Databricks 有三个用于执行不同任务的 REST API:

  • 2.02.1,用于常规管理
  • 1.2,用于直接在 Azure Databricks 运行命令

有关所有 REST API 的最新版本,请参阅 REST API(最新)。 你也可以直接跳转到各版本的 REST API 主页:2.12.01.2

重要

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

  • 群集 API 2.0
  • 群集策略 API 2.0
  • Databricks SQL 终结点 API 2.0
  • Databricks SQL 查询和仪表板 API 2.0
  • Databricks SQL 查询历史记录 API 2.0
  • DBFS API 2.0
  • Delta Live Tables API 2.0
  • Git 凭据 API 2.0
  • 全局初始化脚本 API 2.0
  • 组 API 2.0
  • 实例池 API 2.0
  • IP 访问列表 API 2.0
  • 作业 API 2.12.0
  • 库 API 2.0
  • MLflow API 2.0
  • 权限 API 2.0
  • 存储库 API 2.0
  • SCIM API 2.0
  • 机密 API 2.0
  • 令牌 API 2.0
  • 令牌管理 API 2.0
  • 工作区 API 2.0
  • API 1.2

身份验证

若要了解如何使用个人访问令牌向 REST API 进行身份验证,请参阅使用 Azure Databricks 个人访问令牌进行身份验证

若要了解如何使用 Azure Active Directory 令牌向 REST API 进行身份验证,请参阅使用 Azure Active Directory 令牌进行身份验证。 有关示例,请参阅使用用户的 Azure AD 访问令牌使用服务主体的 AAD 访问令牌

有关 API 示例,请参阅 API 示例

速率限制

为了确保在繁重负载下服务质量很高,Databricks 对所有 REST API 调用强行实施了速率限制。 这些限制按每个终结点和每个工作区进行设置,目的是确保公平使用和高可用性。

超出速率限制的请求会返回 429 响应状态代码

分析输出

分析 JSON 输出的各个部分可能很有用。 Databricks 建议使用 实用工具 jq 来分析 JSON。 在 Linux 上可以通过jq安装 jq,在 macOS 上使用 Homebrew 通过 brew install jq 安装,或者在 Windows 上使用 Chocolatey 通过 choco install jq 安装。 有关 jq 的详细信息,请参阅 jq

此示例列出了指定工作区中可用群集的名称和 ID。 此示例使用 .netrc 文件

curl --netrc -X GET https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/clusters/list \
| jq '[ .clusters[] | { id: .cluster_id, name: .cluster_name } ]'
[
  {
    "id": "1234-567890-batch123",
    "name": "My Cluster 1"
  },
  {
    "id": "2345-678901-rigs234",
    "name": "My Cluster 2"
  }
]

兼容性

对同一 API 版本的响应不会从 JSON 输出删除任何字段。 但是,API 可能会向 JSON 输出添加新字段,而不会递增 API 版本。 编程工作流必须了解这些添加内容并忽略未知字段。

某些 STRING 字段(其中包含供 UI 使用的错误和描述性消息)未结构化,在编程工作流中请不要依赖这些字段的格式。

使用 curl 调用 Databricks REST API

curl 是一种用于向/从服务器传输数据的常用工具。 本部分具体介绍如何使用 curl 来调用 Databricks REST API。

使用查询字符串来调用 GET

虽然大多数 API 调用都要求指定 JSON 正文,对于 GET 调用,可以通过将其追加到 ? 之后并将 URL 放在括号中来指定查询字符串。 如果使用 curl,可以随查询字符串指定--get(或 -G)和 --data(或 -d);不需要将 URL 或查询字符串放在括号中。

在以下示例中,请将 adb-1234567890123456.7.azuredatabricks.net 替换为 Azure Databricks 部署的adb-1234567890123456.7.azuredatabricks.net。 应以 adb- 开头。 请勿使用已被弃用的以 <azure-region-name> 开头的区域 URL。 该 URL 可能不适用于新的工作区,可靠性更低,并且性能比每工作区 URL的低。

此示例会打印有关指定群集的信息。 此示例使用 .netrc 文件

使用 ?

curl --netrc 'https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/clusters/get?cluster_id=1234-567890-patch123'

使用 --get--data

curl --netrc --get \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/clusters/get \
--data cluster_id=1234-567890-batch123
{
  "cluster_id": "1234-567890-batch123",
  "driver": {
    "node_id": "123ab456789012345cd67e8e90123f45",
    "instance_id": "234ab456789012345cd67e8e90123f45",
    "start_timestamp": 1618448261567,
    "host_private_ip": "10.0.0.0",
    "private_ip": "10.0.0.0"
  },
  ...
}

此示例会列出 DBFS 根目录的内容。 此示例使用 .netrc 文件

curl --netrc --get \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/dbfs/list \
--data path=/
"files": [
  {
    "path": "/tmp",
    "is_dir": true,
    "file_size": 0,
    "modification_time": 1547078156000
  },
  {
    "path": "/my_file.txt",
    "is_dir": false,
    "file_size": 40,
    "modification_time": 1541374426000
  },
  ...
]

使用 Python 调用 Databricks REST API

requests 是一个用于在 Python 中发出 HTTP 请求的常用库。 此示例使用 requests 库列出有关指定 Azure Databricks 群集的信息。 此示例使用 .netrc 文件

import requests
import json

instance_id = 'adb-1234567890123456.7.azuredatabricks.net'

api_version = '/api/2.0'
api_command = '/clusters/get'
url = f"https://{instance_id}{api_version}{api_command}"

params = {
  'cluster_id': '1234-567890-batch123'
}

response = requests.get(
  url = url,
  params = params
)

print(json.dumps(json.loads(response.text), indent = 2))
{
  "cluster_id": "1234-567890-batch123",
  "driver": {
    ...
  },
  "spark_context_id": 1234567890123456789,
  ...
}

使用 PowerShell 调用 Databricks REST API

此示例在 PowerShell 中使用 Invoke-RestMethod cmdlet 来列出有关指定 Azure Databricks 群集的信息。

$Token = 'dapia1b2345678901c23456defa7bcde8fa9'
$ConvertedToken = $Token | ConvertTo-SecureString -AsPlainText -Force

$InstanceID = 'adb-1234567890123456.7.azuredatabricks.net'
$APIVersion = '/api/2.0'
$APICommand = '/clusters/get'
$Uri = "https://$InstanceID$APIVersion$APICommand"

$Body = @{
  'cluster_id' = '1234-567890-batch123'
}

$Response = Invoke-RestMethod `
  -Authentication Bearer `
  -Token $ConvertedToken `
  -Method Get `
  -Uri  $Uri `
  -Body $Body

Write-Output $Response
cluster_id       : 1234-567890-batch123
driver           : ...
spark_context_id : 1234567890123456789
...

Runtime 版本字符串

许多 API 调用都要求必须指定 Databricks Runtime 版本字符串。 此部分介绍了 Databricks REST API 中的版本字符串的结构。

<M>.<F>.x[-cpu][-esr][-gpu][-ml][-photon][-hls]-scala<scala-version>

其中

  • M:Databricks Runtime 主要版本
  • F:Databricks Runtime 功能版
  • cpu:CPU 版本(只包含 -ml
  • esr:外延支持
  • gpugpu
  • mlml
  • photonphoton
  • hlshls(已弃用)
  • scala-version:用于编译 Spark 的 Scala 的版本:2.10、2.11 或 2.12

例如:

  • 7.6.x-gpu-ml-scala2.12 表示用于机器学习的 Databricks Runtime 7.6,它启用了 GPU,并使用 Scala 版本 2.12 编译 Spark 版本 3.0.1
  • 6.4.x-esr-scala2.11 表示 Databricks Runtime 6.4 外延支持,它使用 Scala 版本 2.11 编译 Spark 版本 2.4.5

受支持的 Databricks Runtime 版本和支持计划以及不受支持的版本表将 Databricks Runtime 版本映射到运行时中包含的 Spark 版本。

可以通过调用运行时版本 API 获取可用 Azure Databricks 运行时版本字符串的列表。

Databricks Light

apache-spark.<M>.<F>.x-scala<scala-version>

其中

  • M:Apache Spark 主要版本
  • F:Apache Spark 功能版
  • scala-version:用于编译 Spark 的 Scala 的版本:2.10 或 2.11

例如,apache-spark-2.4.x-scala2.11