REST API 2.0

Databricks REST API 2.0 支持多种服务,这些服务用于管理 Azure Databricks 群集群集策略DBFS增量实时表全局初始化脚本IP 访问列表作业MLFlow 试验和模型权限SCIM 设置机密令牌工作区

本文概述了如何使用 REST API。 本文末尾列出了各个 API 参考、身份验证选项和示例的链接。

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

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

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

速率限制

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

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

分析输出

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

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

curl --netrc -X GET https://adb-1234567890123456.7.databricks.azure.cn/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 中使用引号将 URL 或查询字符串括起来。

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

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

使用 ?

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

使用 --get--data

curl --netrc --get \
https://adb-1234567890123456.7.databricks.azure.cn/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.databricks.azure.cn/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.databricks.azure.cn'

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.databricks.azure.cn'
$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

API