# @astrato-io/sdk 中文文档

规范地址：https://npmcn.com/package/%40astrato-io/sdk/

版本：0\.6\.0
npm 元数据更新时间：2026-10-28T18:45:43.816Z
中文译文更新时间：2026-11-07T00:58:19.263Z
软件包许可：SEE LICENSE IN LICENSE

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

原始 npm 页面：https://www.npmjs.com/package/%40astrato-io/sdk
原文对照：https://npmcn.com/package/%40astrato-io/sdk/?lang=original

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

- 包体积（解压后）：83.7 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-10-20T13:54:23.342Z
- 最新版本发布：2026-10-28T18:45:40.810Z
- 近 30 天下载量：17648（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

浏览器 SDK 连接自定义应用程序到 Astrato APIs 和运行时服务.

## 安装

```sh
npm install @astrato-io/sdk
```

也可以使用：`pnpm add @astrato-io/sdk`、`yarn add @astrato-io/sdk`、`bun add @astrato-io/sdk`

## README

# @astrato-io/sdk (英语)

浏览器 SDK 连接自定义应用程序到 Astrato APIs 和运行时服务.

使用此软件包进行认证,Astrato API请求,数据和元数据访问,事件,变量,以及组范围选择状态. 可视化渲染是由 `@astrato-io/visualizations`。 。 。 .

## 安装

```bash
npm install @astrato-io/sdk
```

该软件包作为无害环境管理方式分发,需要浏览器环境 `fetch`, (中文(简体) ), `Headers`,以及 `URL`. RxJS作为包依赖性安装,被公众可观察到的API所使用.

## 创建客户端

```ts
import { createAstratoClient } from '@astrato-io/sdk';

const client = createAstratoClient({
  baseUrl: 'https://your-astrato-instance.example/',
  tenantId: 'tenant-id',
  auth: {
    token: 'personal-access-token',
  },
  visualizationEngine: true,
});
```

`baseUrl` 需要时间. `tenantId` 用作数据和元数据请求的默认租户.

认证可以使用固定的代号,同步的代号提供者,或者自定义标题:

```ts
const client = createAstratoClient({
  baseUrl,
  tenantId,
  auth: {
    getAccessToken: async () => refreshAccessToken(),
    headers: {
      'x-client-name': 'customer-portal',
    },
  },
});
```

当一个符号可用时, SDK 以 `Authorization: Bearer <token>` 除非明确提供授权信头.

## 嵌入式框架桥

嵌入到可信任的主机中的应用程序可以使用相同的SDK客户端而无需收到主机的证书. 主机建立版本 `MessagePort` 与一个iframe连接,并通过允许的列表回调处理请求。 这是一个清晰的靴子: 仅仅在iframe内 永远无法使桥梁.

在主机中,在iframe应用程序启动前创建桥. 这个 `request` 回调必须验证相对的 SDK 路径, HTTP 方法, 租户, 语义层, 并对照主机自身的授权规则进行操作, 然后使用保留在主机中的证书执行已核准的操作 。 在没有故意许可名单的情况下,不要向特权网络客户端转发儿童提供头条. 如果桥在iframe装上后被接通,通过 `initialLoadComplete: true`;这让桥区分出第一个负载和后期导航.

```ts
import { createAstratoIframeHostBridge } from '@astrato-io/sdk';

const bridge = createAstratoIframeHostBridge({
  iframe,
  childOrigin: 'null', // for an intentionally opaque sandbox; otherwise use the exact child origin
  context: {
    tenantId,
    semanticLayer: { id: semanticLayerId, datasourceType },
    capabilities: ['query', 'metadata'],
  },
  request: (request, signal) => executeAllowedSdkRequest(request, signal),
});

// Destroy when the iframe is removed or its authority changes.
bridge.destroy();
```

Iframe所信任的应用靴子提供了精确的父源并连接一次. 之后,共享应用程序运行时代码可以同步发现已建立的连接并创建普通可视化启用的客户端:

```ts
import { connectAstratoIframeBridge, getAstratoIframeBridge } from '@astrato-io/sdk';

await connectAstratoIframeBridge({ parentOrigin: trustedParentOrigin });

const connection = getAstratoIframeBridge();
if (!connection) throw new Error('Astrato iframe bridge is unavailable.');
const client = connection.createClient();
```

`createClient()` 永远不再回到 `fetch`。该桥拒绝绝对的 URL 和 证书 信头、 边框请求和响应大小,并支持请求中止、 超时和断开清理。 主机请求最多 `maxConcurrentRequests` 一次( 默认为16); 过多的请求按到达顺序等待, 最多有 32 个活动请求和队列请求合并 。 请求超时包括等待的时间. 已中止或超时的活性请求保持其货币位,直到主机调回结算,所以即使该调回忽略了中止,主机限制仍然准确. 主机出错作为通用代码返回,因此私密细节不会被发送到iframe. 主机回调仍然是授权边界;上下文 `capabilities` 列表为描述性。 协议版本导出为 `ASTRATO_IFRAME_BRIDGE_PROTOCOL_VERSION` 和不兼容的版本不连接。 破坏或替换连接会破坏其SDK客户端并使其元数据缓存失效.

## 数据和元数据

直接数据服务使用当前Astrato数据和schema APIs. 查询有效载荷通过时没有隐藏过滤器,可变或选择更改.

语义层元数据从租户范围的数据视图复合端点上载: `/api/message/tenants/{tenantId}/schema/dataviews/{semanticLayerId}/composite`。该响应提供了引擎字段密钥、语义项目密钥和视图连接,而不从图、视图或字段名称重建身份.

```ts
const metadata = await client.services.data.getSemanticLayerMetadata?.('semantic-layer-id');

const result = await client.hostServices.engine.getData({
  semanticLayerId: 'semantic-layer-id',
  query: {
    dimensions: [],
    measures: [],
  },
});
```

当可视化引擎执行查询时,它会保留每个可视化的最新成功查询元数据 对象标识。 使用该元数据显示已执行的 SQL 、 持续时间、 结果大小、 供应商查询链接或真实仓库查询 不再次发布数据查询的洞察力 :

```ts
const metadata = client.hostServices.engine.getLastQueryMetadata?.('sales-by-manufacturer');

const insights =
  metadata?.semanticLayerId && metadata.startTime !== undefined
    ? await client.hostServices.engine.getQueryInsights?.({
        queryID: metadata.queryID,
        semanticLayerId: metadata.semanticLayerId,
        startTime: metadata.startTime,
      })
    : undefined;
```

查询元数据被请求上下文隔离 `objectId`如果对一个对象的多次请求相重叠,则只有 最新要求可能更新其元数据。 查询的可用性和响应细节取决于连接的仓库.

可视化引擎地图 `semanticLayerId` 到当前引擎 API 的 遗产 `databaseID` 电线场. 低层 `client.services.data.query()` 方法保持透明并公布 `query` 值不重写.

请求上下文可以在客户端上配置一次,并在每个查询中覆盖:

```ts
const client = createAstratoClient({
  baseUrl,
  tenantId,
  auth: { token },
  context: {
    datasourceType: 'snowflake',
    sheetId: 'sheet-id',
    workbookState: 'draft',
    workbookVersionContainerId: 'workbook-version-container-id',
  },
});
```

## 已认证的请求 和自定义

使用 `client.request()` 对于没有专用服务方法的Astrato端点。 请求使用配置的基址、认证、传输事件和错误记录:

```ts
const response = await client.request({
  method: 'GET',
  url: 'api/example',
});
```

`createAstratoClient()` 还接受自定义 `transport`, (中文(简体) ), `logger`,事件总线,数据端点覆盖,以及主机服务实施. 这些选项允许应用程序整合自己的网络,诊断,或平台服务而不改变可视化代码.

## 可视化引擎

目前Astrato可视化包装需要小型同步引擎表面. 在使用客户端时明确启用 SDK 的可视化引擎 `@astrato-io/visualizations`数字 :

```ts
const client = createAstratoClient({
  baseUrl,
  tenantId,
  auth: { token },
  visualizationEngine: true,
});

await client.hostServices.engine.fields.getFieldMetadata?.({
  semanticLayerId: 'semantic-layer-id',
  tenantId,
});
```

元数据快照在一个客户端内再利用五分钟,最多完成16个 截图保留。 同一租户、语义层、数据来源和 认证机构共享一个负载 。 配置 `metadataCache` 打开 `createAstratoClient()` 当不同的约束是适当的。 打电话 `client.hostServices.engine.fields.invalidateMetadata()` 模式更改后; 通过相同的元数据请求以取消一个层, 或省略它以清除 全部的快照. `refreshMetadata(request)` 清除并重新装入一层。 页面重载创建 新客户端, 因此从空缓存开始 .

默认引擎会解决每个元数据操作或查询的认证并绑定它 请求相同的信头。 同时期业务分担待认证解析. 在每次引用时返回新令牌的召回被支持. 当任何 SDK 请求被观察时 更改了认证信头,默认引擎清除其已缓存和活跃的元数据。 装入 在读取同步字段或连接API之前再次读取元数据. 查询解析认证 在变换之前,它们不能替换先前权威元数据中的字段. 如果后续的 SDK 操作出现变化, 元数据操作或引擎查询会拒绝 在完成前进行认证;被拒绝的查询结果不会更新查询元数据. 老一点 在更新成功查找后完成的认证查询,如果其证书不同于 现在的 普通请求继续解决自己的认证问题. 没有SDK认证而自行提供运输权限的应用程序必须调用 `invalidateMetadata()` 当权力改变。 查询结果永远不会被缓存 .

摧毁客户端只会使元数据在由该客户端创建的引擎中失效. 提供引擎 结束 `hostServices.engine` 仍归其召唤者所有。 分组分割选择幸存缓存 命中;一个新的元数据负载再次从模型中初始化它们.

同步元数据调用加载引擎快照. 现场获取器和连接检查随后按照可视化包装器的要求同步读取该快照. 字段由引擎识别 `fieldKey` 值; SDK 不将字段键分析为视图/名称引用. 语义维度,度量和计算使用综合响应提供的密钥和相关观点. 视图名称只保留在已存在的可视化API仍然请求视图级连接的情况下.

预计可视化领域暂时包括 `schema: 'legacy'` 因为可视化软件包 仍然需要非空值。 此兼容性占位符独立于源数据库 策略并覆盖任何进入的字段 `schema`; 它不会改变条形引擎键或源 元数据。 消费者应当使用字段键进行身份识别. 删除这一要求和占位符 追踪到 [ASTA - 15281号](https://app.clickup.com/t/123y1w8p6zn)。 。 。 .

## 使用 SDK 的可视化

在主机应用程序中安装软件包并导入一次可视化样式表 :

```bash
npm install @astrato-io/sdk @astrato-io/visualizations
```

```ts
import '@astrato-io/visualizations/styles.css';
```

为应用程序创建一个SDK客户端和一个可视化运行时间. 必须启用可视化引擎,以便运行时间能够通过SDK加载数据和语义层元数据:

```ts
import { createAstratoClient } from '@astrato-io/sdk';
import { createVisualizationRuntime, registerAstratoElements, registry } from '@astrato-io/visualizations';

const tenantId = 'tenant-id';
const semanticLayerId = 'semantic-layer-id';

const client = createAstratoClient({
  baseUrl: 'https://your-astrato-instance.example/',
  tenantId,
  auth: { token: 'personal-access-token' },
  visualizationEngine: true,
});

const runtime = createVisualizationRuntime({
  client,
  registry,
});

runtime.createInstance({
  id: 'sales-by-manufacturer',
  type: 'bar',
  groupId: 'dashboard',
  dataBinding: {
    tenantId,
    semanticLayerId,
    datasourceType: 'snowflake',
  },
});

registerAstratoElements({ runtime });
```

将运行时间自有实例与框架中性网络组件:

```html
<astrato-visualization instance-id="sales-by-manufacturer"></astrato-visualization>
```

该元素必须具有非零维度:

```css
astrato-visualization {
  display: block;
  width: 100%;
  height: 400px;
}
```

若为 `vSpec` 中省略,运行时创建了空的默认可视化。 要创建有用的初始可视化, 使用 `compileVisualizationDefinition()` 从 `@astrato-io/visualizations/definitions` 并装入语义层元数据 `client.hostServices.engine.fields.getFieldMetadata()`。将已编译的 vSpec 传递到 `runtime.createInstance()`定义使用精确的引擎键,在编译失败时返回结构化验证问题.

直接管理 DOM 生命周期的应用程序可以在没有网络组件的情况下挂载 :

```ts
const container = document.getElementById('chart');

if (!container) {
  throw new Error('Missing chart container.');
}

const handle = await runtime.mount(container, 'sales-by-manufacturer');
const renderResult = await handle.ready;

console.log(renderResult.status);

handle.unmount();
runtime.removeInstance('sales-by-manufacturer');
```

同样的情况 `groupId` 共享选择状态。 删除一个网络组件会自动卸载; 取消不再需要的运行时间实例并调用 `client.destroy()` 当应用程序处理 SDK 客户端时.

见 `@astrato-io/visualizations` 软件包 README 用于支持的可视化ID,完整的定义计划,操作,获取器,元数据发现,以及自定义元素选项.

## 东道主服务

客户端通过 : `client.services` 财务报告和审定财务报表 `client.hostServices`. SDK和运输活动 可通过 `client.events`。 。 。 .

| 服务 | 目的 |
| --- | --- |
| `data` | 查询、语义层元数据、数据源元数据、汇总和能力 |
| `engine` | 可选可视化兼容查询和字段适配器 |
| `selections` | 分组范围已应用并待选择状态 |
| `variables` | 可变查询和数值解析度 |
| `model` | 可视化模型保存相容性钩 |

应用程序可通过 `hostServices`数字 :

```ts
const client = createAstratoClient({
  baseUrl,
  hostServices: {
    variables: customVariableService,
  },
});
```

缺少所需的配置时,数据和引擎默认明显失败. 选择和可变默认使用元状态.

## 选择状态

选择被隔离 `groupId`。价值和关联选择与引擎字段键一起使用其类型 作为身份,所以两种类型可以共存为一个领域.

```ts
client.services.selections.selectValues('dashboard', {
  field: { fieldKey: '[Orders].[Country]' },
  operator: 'inList',
  values: ['Sweden'],
});

const subscription = client.services.selections.onActiveSelectionChangeApplied('dashboard').subscribe((selection) => {
  console.log(selection.applied);
});

subscription.unsubscribe();
```

选择模式默认为 `auto`内 `manual` 模式中,更改将持续到 `applyPendingSelections(groupId)` 名为.

## 持久性行为

SDK不默认持续可视化或工作簿状态.

-   `model.saveProperties()` 财务报告和审定财务报表 `model.saveLocalVSpec()` 是兼容性无操作.
-   无隐含 `localStorage` 或使用索引数据库存储.

## 事件和清理

```ts
const unsubscribe = client.events.on('transport:error', (event) => {
  console.error(event.payload);
});

unsubscribe();
client.destroy();
```

`destroy()` 清除 SDK 事件订阅 。 申请还应不订阅其拥有的可观察服务.

## 软件包构建

软件包包含一个精密的ESM捆绑,一个单一的公开的TypeScript声明文件,这个README,软件包元数据,所提供的LICENSE文档,以及任何通知文件. 它没有源地图。 RxJS仍为外置,因此应用程序捆绑器可以去除并摇出树来.

JavaScript 执行和公开的 API 类型可以被软件包用户看到. 消减不会使客户端代码保密. 主机应用程序和Astrato API必须保留证书和访问规则.

## 常见问题

### @astrato-io/sdk 是什么？

浏览器 SDK 连接自定义应用程序到 Astrato APIs 和运行时服务\.

### 如何安装 @astrato-io/sdk？

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

### @astrato-io/sdk 支持 TypeScript 吗？

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

### @astrato-io/sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @astrato-io/sdk 可以商用吗？

@astrato-io/sdk 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @astrato-io/sdk 的下载量有多少？

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

### @astrato-io/sdk 还在维护吗？

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