# @deepnote/cloud 中文文档

规范地址：https://npmcn.com/package/%40deepnote/cloud/

版本：0\.4\.0
npm 元数据更新时间：2026-11-10T06:46:10.566Z
中文译文更新时间：2026-11-11T20:52:09.692Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40deepnote/cloud
原文对照：https://npmcn.com/package/%40deepnote/cloud/?lang=original
项目主页：https://github.com/deepnote/deepnote#readme
源码仓库：https://github.com/deepnote/deepnote

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：244 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.14\.0
- 运行依赖：3 个
- 首次发布：2026-08-13T11:30:15.272Z
- 最新版本发布：2026-11-10T06:46:10.398Z
- 近 30 天下载量：3385（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

深音云客户端运行 API

## 安装

```sh
npm install @deepnote/cloud
```

也可以使用：`pnpm add @deepnote/cloud`、`yarn add @deepnote/cloud`、`bun add @deepnote/cloud`

## README

# @deepnote/云

深 Note Cloud API的客户端(审查):创建笔记本,触发运行,进行投票完成, 获取其执行快照,并作为 Streamlit apps 发布已有的项目文件 .

用于 `deepnote run --cloud` (单位:千美元)`@deepnote/cli`和通过 `@deepnote/local-runner`。 。 。 .

一个 **应用** hTML、CSS和由Deepnote主持并在浏览器中运行的JavaScript。 A 类 **简化应用程序** 是一个运行在项目硬件上的 Python UI .

客户端接受ID和平面对象. 将笔记本内容映射到 `ProjectSpec` 当创建工程时.

## 安装

```bash
npm install @deepnote/cloud
```

## 使用量

```ts
import {
  triggerNotebookRun,
  pollRunUntilComplete,
  waitForRunSnapshot,
} from "@deepnote/cloud";

const started = await triggerNotebookRun(baseUrl, token, {
  notebookId,
  inputs,
  detachedRunStorageMode: "readonly",
});
const run = await pollRunUntilComplete(baseUrl, token, started.runId, {
  snapshotDelivery: "inline",
});
const { content: snapshotYaml } = await waitForRunSnapshot(baseUrl, token, run);
```

认证是 `Authorization: Bearer <token>`。终点: `POST {baseUrl}/v2/runs` 财务报告和审定财务报表 `GET {baseUrl}/v2/runs/{runId}`. 反应计划是允许的(`.passthrough()`因为API 正在预览中,其确切形状可能会漂移。 失败投出 `ApiError` (从) `@deepnote/database-integrations`) (中文(简体) ).

全注本运行默认脱去,不更新活版编辑器中的输出. `detachedRunStorageMode: "readonly"` 防止写作持续的项目存储; 它不隔离数据库,集成,外部API,或笔记本访问的其他系统. Block-scoped 运行使用活模式, 因为 API 不支持 `blockIds` 离散的运行 因此无法使用 `detachedRunStorageMode`。 。 。 .

## API 参考

| 导出 | 说明 |
| --- | --- |
| `createProject(baseUrl, token, spec, opts?)` | 创建项目、 笔记本和块; 返回指定的 IDs Deepnote 。 见下文. |
| `triggerNotebookRun(baseUrl, token, body)` | `POST /v2/runs` 开始运行一个已有的笔记本。 返回常态运行 . |
| `getRun(baseUrl, token, runId, options?)` | `GET /v2/runs/{runId}` - 获取运行当前状态. |
| `pollRunUntilComplete(baseUrl, token, runId, opts?)` | 直到运行达到终端状态。 重复短暂的失败; 执行最后期限 . |
| `fetchSnapshotContent(run, options)` | 返回运行的快照 YAML, 从内置内容或一个 `downloadUrl`。 。 。 . `null` 如果它没有. |
| `waitForRunSnapshot(baseUrl, token, run, opts?)` | 还原 a `SettledRunSnapshot` 在边界定居后 内容 `content` 实值 `null` ; 无法读取的快照. |
| `describeRunError(run)` | 如果 API 提供一条, 运行失败的可读信息 . |
| `isTerminalStatus` 编号 : `isSuccessStatus` 编号 : `isFailedStatus` | 状态分类员. 未知状态被作为非地铁处理,因此漂移的API不能被挂起. |
| `RUN_STATUSES`, (中文(简体) ), `RunStatus` | 已知运行状态 . |
| `RunTimeoutError` | 掷出时 `pollRunUntilComplete` 超过期限。 载着 `runId` 跑步可能还在进行中. |
| `NormalizedRun`, (中文(简体) ), `TriggerRunBody`, (中文(简体) ), `GetRunOptions`, (中文(简体) ), `PollOptions`, (中文(简体) ), `FetchSnapshotOptions`, (中文(简体) ), `SettledRunSnapshot`, (中文(简体) ), `WaitForRunSnapshotOptions` | 类型. |
| `listAllProjects(baseUrl, token, opts?)` | `GET /v2/projects` ——工作空间的每一个项目,行走活泼到耗尽. |
| `getProjectDetail(baseUrl, token, projectId, opts?)` | `GET /v2/projects/{id}` - 一个项目,包括其工作目录和数据应用程序设置(`dataApp`, (中文(简体) ), `null` 其他项目类型). |
| `createDataAppProject(baseUrl, token, { name, folderId? }, opts?)` | `POST /v2/projects` 与 `projectType: 'data_app'` ——创建空的未公布的数据应用项目;返回 `{ id, name }`。 。 。 . |
| `setDataAppPublished(baseUrl, token, projectId, published, opts?)` | `PATCH /v2/projects/{id}` 与 `{ dataApp: { published } }` ——发布或撤销数据应用项目;返回 `{ published, url }`。 。 。 . |
| `exportProject(baseUrl, token, projectId, opts?)` | `GET /v2/projects/{id}/export` ——项目笔记本为定型 `.deepnote` 文档(未从导出 ZIP 中解开,每个笔记本一个)。 见下文. |
| `importProject(baseUrl, token, projectId, files, opts?)` | `POST /v2/projects/{id}/import` - 核对ZIP `.deepnote` 文档(准确反向输出)进入项目。 见下文. |
| `uploadProjectFile(baseUrl, token, projectId, path, bytes, opts?)` | `POST /v2/files` ——上传1个工作-指导文件(多部分). 不覆盖;先删除。 缓期调剂限于100米B. |
| `deleteProjectFile(baseUrl, token, projectId, path, opts?)` | `DELETE /v2/files` 删除一个工作指导文件; `false` 如果它不存在的话. |
| `downloadProjectFile(baseUrl, token, projectId, path, opts?)` | `GET /v2/files/download` ——一个工作-指导文件的生字节. 缓期调剂限于100米B. |
| `createStreamlitApp(baseUrl, token, body, opts?)` | `POST /v2/streamlit-apps` ——作为主机Streamlit应用程序服务于现有项目相关文件. 返回 `StreamlitApp` 记录; `url` 这是它的地址. |
| `listStreamlitApps(baseUrl, token, projectId, opts?)` | `GET /v2/streamlit-apps?projectId=` ——项目"流体"应用软件(未涂装). |
| `getStreamlitAppStatus(baseUrl, token, appId, opts?)` | `GET /v2/streamlit-apps/{id}/status` —— 说 `running`, (中文(简体) ), `starting`,或 `unavailable`。 。 。 . |
| `waitForStreamlitApp(baseUrl, token, appId, opts?)` | 投票直到 `running`· ; `unavailable` 不是终端。 重复短暂的失败; 抛出 `StreamlitAppTimeoutError` 之后 `timeoutMs` (默认10分). |
| `StreamlitAppTimeoutError` | 掷出时 `waitForStreamlitApp` 超过期限。 卡莉丝 `streamlitAppId` 财务报告和审定财务报表 `lastStatus`;应用程序可能仍在启动. |
| `StreamlitApp`, (中文(简体) ), `StreamlitAppStatus`, (中文(简体) ), `CreateStreamlitAppBody`, (中文(简体) ), `StreamlitAppRequestOptions`, (中文(简体) ), `WaitForStreamlitAppOptions` | 类型. |

**说明 `exportProject`数字 :** 导出是一个 ZIP 和一个 `.deepnote` 每个笔记本的文档 携带完整的项目信封和共享 `metadata.modifiedAt`。 。 。 . `exportProject` 解开它 返回文档(`{ filename, content }[]`,按文件名排序). 这个 **文档** 为: 字节决定一个不变的项目——ZIP容器不是——所以计算变化 指纹在文档上,而不是档案.

**说明 `importProject`数字 :** 发送一个 ZIP 和一个 `.deepnote` 文档 导出形状。 通过导出 `metadata.modifiedAt` 作为 `baseModifiedAt` 检测结构 更改(创建/删除/改名、其他进口)和内容散列为 `baseContentHash` 也可以检测编辑器块编辑,它从不推进时间戳;在不匹配服务器时 以409(丢失的更新保护)拒绝进口,以及 `force` 跳过两个检查。 进口 用笔记本 id 进行校正( 创建了不匹配的笔记本, 缺失的笔记本只删除与 `deleteMissingNotebooks`;空的 ZIP 导入不包含笔记本, 或者删除下面的每个笔记本 旗帜)。 每份文件都必须属于目标项目,并商定项目名称和整合 附录。 使用共享名称和一份礼物 `project.integrations` 列表对齐 工程附件( x)`[]` 解开全部;缺出一个字段后,它们保持不变)。 一体化 全权证书及全权证书 `settings.requirements` 从未进口.

终端状态可以在其快照附后前到达. 偏爱 `waitForRunSnapshot` 之后 投票:它简短地重复附件,返回 `content: null` 当没有生产出任何文物的时候, 并保留下载/读取失败为错误,而不是将其误认为是空运行.

**关于快照下载的说明 :** 只在下载 URL 时发送无记名符号 同一来源 `baseUrl`。在没有认证的情况下获取一个跨源的URL(例如,预先签名的S3链接), 所以信使永远不会泄露给第三方主机.

云运行和内容创建请求,即使呼叫者提供 取消信号。 最后期限包括消耗反应机构,以及暂停/调用者破坏 错误仍可与 `ApiError` 回应.

**说明 `createProject`数字 :** 这是无头对应器 `uploadNotebook`,使用 未认证 `/v1/import` 端点,因此必须在浏览器中完成. 带着一个标志, 首选项 `createProject` ——它还原出新的id,以便你立即运行笔记本.

两个API细节通过它泄露. `POST /v2/projects` 种子新工程,带有空占位符 笔记本,什么 `createProject` 一旦您的名称存在, 删除( 没有终点可重命名); a 无法删除的占位符通过 `onWarning` 而不是失败的创造。 还有 没有块块的终点,所以块块每个需要一个相继请求——使用 `onProgress` 报告 在一个大笔记本上。 中途失败的创建会留下部分内容:没有交易.

## 许可证

阿帕奇 - 2.0

## 常见问题

### @deepnote/cloud 是什么？

深音云客户端运行 API

### 如何安装 @deepnote/cloud？

在项目目录运行 npm install @deepnote/cloud，或使用 pnpm add / yarn add / bun add。

### @deepnote/cloud 支持 TypeScript 吗？

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

### @deepnote/cloud 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @deepnote/cloud 需要什么版本的 Node\.js？

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

### @deepnote/cloud 可以商用吗？

@deepnote/cloud 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @deepnote/cloud 的下载量有多少？

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

### @deepnote/cloud 还在维护吗？

最新版本 0\.4\.0 发布于 2026/11/10（1 天前）；至今共发布 5 个版本，其中过去 12 个月发布了 5 个；首次发布于 2026/08/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。