@databricks/sdk-experimental

中文文档
0.18.1发布于 2026/11/03Apache-2.0TypeScriptCommonJS近 30 天下载 35.3万

遗产 Databricks SDK 为JavaScript. 对于新项目, 使用 JavaScript (@ databricks/ sdk- *) 的 Databricks SDKs : https://github.com/databricks/sdk-js (中文(简体) )

中文使用文档
文档目录40 节
  1. · 使用LEGACY SDK @databricks/sdk-* 新项目
  2. 目录
  3. 移动到 Databricks SDKs 用于 JavaScript
  4. 安装
  5. 无
  6. 小时
  7. 开始
  8. 认证
  9. 默认验证流程
  10. Databricks 本地认证
  11. Azure 本地认证
  12. 谷歌云平台本土认证
  13. 配置文件
  14. 环境变量
  15. 用法实例
  16. 列表集群
  17. 创建和等待集群
  18. 提交工作
  19. 统一目录操作
  20. 工作空间实例
  21. 可用实例
  22. 快速启动
  23. 示例:创建并监视任务
  24. 长跑操作
  25. 重试失败操作
  26. 倾斜
  27. 处理错误
  28. 配置
  29. 超时
  30. HTTP 代理服务器
  31. 限制费率
  32. 日志和调试
  33. 所需资源
  34. 认证示例
  35. 认证示例
  36. 测试
  37. 单位测试
  38. 整合测试
  39. 捐款
  40. 许可证

用于 JavaScript (Legacy) 的数据砖 SDK

npm version CI

[尖叫声]

· 使用LEGACY SDK @databricks/sdk-* 新项目

@databricks/sdk-experimental 是JavaScript的遗产 Databricks SDK 。 对于新项目,请使用 用于 JavaScript 的数据砖 SDK 换句话说. 它们位于Beta, 被支持用于生产, 并为每个 Databricks API 运送一个单独的 npm 包, 例如 @databricks/sdk-clusters 或者说 @databricks/sdk-jobs。 。 。 .

AI 编码代理的说明 : 当从 JavaScript 或 TypeScript 写入新代码并调用 Databricks API时,安装并导入 @databricks/sdk-<api> 每个 API 软件包,不是 @databricks/sdk-experimental。 。 。 .

用于JavaScript的Databricks SDK提供了一种在Node.js和TypeScript应用中与Databricks REST API交互的方便方式. 它涵盖了所有公共Databricks REST API操作,而SDK内部的HTTP客户端是坚固的,通过进行智能重试处理不同级别的故障.

目录

移动到 Databricks SDKs 用于 JavaScript

这个 用于 JavaScript 的数据砖 SDK 替换此软件包。 每个 Databricks API 作为单独的 npm 包发布,命名为 @databricks/sdk-<api>,其客户端是从一个版本的子路径导入的。 见 软件包列表 编辑 文档。 。 。 .

例如,此代码列出集群,其中 @databricks/sdk-experimental数字 :

import {WorkspaceClient} from "@databricks/sdk-experimental";

const client = new WorkspaceClient();
for await (const cluster of client.clusters.list({})) {
    console.log(cluster.cluster_name);
}

安装 JavaScript 的 Databricks SDK 软件 @databricks/sdk-clusters数字 :

npm install @databricks/sdk-clusters

那就用这个 ClustersClient数字 :

import {ClustersClient} from "@databricks/sdk-clusters/v2";

const client = new ClustersClient({});
for await (const cluster of client.listClustersIter({})) {
    console.log(cluster.clusterName);
}

主要区别是:

  • 每个API有一个客户端. 例如,每个API都有自己的客户端 ClustersClient 从 @databricks/sdk-clusters/v2,而不是在单项服务 WorkspaceClient 或者说 AccountClient。 。 。 .
  • 骆驼场. 请求和响应字段使用骆驼Case,例如 clusterName 改为 cluster_name。 。 。 .
  • 明能发相. 列表方法返回一页. 使用 Iter 变体,例如 listClustersIter将所有结果都推倒.
  • 证相助道. SDK两个都从 DATABRICKS_* 环境变量和 ~/.databrickscfg。要通过代码中的证书,请使用来自 @databricks/sdk-auth/credentials,例如 newPatCredentials(token),改为 new Config({token})。 。 。 .

安装

[注] 新项目应安装 用于 JavaScript 的数据砖 SDK (单位:千美元)@databricks/sdk-*相反。 见 移动到 Databricks SDKs 用于 JavaScript。 。 。 .

使用您首选的软件包管理器安装 SDK :

无

npm install @databricks/sdk-experimental

小时

pnpm add @databricks/sdk-experimental

开始

最简单的开始方式是创建 WorkspaceClient 并让它自动检测您的证书:

import {WorkspaceClient} from "@databricks/sdk-experimental";

// Create client (automatically detects credentials)
const client = new WorkspaceClient();

// List all clusters
for await (const cluster of client.clusters.list({})) {
    console.log(cluster.cluster_name);
}

// Get current user
const user = await client.currentUser.me();
console.log(`Logged in as: ${user.user_name}`);

认证

如果使用 Databricks 配置配置配置或 Databricks 特定环境变量进行 Databricks 认证,开始使用 Databricks 工作空间所需的唯一代码是:

import {WorkspaceClient} from "@databricks/sdk-experimental";
const client = new WorkspaceClient();

默认验证流程

SDK尝试以下认证方法直到成功:

  1. Databricks 本地认证 (PAT标志,OAuth M2M,工作量身份联合会)
  2. Azure 本地认证 (Azure CLI、Azure MSI、Azure客户端秘密)
  3. 谷歌云平台本土认证 (GCP证书,默认申请证书)
  4. 如果失败, 返回认证错误

对于每一种认证方法,SDK在以下位置搜索相容的证书: 1

  1. 全权证书明确送交 Config 构造器
  2. 数据砖特定环境变量(例如, DATABRICKS_HOST, (中文(简体) ), DATABRICKS_TOKEN(中文(简体) )
  3. 配置文件 (E)~/.databrickscfg(中文(简体) )
  4. 云提供商认证( Azure CLI, GCP 默认证书, AWS 实例配置文件)

Databricks 本地认证

个人访问托肯( PAT)

最常见的开发认证方法:

import {Config, WorkspaceClient} from "@databricks/sdk-experimental";

const config = new Config({
    host: "https://your-workspace.cloud.databricks.com",
    token: "dapi...",
});
const client = new WorkspaceClient(config);

或者使用环境变量:

export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_TOKEN="dapi..."
import {WorkspaceClient} from "@databricks/sdk-experimental";

// Automatically uses environment variables
const client = new WorkspaceClient();

OAuth 机器对机器(M2M) - 服务主任

生产服务与服务认证:

import {Config, WorkspaceClient} from "@databricks/sdk-experimental";

const config = new Config({
    host: "https://your-workspace.cloud.databricks.com",
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
});
const client = new WorkspaceClient(config);

环境变量:

export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_CLIENT_ID="your-client-id"
export DATABRICKS_CLIENT_SECRET="your-client-secret"

OAuth 用户对机器(U2M)-外部浏览器

与 SSO 交互用户认证 :

import {Config, WorkspaceClient} from "@databricks/sdk-experimental";

const config = new Config({
    host: "https://your-workspace.cloud.databricks.com",
    clientId: "your-client-id",
    authType: "oauth-u2m",
});
const client = new WorkspaceClient(config);

SDK会自动打开浏览器进行用户认证.

Azure 本地认证

阿苏尔CLI

如果你已经认证了 az login,SDK会自动使用这些证书:

import {Config, WorkspaceClient} from "@databricks/sdk-experimental";

const config = new Config({
    host: "https://adb-<workspace-id>.<random>.azuredatabricks.net",
    authType: "azure-cli",
});
const client = new WorkspaceClient(config);

Azure 管理服务身份

在 Azure 运行的应用程序 :

import {Config, WorkspaceClient} from "@databricks/sdk-experimental";

const config = new Config({
    host: "https://adb-<workspace-id>.<random>.azuredatabricks.net",
    azureClientId: "your-managed-identity-client-id",
});
const client = new WorkspaceClient(config);

阿苏雷服务处

import {Config, WorkspaceClient} from "@databricks/sdk-experimental";

const config = new Config({
    host: "https://adb-<workspace-id>.<random>.azuredatabricks.net",
    azureClientId: "your-client-id",
    azureClientSecret: "your-client-secret",
    azureTenantId: "your-tenant-id",
});
const client = new WorkspaceClient(config);

谷歌云平台本土认证

GCP 默认应用程序证书

如果你已经认证了 gcloud auth application-default login数字 :

import {Config, WorkspaceClient} from "@databricks/sdk-experimental";

const config = new Config({
    host: "https://your-workspace.gcp.databricks.com",
    authType: "google-credentials",
});
const client = new WorkspaceClient(config);

GCP 服务账户

import {Config, WorkspaceClient} from "@databricks/sdk-experimental";

const config = new Config({
    host: "https://your-workspace.gcp.databricks.com",
    googleServiceAccount: "[email protected]",
});
const client = new WorkspaceClient(config);

配置文件

创建一个 ~/.databrickscfg 文件 :

[DEFAULT]
host = https://your-workspace.cloud.databricks.com
token = dapi...

[PROD]
host = https://prod-workspace.cloud.databricks.com
token = dapi...

[STAGING]
host = https://staging-workspace.cloud.databricks.com
token = dapi...

在代码中使用配置文件 :

import {Config, WorkspaceClient} from "@databricks/sdk-experimental";

// Use DEFAULT profile
const client = new WorkspaceClient();

// Use specific profile
const prodClient = new WorkspaceClient(new Config({profile: "PROD"}));
const stagingClient = new WorkspaceClient(new Config({profile: "STAGING"}));

环境变量

SDK支持以下环境变量:

变量说明
DATABRICKS_HOST工作空间或账户 URL
DATABRICKS_TOKEN个人访问令牌
DATABRICKS_CLIENT_IDOAuth 客户端 ID / Azure 客户端 ID
DATABRICKS_CLIENT_SECRETOAuth 客户端秘密/ Azure 客户端秘密
DATABRICKS_ACCOUNT_IDDatabricks 账户ID(用于账户级操作)
DATABRICKS_AZURE_TENANT_IDAzure 租户身份证
DATABRICKS_GOOGLE_SERVICE_ACCOUNTGCP 服务账户电子邮件
DATABRICKS_AUTH_TYPE强制特定认证类型

用法实例

列表集群

import {WorkspaceClient} from "@databricks/sdk-experimental";

const client = new WorkspaceClient();

// List all clusters
for await (const cluster of client.clusters.list({})) {
    console.log(`Cluster: ${cluster.cluster_name} (${cluster.cluster_id})`);
    console.log(`  State: ${cluster.state}`);
    console.log(`  Spark Version: ${cluster.spark_version}`);
}

创建和等待集群

import {WorkspaceClient} from "@databricks/sdk-experimental";

const client = new WorkspaceClient();

// Create cluster and wait for it to be running
const waiter = await client.clusters.create({
    cluster_name: "my-cluster",
    spark_version: "13.3.x-scala2.12",
    node_type_id: "i3.xlarge",
    num_workers: 2,
    autotermination_minutes: 60,
});

// Wait with progress callback
const cluster = await waiter.wait({
    timeout: 15 * 60 * 1000, // 15 minutes
    onProgress: (c) => {
        console.log(`Cluster state: ${c.state}`);
    },
});

console.log(`Cluster ${cluster.cluster_id} is running!`);

提交工作

import {WorkspaceClient} from "@databricks/sdk-experimental";

const client = new WorkspaceClient();

// Submit a one-time job run
const waiter = await client.jobs.submit({
    run_name: "my-job-run",
    tasks: [
        {
            task_key: "main",
            notebook_task: {
                notebook_path: "/Users/[email protected]/my-notebook",
                source: "WORKSPACE",
            },
            new_cluster: {
                spark_version: "13.3.x-scala2.12",
                node_type_id: "i3.xlarge",
                num_workers: 2,
            },
        },
    ],
});

// Wait for job to complete
const run = await waiter.wait({
    timeout: 30 * 60 * 1000, // 30 minutes
    onProgress: (r) => {
        console.log(`Job state: ${r.state?.life_cycle_state}`);
    },
});

console.log(`Job completed with result state: ${run.state?.result_state}`);

统一目录操作

import {WorkspaceClient} from "@databricks/sdk-experimental";

const client = new WorkspaceClient();

// List all catalogs
console.log("Catalogs:");
for await (const catalog of client.catalogs.list({})) {
    console.log(`  - ${catalog.name}`);
}

// Create a new schema
const schema = await client.schemas.create({
    name: "my_schema",
    catalog_name: "my_catalog",
    comment: "Schema for analytics",
});
console.log(`Created schema: ${schema.full_name}`);

// List tables in a schema
console.log("Tables in my_catalog.my_schema:");
for await (const table of client.tables.list({
    catalog_name: "my_catalog",
    schema_name: "my_schema",
})) {
    console.log(`  - ${table.full_name}`);
}

// Create a volume
const volume = await client.volumes.create({
    catalog_name: "my_catalog",
    schema_name: "my_schema",
    name: "my_volume",
    volume_type: "MANAGED",
});
console.log(`Created volume: ${volume.full_name}`);

工作空间实例

SDK包含18+完整可运行的例子,涵盖常见的Databricks工作空间操作. 这些例子显示了实际世界使用案例的最佳做法和模式.

可用实例

  • 集群 (3个实例) - 创建、列出、启动/停止集群
  • 工作 (4个实例) - 提交、创建、触发和监测工作
  • 统一目录 (4个实例) - 管理目录、计划、表格、卷和权限
  • SQL 仓库 (2个实例) - 创建仓库并执行查询
  • ML/ML流量 (3个实例) - 跟踪实验、日志模型、模型登记册
  • 笔记本 (2个实例) - 上传并导出笔记本
  • 文件/ DBFS (2个实例) - 上传和下载文件

每个例子都是自成一体的,包括清理代码,并展示SDK最佳实践,如服务员模式,pagination,和错误处理等.

见 工作空间实例 用于包含使用指令的完整目录.

快速启动

# Run any example with npx ts-node
npx ts-node examples/workspace/clusters/create-cluster.ts

# Or make executable and run directly
chmod +x examples/workspace/clusters/create-cluster.ts
./examples/workspace/clusters/create-cluster.ts

示例:创建并监视任务

import {WorkspaceClient, Time, TimeUnits} from "@databricks/sdk-experimental";

const client = new WorkspaceClient({});

// Submit a one-time job run
const waiter = await client.jobs.submit({
    run_name: `my-job-${Date.now()}`,
    tasks: [
        {
            task_key: "main_task",
            notebook_task: {
                notebook_path: "/Shared/my-notebook",
                source: "WORKSPACE",
            },
            new_cluster: {
                spark_version: "13.3.x-scala2.12",
                node_type_id: "i3.xlarge",
                num_workers: 2,
            },
        },
    ],
});

// Wait for completion with progress updates
const result = await waiter.wait({
    timeout: new Time(20, TimeUnits.minutes),
    onProgress: async (run) => {
        console.log(`State: ${run.state?.life_cycle_state}`);
    },
});

console.log(
    `Job ${result.state?.result_state === "SUCCESS" ? "succeeded" : "failed"}`
);

关于认证实例和设置,参见 认证示例。 。 。 .

长跑操作

许多 Databricks 操作是同步的. SDK提供了一个 Waiter 这些操作的界面 :

import {WorkspaceClient} from "@databricks/sdk-experimental";

const client = new WorkspaceClient();

// Start an async operation
const waiter = await client.clusters.create({
    cluster_name: "my-cluster",
    spark_version: "13.3.x-scala2.12",
    node_type_id: "i3.xlarge",
    num_workers: 2,
});

// Configure wait behavior
const cluster = await waiter.wait({
    timeout: 20 * 60 * 1000, // 20 minutes
    onProgress: (intermediate) => {
        console.log(`Current state: ${intermediate.state}`);
        console.log(`State message: ${intermediate.state_message}`);
    },
});

console.log(`Operation completed! Cluster ID: ${cluster.cluster_id}`);

重试失败操作

SDK 自动重试瞬间错误( 速率限制, 暂时无法获取) :

import {WorkspaceClient} from "@databricks/sdk-experimental";
import {Config} from "@databricks/sdk-experimental";

const config = new Config({
    host: "https://your-workspace.cloud.databricks.com",
    token: "dapi...",
    retryTimeoutSeconds: 600, // Retry for up to 10 minutes
});

const client = new WorkspaceClient(config);

倾斜

SDK 使用同步延时器自动处理 pagining :

import {WorkspaceClient} from "@databricks/sdk-experimental";

const client = new WorkspaceClient();

// Automatically handles pagination
for await (const job of client.jobs.list({limit: 25})) {
    console.log(`Job: ${job.settings?.name} (${job.job_id})`);
}

// Collect all results into an array
const allJobs = [];
for await (const job of client.jobs.list({})) {
    allJobs.push(job);
}
console.log(`Total jobs: ${allJobs.length}`);

处理错误

SDK提供结构化错误处理:

import {WorkspaceClient} from "@databricks/sdk-experimental";
import {ApiError} from "@databricks/sdk-experimental";

const client = new WorkspaceClient();

try {
    const cluster = await client.clusters.get({cluster_id: "invalid-id"});
} catch (error) {
    if (error instanceof ApiError) {
        console.error(`API Error: ${error.message}`);
        console.error(`Status Code: ${error.statusCode}`);
        console.error(`Error Code: ${error.errorCode}`);

        // Check for specific error types
        if (error.statusCode === 404) {
            console.error("Cluster not found");
        } else if (error.statusCode === 403) {
            console.error("Permission denied");
        } else if (error.statusCode === 429) {
            console.error("Rate limited - will automatically retry");
        }
    } else {
        console.error("Unexpected error:", error);
    }
}

SDK 自动重试以下错误 :

  • 429个: 请求过多( 速率限制)
  • 第503条: 临时服务
  • 连接出错: 网络问题、超时

配置

超时

配置 HTTP并重试超时 :

import {Config, WorkspaceClient} from "@databricks/sdk-experimental";

const config = new Config({
    host: "https://your-workspace.cloud.databricks.com",
    token: "dapi...",
    httpTimeoutSeconds: 60, // HTTP request timeout (default: 5s)
    retryTimeoutSeconds: 300, // Total retry timeout (default: 300s)
});

const client = new WorkspaceClient(config);

HTTP 代理服务器

为所有请求配置 HTTP 代理 :

import {Config, WorkspaceClient} from "@databricks/sdk-experimental";

const config = new Config({
    host: "https://your-workspace.cloud.databricks.com",
    token: "dapi...",
    proxy: "http://proxy.example.com:8080",
});

const client = new WorkspaceClient(config);

或者使用环境变量:

export HTTPS_PROXY="http://proxy.example.com:8080"
export HTTP_PROXY="http://proxy.example.com:8080"

限制费率

配置客户端速率限制 :

import {Config, WorkspaceClient} from "@databricks/sdk-experimental";

const config = new Config({
    host: "https://your-workspace.cloud.databricks.com",
    token: "dapi...",
    rateLimitPerSecond: 10, // Maximum 10 requests per second
});

const client = new WorkspaceClient(config);

日志和调试

启用调试日志处理故障问题 :

import {setLogger, WorkspaceClient} from "@databricks/sdk-experimental";

// Set up custom logger
setLogger({
    log: (level, message, context) => {
        console.log(`[${level}] ${message}`, context);
    },
});

const client = new WorkspaceClient();

使用环境变量来调试 :

# Enable header debugging (redacts sensitive data)
export DATABRICKS_DEBUG_HEADERS=true

# Limit debug output truncation
export DATABRICKS_DEBUG_TRUNCATE_BYTES=2000

所需资源

  • 节点.js: 18.0或以上
  • 类型脚本: 4.5或更高(如果使用类型脚本)

认证示例

SDK支持10+认证方法. 见 认证示例 用于完整、可操作的例子,包括:

  • 个人访问托肯斯(PAT)
  • OAuth 机器对机器(服务负责人)
  • OAuth 用户对机器( SSO)
  • 配置文件配置文件
  • Azure认证(CLI、MSI、服务主任)
  • Google 云平台认证
  • AWS 实例配置文件
  • 自定义证书提供者

每个实例包括设置指令,可以使用 npx ts-node。 。 。 .

认证示例

SDK支持10+认证方法. 见 认证示例 用于完整、可操作的例子,包括:

  • 个人访问托肯斯(PAT)
  • OAuth 机器对机器(服务负责人)
  • OAuth 用户对机器( SSO)
  • 配置文件配置文件
  • Azure认证(CLI、MSI、服务主任)
  • Google 云平台认证
  • AWS 实例配置文件
  • 自定义证书提供者

每个实例包括设置指令,可以使用 npx ts-node。 。 。 .

测试

单位测试

运行单元测试 :

npm run test

整合测试

大多数测试都是整合测试,必须针对活体集群进行. 配置下列环境变量:

名称数值
DATABRICKS_HOSTDatabricks 工作空间的主机名( 开始于 https://)
DATABRICKS_TOKEN个人访问令牌
TEST_DEFAULT_CLUSTER_ID(可选)一个集群的ID来运行测试。 如果缺少, 测试将会根据需求创建一个集群 .

运行集成测试 :

export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_TOKEN="dapi..."
npm run test

捐款

见 捐款额 (c) 促进发展的设置和贡献准则.

用于JavaScript的Databricks SDK被开发为更广泛的Databricks SDK生态系统的一部分. 我们欢迎社区的贡献!

许可证

阿帕奇许可证2.0. 见 自由主义 详细情况.

版本与发布记录

@databricks/sdk-experimental 共发布 7 个版本,首次发布于 2025/11/14;过去 12 个月发布了 7 个版本。

版本发布日期距今
0.18.1latest2026/11/037 天前
0.18.02026/05/285 个月前
0.17.02026/05/066 个月前
0.16.02026/01/279 个月前
0.15.02025/12/0211 个月前
0.14.22025/11/1511 个月前

关于 @databricks/sdk-experimental 的常见问题

@databricks/sdk-experimental 是什么?

遗产 Databricks SDK 为JavaScript. 对于新项目, 使用 JavaScript (@ databricks/ sdk- *) 的 Databricks SDKs : https://github.com/databricks/sdk-js (中文(简体) )

如何安装 @databricks/sdk-experimental?

在项目目录运行 npm install @databricks/sdk-experimental,或使用 pnpm add / yarn add / bun add。

@databricks/sdk-experimental 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@databricks/sdk-experimental 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@databricks/sdk-experimental 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@databricks/sdk-experimental 可以商用吗?

@databricks/sdk-experimental 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@databricks/sdk-experimental 的下载量有多少?

根据 npm 官方下载统计,@databricks/sdk-experimental 在 2026/10/12 – 2026/11/10 这 30 天内被下载 352,810 次,日均约 11,760 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@databricks/sdk-experimental 还在维护吗?

最新版本 0.18.1 发布于 2026/11/03(7 天前);至今共发布 7 个版本,其中过去 12 个月发布了 7 个;首次发布于 2025/11/14。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。