# @cognite/sdk 中文文档

规范地址：https://npmcn.com/package/%40cognite/sdk/

版本：10\.19\.0
npm 元数据更新时间：2026-11-06T13:06:21.541Z
中文译文更新时间：2026-11-10T10:03:03.278Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：1.9 MB，111 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2018-12-18T23:14:20.207Z
- 最新版本发布：2026-11-06T13:06:21.198Z
- 近 30 天下载量：46403（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：269（近 12 个月 15 个）

## 中文简介

包裹 `@cognite/sdk` 方便地进入马厩 [认知 API](https://doc.cognitedata.com/dev/) 以客户端或服务器侧javascript写成的应用程序.

## 安装

```sh
npm install @cognite/sdk
```

也可以使用：`pnpm add @cognite/sdk`、`yarn add @cognite/sdk`、`bun add @cognite/sdk`

## README

# 认知 Javascript SDK

包裹 `@cognite/sdk` 方便地进入马厩 [认知 API](https://doc.cognitedata.com/dev/) 以客户端或服务器侧javascript写成的应用程序.

SDK通过无记名符号支持认证. 见 [认证指南](https://github.com/cognitedata/cognite-sdk-js/blob/v1/guides/authentication.md)。 。 。 .

## 安装

用纱线安装软件包 :

```
$ yarn add @cognite/sdk
```

或无

```
$ npm install @cognite/sdk --save
```

## 使用量

```js
const { CogniteClient } = require('@cognite/sdk');
```

### 使用ES模块

```js
import { CogniteClient } from '@cognite/sdk';
```

### 使用打字符

SDK是用本地打字符写的,所以不需要定义额外的类型.

## 快速启动

### 网页

```js
import { CogniteClient } from '@cognite/sdk';

async function quickstart() {
  const project = 'publicdata';
  const oidcTokenProvider = async () => {
    return 'YOUR_OIDC_ACCESS_TOKEN';
  };

  const client = new CogniteClient({
    appId: 'YOUR APPLICATION NAME',
    project,
    oidcTokenProvider,
  });

  const assets = await client.assets.list().autoPagingToArray({ limit: 100 });
}
quickstart();
```

> 关于SDK认证的更详细信息请参见此 [文档](https://github.com/cognitedata/cognite-sdk-js/blob/master/guides/authentication.md)。 。 。 . 此外,还可找到更全面的入门指南 [这里](https://docs.cognite.com/dev/guides/sdk/js/)

### 后端

```js
const { CogniteClient } = require('@cognite/sdk');

async function quickstart() {
  const client = new CogniteClient({
    appId: 'YOUR APPLICATION NAME',
    oidcTokenProvider: () => Promise.resolve('YOUR_OIDC_ACCESS_TOKEN'),
  });

  const assets = await client.assets.list().autoPagingToArray({ limit: 100 });
}
quickstart();
```

## 文档

-   [API 参考文件](https://doc.cognitedata.com/api/v1)
-   [JS SDK 参考文件](https://cognitedata.github.io/cognite-sdk-js/classes/cogniteclient.html)

## 货币

> **实验:** 页:1 `concurrency` 选项是实验性的。 中断更改 包括补丁和小版本.

货币限制控制 同一时间,而不是它每秒发出多少请求。 限额按 客户端和操作类别。 达到类别限制的请求在 队列;其他类别和单独的客户端有独立的限制.

SDK使用semaphores来管理这些队列. 每次HTTP尝试都获得一个插槽 并保留到反应机构读取或尝试失败。 槽数 在重试后退时释放,允许排队请求继续。 重试 必须再次获得一个位置; 备份只暂停该请求, 而不是类别 .

在FIFO(先入先出)命令中允许排队尝试,但呼叫是 **未保证在援引命令中完成**。继续等待依赖 明显变异.

SDK 强制 **无请求超时**从未解决的请求,包括 待命反应机构,无限期保留其位置。 时机成熟的外出承诺, 举例来说 `Promise.race`,不取消相关请求或释放 它的档位.

货币限额为: **选入**: 除非您通过 `concurrency` 客户端选项。 传递一个空对象以启用默认值 . 目前,SDK只对数据建模请求适用货币限制. 其他API请求不受此机制的限制.

> **说明:** CDF是一个共享后端服务. 过高的货币可降解 组织内其他工作量的业绩。 从默认开始 \* 谨慎地限制和增加这些限制和增加,监测延迟和延缓反应 (HTTP 429) (韩语). 较高的通货量不一定意味着较高的通货量.

### 数据建模货币

一次 `concurrency` 设置, 数据建模请求受默认限制 见下文。 每个客户都有在数据模型中所有终点共享的独立预算 `/models` 命名空间和数据建模 GraphQL 路由,包括原始客户端 HTTP 调用 :

| 类别 | 默认 | 业务 |
| --- | --- | --- |
| `read` | 1个 | 实例列表、检索、查询、同步、检查、DM用户GraphQL查询和变异 |
| `search` | 2个 | 实例搜索和汇总 |
| `write` | 1个 | 案件升级/申请 |
| `delete` | 1个 | 删除实例 |
| `readSchema` | 2个 | 空间、容器、视图和数据模型的读取;统计 |
| `writeSchema` | 1个 | 图QL DML 撰写 |

数据建模图QL查询和变异 `/userapis/spaces/{space}/datamodels/{model}/versions/{version}/graphql` 全部使用 `read`。分类是基于终点,而不是GraphQL请求机构,所以 这些突变没有获得REST `write` 或者说 `delete` 预算。 增加 `read` 还增加了这些突变的允许货币. 图QL DML 写给 `/dml/graphql` 使用情况 `writeSchema`。 。 。 .

已知名称空间使用的未知操作 `readSchema`; 其他不详 数据模型中的操作 `/models` 名称空间使用 `read`。 。 。 . 项目路径在代理路径前缀后仍然有限, 例如 `https://proxy.example/cdf/api/v1/projects/my-project/models/instances/query`。 。 。 . 类别有独立的预算,因此不同类别的请求可以运行 同时。 如果每个类别都是饱和的,默认最多允许8个 每个客户的飞行请求(1+2+1+1+1+2+1).

要启用默认限制 :

```js
const client = new CogniteClient({
  appId: 'YOUR APPLICATION NAME',
  project: 'YOUR PROJECT',
  oidcTokenProvider: async () => 'YOUR_OIDC_ACCESS_TOKEN',
  concurrency: {},
});
```

为设定具体限额:

```js
const client = new CogniteClient({
  appId: 'YOUR APPLICATION NAME',
  project: 'YOUR PROJECT',
  oidcTokenProvider: async () => 'YOUR_OIDC_ACCESS_TOKEN',
  concurrency: {
    dataModeling: { read: 2, write: 2 },
  },
});
```

被允许或 `undefined` 类别值保留其默认值。 限制必须是 正整数或 `Infinity`; 无效值在客户端构建过程中抛出. `Infinity` 禁用一个类别的限制(即没有货币控制).

默认 `read: 1`,一个已停用实例读取的块块 建模读取同一个客户端。 Schema 读取,其他类别保留 独立.

## 最佳做法

### 无子模块导入

我们强烈建议避免从SDK内部模块中进口任何东西.

所有接口和函数只能从顶层导入,否则在我们内部结构发生变化时,你可能会面临相容性问题.

**错误 :**

```
import { CogniteAsyncIterator } from '@cognite/sdk/dist/src/autoPagination'; // ❌
import { AssetsAPI } from '@cognite/sdk/dist/src/resources/assets/assetsApi'; // ❌

let assetsApi: AssetsAPI; // ❌
```

**不错:**

```
import { CogniteAsyncIterator } from '@cognite/sdk'; // ✅

let assetsApi: CogniteClient['assets']; // ✅
```

我们建议使用 [埃斯林特语name](https://eslint.org/docs/rules/no-restricted-imports) 确保执行这一最佳做法而不必记住模式:

**.eslintrc.json: (英语)**

```
"rules": {
  "no-restricted-imports": ["error", { "patterns": ["@cognite/sdk/**"] }]
}
```

API参考文件包含每个端点的片段, 给出 SDK 使用的例子。 另见 [样本部分](https://github.com/cognitedata/cognite-sdk-js#samples) 这回贷.

## 指南

-   [移徙指南](https://github.com/cognitedata/cognite-sdk-js/blob/master/guides/MIGRATION_GUIDE_1xx_2xx.md) 如何从版本迁移 `1.x.x` 改为版本 `2.x.x`。 。 。 .
-   [移徙指南](https://github.com/cognitedata/cognite-sdk-js/blob/master/guides/MIGRATION_GUIDE_2xx_3xx.md) 从版本 `2.x.x` 改为版本 `3.x.x`。 。 。 .

## 常见问题

### @cognite/sdk 是什么？

包裹 @cognite/sdk 方便地进入马厩 认知 API 以客户端或服务器侧javascript写成的应用程序\.

### 如何安装 @cognite/sdk？

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

### @cognite/sdk 支持 TypeScript 吗？

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

### @cognite/sdk 支持 ESM 还是 CommonJS？

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

### @cognite/sdk 可以商用吗？

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

### @cognite/sdk 的下载量有多少？

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

### @cognite/sdk 还在维护吗？

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