# @aidbox/sdk-r4 中文文档

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

版本：1\.0\.15
npm 元数据更新时间：2024-10-30T17:10:22.446Z
中文译文更新时间：2026-11-06T13:25:44.008Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：1.9 MB，434 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：2 个
- 首次发布：2023-06-16T14:05:53.642Z
- 最新版本发布：2024-10-30T17:10:22.242Z
- 近 30 天下载量：3141（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 0 个）

## 中文简介

带有 HL7- R4 软件包的默认辅助箱 SDK

## 安装

```sh
npm install @aidbox/sdk-r4
```

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

## README

# 辅助箱 JavaScript SDK FHIR-R4

## 如何使用

**重要内容:** 在我们开始之前,我们必须确保 辅助框 [客户端](https://docs.aidbox.app/tutorials/security-and-access-control/basic-auth-tutorial#basic-auth) 实值 配置 还有你的 [准入政策](https://docs.aidbox.app/security-and-access-control-1/security/access-control) 提供 你试图接触到的资源的颗粒性访问.

```javascript
import { Client } from 'aidbox-sdk';

export const aidbox = new Client('<HOST_URL>', {
  auth: {
    method: 'basic',
    credentials: {
      username: '<CLIENT_NAME>',
      password: '<CLIENT_SECRET>',
    },
  },
});
```

此代码从 Aidbox- sdk 软件包创建 SDK 的新实例, 并将其设置为连接到 Aidbox 服务器 运行中 `<HOST_URL>`。 。 。 . 你需要替换 `<CLIENT_NAME>` 财务报告和审定财务报表 `<CLIENT_SECRET>` 和你的客户身份和客户秘密 配置较早,SDK也支持两种类型的API(Aidbox, 斐济 [显示差异](https://docs.aidbox.app/modules-1/fhir-resources/aidbox-and-fhir-formats)只要提供其中之一 作为第三个参数.

通过在项目中使用 Aidbox-sdk ,您可以轻松地与 Aidbox 服务器交互,并进行诸如读取和 写入资源, 查找资源, 以及更多 .

那你可以随时随地使用辅助箱

```javascript
import { aidbox } from '../aidbox-client';

async function getPatients() {
  return aidbox.resource.list('Patient');
}
```

## API 密码

### 资源。 列表

列表方法接受资源名称,并成为随后请求复杂化的依据

#### 地点

添加搜索参数的方法

举例来说,你想找到所有叫约翰的病人,所以

```typescript
resource.list('Patient').where('name', 'John');
```

或者你想找到所有叫约翰或史蒂夫的病人

```typescript
resource.list('Patient').where('name', ['John', 'Steve']);
```

另外,支持数字和日期前缀的方法,只是通过它作为第三个参数

```typescript
resource.list('Patient').where('birthdate', '2014-06-30', 'gt');
```

#### 排序

方法排序添加排序参数

例如,您想要展示最年长的病人

```typescript
resource.list('Patient').sort('birthdate', 'asc');
```

还有,你想用病人的名字来整理数据

```typescript
resource.list('Patient').sort('birthdate', 'asc').sort('name', 'asc');
```

#### 计数

限制请求返回资源数量的方法计数

```typescript
resource.list('Patient').count(10);
```

#### 内容提要

要请求服务器提供部分资源,您可以使用摘要函数。 此函数允许您 指定要收到的摘要类型,例如 **真实、虚假、文本、数据或计数**。 。 。 .

默认情况下, 当你向服务器提出请求时, 它会返回所有的资源 .

摘要功能接受几类摘要,每类摘要提供了不同程度的详细内容 数据。 例如:

-   true - 有限的资源元素子集
    
-   假 - 资源的所有部分
    
-   文本 - 只有文本、 id、 meta 和顶级强制元素
    
-   数据 - 没有文本元素的资源
    
-   计数 - 计算匹配资源,而不返回实际匹配
    
    摘要( “数据”)
    

#### 要件

如果您需要从服务器取回某一资源的特定元素,则可以使用元素函数. 此函数 允许您指定您感兴趣的资源中哪些部分,并可以帮助减少数据数量 由服务器返回.

通过使用元素函数,您可以自定义只获取您需要的数据的请求,而不是 请求整个数据集。 在处理大型数据集时,或当您只需要一个 可用数据的小子集.

要使用元素函数,只需在您想要获取的元素中传递作为参数。 例如,如果你 需要资源的名称和地址字段,您可以使用下列语法提出请求:

```typescript
resource.list('Patient').elements(['name', 'address']);
```

此请求将只返回每个资源的名称和地址字段,而不是整个数据集 。 通过减少 ,您可以帮助精简请求,提高应用程序的性能.

### 资源.get

获取函数是用其ID检索单一资源的工具.

要使用 GetResource 函数,您必须在资源类型和ID中通过作为参数. 例如,如果你想的话 用 ID- ID 检索病人资源, 您可以使用下列语法提出请求 :

```typescript
resource.get('Patient', 'id');
```

### 资源。创建

创建资源函数用于创建新资源.

第一个参数是一个资源名称,第二个参数是一个资源主体

```typescript
resource.create('Patient', { active: true });
```

### 资源.更新()

更新功能用于更新其id识别的特定资源并配有部分数据集 在第三个参数中提供。 此函数允许部分更新资源而无需发送 整个资源对象.

第一个参数指定要更新的资源名称. 第二个参数确定具体 待更新的资源.

```typescript
resource.update('Patient', 'c58f29eb-f28d-67c1-0400-9af3aba3d58c', {
  active: false,
});
```

### qq 资源. delete ()

删除资源功能用于删除其id识别的特定资源.

```typescript
resource.delete('Patient', 'c58f29eb-f28d-67c1-0400-9af3aba3d58c');
```

### 创建订阅

Aidbox订阅是订阅和获取服务器上更新资源的通知的一种方式. 见 我们 [订阅样本](https://github.com/Aidbox/aidbox-sdk-js/tree/main/subscription-sample) 更多细节.

```javascript
await client.subsSubscription.create({
  id: 'patient-created',
  status: 'active',
  trigger: { Patient: { event: ['create'] } },
  channel: { endpoint: 'https://aidbox/patient-created' },
});
```

### 发送日志

Aidbox具有扩展其日志的能力. 有一个 a 一个 [结束点](https://docs.aidbox.app/core-modules/logging-and-audit/extending-access-logs#usdloggy-endpoint) 那个 从应用程序中接受带有定义结构的日志。 这些原木被吸收入弹性原木.

```javascript
await client.sendLog({
    type: "ui",
    message: {event: "YOUR_EVENT", id: "id", ...},
    v: "APP_VERSION",
    fx: "fetchUsers"
})
```

### Bundle 请求

SDK有帮助者为捆绑请求准备数据.

```javascript
client.transformToBundle(
  [
    {
      resourceType: 'Patient',
      name: [
        {
          given: [''],
          family: '',
        },
      ],
    },
  ],
  'POST',
);
```

捆绑请求可以是 [交易或批次](https://docs.aidbox.app/api-1/fhir-api/bundle#post-endpoint) 类型。 SDK 软件 默认使用“ 交易” 类型, 但可以通过在第二个参数中提供它来更改.

```javascript
const data = ArrayOfPatients.map(client.bundleEntryPost);

await client.bundleRequest(data, 'batch');
```

## 任务 API

队列是实现可靠,同步,可伸缩,再试安全代码执行的宝贵工具. 通过使用队列,我们可以确保任务或消息得到可靠处理,即使面对失败或系统 中断. 队列的同步性质允许独立处理任务,允许并行化并减少等待 时间.

```javascript
import { Engine } from 'aidbox-javascript-sdk';

const client = new Engine('http://localhost:8888', {
  username: 'test',
  password: 'secret',
});
```

### 定义

首先,我们必须创造任务的计划 设置限制 此实体的输入和输出参数 :

```clojure
 SendMessage
{:zen/tags #{awf.task/definition zen/schema}
 :type     zen/map
 :keys     {:params {:type    zen/map
                     :require #{:phone :message}
                     :keys    {:phone   {:type zen/string}
                               :message {:type zen/string}}}
            :result {:type    zen/map
                     :require #{:status}
                     :keys    {:status {:type zen/string}}}}}
```

[关于任务定义的更多信息](https://docs.aidbox.app/modules-1/workflow-engine/task#1.-specify-task-definition)  
注意: 每次修改配置项目, 我们必须重生 SDK 包

### 执行情况

下一步是创造商业逻辑 将被视为一个工人, 工人会处理每个任务,我们可以

```javascript
client.task.implement(
  'SendMessage',
  async ({ params, status }) => {
    const { message, phone } = params;

    try {
      await fetch('https://message-sending-server.com/', {
        method: 'POST',
        body: JSON.stringify({ message, phone }),
      });

      return { status: 'success' };
    } catch (error) {
      return { status: 'failure' };
    }
  },
  { batchSize: 5 },
);
```

### 执行

以独特的背景执行单一任务的方法

```javascript
await client.task.execute('SendMessage', {
  phone: '+1234567890',
  message: 'Hi!',
});
```

## 工作流程引擎

Aidbox 提供了 Workflow 引擎模块,所以您可以定义自己的序列 在任务 API 之上的同步任务。 在许多业务流程中,某些任务取决于其他任务的完成. 通过工作流程执行定义任务依赖性允许开发者 以控制任务执行的顺序.

```javascript
import { Engine } from 'aidbox-javascript-sdk';

const client = new Engine('http://localhost:8888', {
  username: 'test',
  password: 'secret',
});
```

### 工作流程定义

```clojure
 CheckOutWorkflow
{:zen/tags #{awf.workflow/definition zen/schema}
 :type     zen/map
 :pool     decision-pool
 :keys     {:params {:type    zen/map
                     :require #{:clientId}
                     :keys    {:clientId {:type zen/string}}}
            :result {:type zen/map
                     :keys {:messageId {:type zen/string}}}
            :error  {:type zen/map
                     :keys {:message {:type zen/string}}}}}
```

[关于工作流程定义的更多信息](https://docs.aidbox.app/modules-1/workflow-engine/workflow#1.-specify-workflow-definition)  
注意: 每次修改配置项目, 我们必须重生 SDK 包

### 工作流程

```javascript
await client.workflow.implement(
  'CheckOutWorkflow',
  async ({ params }, { execute, complete, fail }) => {
    if (params.event === 'awf.workflow.event/workflow-init') {
      const response = await fetch('https://server.com/get-client');
      const { phone } = response.json();
      return [
        execute({
          definition: 'SendMessage',
          params: { phone, message: 'Hi!' },
        }),
      ];
    }

    try {
      const response = await fetch('https://workflow-state.com');
      const data = response.json();

      if (
        params.event === 'awf.workflow.event/task-completed' &&
        data.step === 1
      ) {
        return [execute({ definition: 'UpdateInformation', params: {} })];
      }

      if (
        params.event === 'awf.workflow.event/task-completed' &&
        data.step === 2
      ) {
        return [complete({})];
      }
    } catch (error) {
      return [fail({ error })];
    }

    return [];
  },
);
```

### 工作流程执行

```javascript
await client.workflow.execute('CheckOutWorkflow', { clientId: '' });
```

## 常见问题

### @aidbox/sdk-r4 是什么？

带有 HL7- R4 软件包的默认辅助箱 SDK

### 如何安装 @aidbox/sdk-r4？

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

### @aidbox/sdk-r4 支持 TypeScript 吗？

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

### @aidbox/sdk-r4 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aidbox/sdk-r4 需要什么版本的 Node\.js？

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

### @aidbox/sdk-r4 可以商用吗？

@aidbox/sdk-r4 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @aidbox/sdk-r4 的下载量有多少？

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

### @aidbox/sdk-r4 还在维护吗？

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