认知 Javascript SDK

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

SDK通过无记名符号支持认证. 见 认证指南。 。 。 .

安装

用纱线安装软件包 :

$ yarn add @cognite/sdk

或无

$ npm install @cognite/sdk --save

使用量

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

使用ES模块

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

使用打字符

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

快速启动

网页

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认证的更详细信息请参见此 文档。 。 。 . 此外,还可找到更全面的入门指南 这里

后端

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 参考文件
• JS SDK 参考文件

货币

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

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

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

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

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

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

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

数据建模货币

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

数据建模图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).

要启用默认限制 :

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

为设定具体限额:

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 确保执行这一最佳做法而不必记住模式:

.eslintrc.json: (英语)

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

API参考文件包含每个端点的片段, 给出 SDK 使用的例子。 另见 样本部分 这回贷.

指南

• 移徙指南 如何从版本迁移 1.x.x 改为版本 2.x.x。 。 。 .
• 移徙指南 从版本 2.x.x 改为版本 3.x.x。 。 。 .