用于 JavaScript (Legacy) 的数据砖 SDK
[尖叫声]
· 使用LEGACY SDK
@databricks/sdk-*新项目
@databricks/sdk-experimental是JavaScript的遗产 Databricks SDK 。 对于新项目,请使用 用于 JavaScript 的数据砖 SDK 换句话说. 它们位于Beta, 被支持用于生产, 并为每个 Databricks API 运送一个单独的 npm 包, 例如@databricks/sdk-clusters或者说@databricks/sdk-jobs。 。 。 .
- ❌ 在生产环境中不要使用此软件包
- ⚠️ 断裂变化可随时发生
- ➡️ 要移动已存在的代码,请参阅 移动到 Databricks SDKs 用于 JavaScript
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尝试以下认证方法直到成功:
- Databricks 本地认证 (PAT标志,OAuth M2M,工作量身份联合会)
- Azure 本地认证 (Azure CLI、Azure MSI、Azure客户端秘密)
- 谷歌云平台本土认证 (GCP证书,默认申请证书)
- 如果失败, 返回认证错误
对于每一种认证方法,SDK在以下位置搜索相容的证书: 1
- 全权证书明确送交
Config构造器 - 数据砖特定环境变量(例如,
DATABRICKS_HOST, (中文(简体) ),DATABRICKS_TOKEN(中文(简体) ) - 配置文件 (E)
~/.databrickscfg(中文(简体) ) - 云提供商认证( 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_ID | OAuth 客户端 ID / Azure 客户端 ID |
DATABRICKS_CLIENT_SECRET | OAuth 客户端秘密/ Azure 客户端秘密 |
DATABRICKS_ACCOUNT_ID | Databricks 账户ID(用于账户级操作) |
DATABRICKS_AZURE_TENANT_ID | Azure 租户身份证 |
DATABRICKS_GOOGLE_SERVICE_ACCOUNT | GCP 服务账户电子邮件 |
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_HOST | Databricks 工作空间的主机名( 开始于 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. 见 自由主义 详细情况.