# @adobe/aio-lib-ims 中文文档

规范地址：https://npmcn.com/package/%40adobe/aio-lib-ims/

版本：8\.1\.2
npm 元数据更新时间：2026-10-01T01:32:28.761Z
中文译文更新时间：2026-11-05T18:27:29.296Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40adobe/aio-lib-ims
原文对照：https://npmcn.com/package/%40adobe/aio-lib-ims/?lang=original
项目主页：https://github.com/adobe/aio-lib-ims
源码仓库：https://github.com/adobe/aio-lib-ims

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

- 包体积（解压后）：107 kB，21 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：11 个
- 首次发布：2020-02-26T08:00:44.350Z
- 最新版本发布：2026-04-29T18:18:41.539Z
- 近 30 天下载量：71801（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：44（近 12 个月 2 个）

## 中文简介

Adobe IMS(身份管理系统) 支持模块提供低水平的IMS HTTP API访问以及更高水平的获取令牌支持.

## 安装

```sh
npm install @adobe/aio-lib-ims
```

也可以使用：`pnpm add @adobe/aio-lib-ims`、`yarn add @adobe/aio-lib-ims`、`bun add @adobe/aio-lib-ims`

## README

# Adobe I/O IMS 图书馆

[![Version](https://img.shields.io/npm/v/@adobe/aio-lib-ims.svg)](https://npmjs.org/package/@adobe/aio-lib-ims) [![Downloads/week](https://img.shields.io/npm/dw/@adobe/aio-lib-ims.svg)](https://npmjs.org/package/@adobe/aio-lib-ims) [![Node.js CI](https://github.com/adobe/aio-lib-ims/actions/workflows/node.js.yml/badge.svg)](https://github.com/adobe/aio-lib-ims/actions/workflows/node.js.yml)[![License](https://img.shields.io/npm/l/@adobe/aio-lib-ims.svg)](https://github.com/adobe/aio-lib-ims/blob/master/package.json) [![Codecov Coverage](https://img.shields.io/codecov/c/github/adobe/aio-lib-ims/master.svg?style=flat-square)](https://codecov.io/gh/adobe/aio-lib-ims/)

Adobe I/O IMS图书馆帮助与IMS API进行互动,并创建和去除符号. 为了支持多个使用大小写和环境,本库没有管理单一的配置,而是调用多个配置 _IMS 配置背景_。 。 。 . 每个配置上下文都持有创建令牌所需的配置数据. 见 _配置_ 下节.

## 安装

要安装 Adobe I/O IMS 库,只需使用 `npm`数字 :

```sh
npm install @adobe/aio-lib-ims --save
```

## 快速启动

在使用 AIO IMS 库之前, 您需要创建 Adobe 开发者控制台的集成程序, 您可以从其中获取集成细节来设置第一个配置上下文 。 让我们以 OAuth2 集成为例:

```js
const { context, getToken, getTokenData } = require('@adobe/aio-lib-ims')

const config = {
  redirect_uri: "https://callback.example.org",
  client_id: "123456cafebabe",
  client_secret: "12345678-cafe-babe-cafe-9999",
  scope: "openid"
};
await context.set('example', config, true)

const token = await getToken('example')
const tokenDecoded = getTokenData(token)
```

见 [API 文档](https://npmcn.com/package/%40adobe/aio-lib-ims/api.md) 详细情况.

## 配置

AIO IMS 图书馆透明地维护登录配置并保存 使用和刷新在过期前再使用的迹象.

所有配置都存储在单个中 `ims` 根属性.

库支持为不同的使用大小写维护多个配置. 每个这样的配置都存储在自己命名的对象中,并带有 `ims` 配置 . 这种配置被称为 _IMS( 配置) 上下文_ 并有一个标签,允许按名称引用配置.

这是一个例子 `ims` 配置

```js
{
  ims: {
    contexts: {
      sample_jwt: {
        client_id: "<jwt-clientid>",
        client_secret: "XXX",
        technical_account_id: "<guid>@techacct.adobe.com",
        meta_scopes: [
          "ent_dataservices_sdk"
        ],
        ims_org_id: "<org-guid>@AdobeOrg",
        private_key: "XXX"
      },
      sample_oauth2: {
        redirect_uri: "https://callback.example.com",
        client_id: "<oauth2-clientid>",
        client_secret: "XXX",
        scope: "openid AdobeID"
      },
    }
  }
}
```

## 在桌面上运行

当运行于您的本地机器时, AIO IMS 正在利用 [Aio- cli 插件使用的配置模块](https://github.com/adobe/aio-lib-core-config) 装入并更新存储在 `.aio` 财务报告和审定财务报表 `.env` 文档。 图书馆支持本地和全球的aio配置.

以下是依靠AIO IMS从现有配置中生成一个符号的例子:

```js
const { context, getToken } = require('@adobe/aio-lib-ims')

await context.setCurrent('my-config')
const token = await getToken('my-config')
```

## 在 Adobe I/O 运行运行时动作

**注:请选择更轻的 [@adobe/aio-lib-core-auth (英语)](https://github.com/adobe-developer-platform/app-builder-aio-lib-core-auth) 从 Adobe I/O 运行时动作生成 OAuth 令牌的库。 核心库注重高效地生成OAuth令牌,不依赖CLI所需的复杂上下文/插件逻辑. 它还使用内嵌式缓存,而不是App Builder State存储器,可能会遇到使用限制**

AIO IMS库也可以被用到Adobe I/O跑时动作中. 在这种情况下,信息管理系统的配置必须事先确定。 图书馆依靠的是 [Adobe App 构建器州立图书馆](https://github.com/adobe/aio-lib-state) 将所有行动都作为访问标志,并减少向投管处提出的请求.

以下是Adobe I/O 运行时动作例

```js
const { context, getToken } = require('@adobe/aio-lib-ims')

function main ({ imsContextConfig, ...params }) {
  // the IMS context configuration is passed as an action parameter
  // imsContextConfig = { client_id, client_secret, technical_account_id, meta_scopes, ims_org_id, private_key }
  await context.set('my_ctx', imsContextConfig)

  const token = await getToken('my_ctx')
}
```

几点考虑:

-   对字符集的额外限制.
    
    -   名称空间必须通过 Adobe 开发者控制台( 遵循`amsorg-project(-workspace)?` 页:1 不支持遗留的命名空间 .
    -   i/O 运行时动作名称和上下文名称(用于 `context.set`)必须是字母字符串和 `-`, (中文(简体) ), `_`, (中文(简体) ), `.` 被允许.
-   `getToken('my_ctx')` 将永远在州内留下象征 `local=true|false` 用于 `context.set`。 。 。 .
    
-   只为单个 I/O 运行时动作缓存了符号, 这意味着缓存符号无法在动作和运行中获取 `getToken` 在另一个具有相同上下文名的动作中,将重生出一个新的符号.
    

## IMS 环境

IMS环境的使用被保留给Adobe使用. 供参考的是: `env` 配置上下文属性并取出一个值 `prod` 财务报告和审定财务报表 `stage`。 。 。 . 默认值为 `prod`。 。 。 . 一般来说,你不需要处理这个财产.

## 设置当前上下文( 高级)

默认上下文可以在本地设置 `await context.setCurrent('contextname')`。 。 。 . 这将写入以下配置到 `ims` 键 `.aio` 当前工作目录的文件 :

```js
  ims {
    config: {
      current: "contextname"
    }
  }
```

如果在同一工作目录中运行库, 那么 `getToken` 可以不通过 `contextname`数字 :

```js
await context.set('contextname', config, true)
await context.setCurrent('contextname')
const token = await getToken() // generate a token for the config in the 'contextname' context
```

**请注意: `context.setCurrent` 重写本地配置并替换默认值 `aio` 桌面环境中的 CLI OAuth 配置 . 这个会断的 `aio` 命令从同一目录中运行.** 您可以通过执行恢复到原有行为 `aio config delete ims.config.current` 从目录.

## JWT 配置( 已过期)

JWT配置已贬值,有利于OAuth服务器对服务器配置.

JWT(服务集成)配置需要具备以下属性:

| 财产 | 说明 |
| --- | --- |
| 客户端( d) | IMS(Oauth2)客户端ID. 这是 _API 密钥_ 在 Adobe 开发者控制台的集成概览中. |
| 客户端 机密 | IMS( ONOTH2) 客户端秘密 |
| 技术 账户 id | 这个 _技术账户编号_ 从 Adobe 开发者控制台中的集成概览屏幕 |
| 元镜 | 元范围名称阵列 。 这些是样本中一个矿石更特殊属性的标签 _JWT 有效载荷_。可以在 _日本_ 选项卡中的 Adobe 开发者控制台集成 _JWT 有效载荷_ 窗体属性 `"https://<ims-host>/s/ent_dataservices_sdk": true,`. 可能存在一种或多种取决于合并所订阅的服务。 要列出的值 **元镜** 属性是 URL 的最后一个部分。 举例来说,这将是 `ent_dataservices_sdk`。 。 。 . |
| ims org id (韩语) | 这个 _组织标识_ 从 Adobe 开发者控制台中的集成概览屏幕. |
| 私钥 | 匹配任意一个的私钥 _公钥_ 综合计划。 这可以作为一行中的私钥作为字符串,也可以是串的数组(每个元素都是从密钥文件中发出的一行) 见 [设置私钥](https://npmcn.com/package/%40adobe/aio-lib-ims/#readme-setting-the-private-key) 节. |
| 密码句 | (单位:千美元)_可选_) (中文(简体) ). 私钥之通口. |

### 设置私钥

对于 JWT 配置,您的私人密钥在 Adobe 开发者控制台中生成,并在生成时被下载到您的计算机上.

Adobe 开发者 Console 不保留私有密钥(只保存您的对应公钥), 因此您必须设定您在 IMS 上下文配置中手动下载的私有密钥 .

您可以通过两种方式在配置中设置您的私钥:

1.  导入私钥为字符串
2.  设置私人密钥的文件引用

下面的指示假设一个私人密钥文件叫做 `private.key` 财务报告和审定财务报表 `CONTEXT_NAME` 是您 JWT 上下文的名称.

1.  要导入您的私钥为字符串 : `aio config:set ims.contexts.CONTEXT_NAME.private_key path/to/your/private.key --file`
2.  要设置私人密钥的文件引用 : `aio config:set ims.contexts.CONTEXT_NAME.private_key path/to/your/private.key`

注意您的私钥路径, 如果它是相对路径, 将会相对于当前工作目录解决 .

## OAuth2 配置

OAuth2 配置需要以下属性:

| 财产 | 说明 |
| --- | --- |
| 客户端( d) | IMS(Oauth2)客户端ID. 这是 _API 密钥_ 在 Adobe 开发者控制台的集成概览中. |
| 客户端 机密 | IMS( ONOTH2) 客户端秘密 |
| 方向调整 uri | 这个 _默认重定向 URI_ 从 Adobe 开发者控制台中的集成概览屏幕。 或者,任何URI匹配其中之一 _重定向 URI 模式_ 可使用. |
| 范围 | 给令牌分配范围。 这是一系列逗号分离的域名, 取决于此集成所订阅的服务 。 Adobe 开发者控制台目前不披露为 OAuth2 集成定义的范围列表,在服务中可以找到一个很好的范围列表 [OAuth 2.0 范围](https://www.adobe.io/authentication/auth-methods.html#!AdobeDocs/adobeio-auth/master/OAuth/Scopes.md)。至少您可能想要输入 `openid`。 。 。 . |

## OAuth 服务器对服务器配置

此配置将取代 JWT 配置 .

OAuth 服务器对服务器(客户资格授权类型)配置需要以下属性: 用户身份认证

| 财产 | 说明 |
| --- | --- |
| 客户端( d) | IMS(Oauth2)客户端ID. 这是 _API 密钥_ 在 Adobe 开发者控制台的集成概览中. |
| 客户端 机密 | IMS( ONDOTH2) 客户端机密阵列 |
| 技术账户( e) | 这个 _技术账户电子邮件_ 从 Adobe 开发者控制台中的集成概览屏幕 |
| 技术 账户 id | 这个 _技术账户编号_ 从 Adobe 开发者控制台中的集成概览屏幕 |
| 范围 | 给令牌分配范围。 这是一系列的字符串, 取决于此集成所订阅的服务 。 OAuth2 服务器对服务器证书定义的范围列表列于 `Scopes` 选项卡. |
| ims org id (韩语) | Adobe开发者控制台的集成概览屏幕中的组织ID. |

## 托肯验证

### 缓存

验证和无效可以被缓存来提高性能. 要使用缓存, 配置一个新的缓存, 并在初始化时传递给库 :

```js
const { Ims, ValidationCache, getToken} = require('@adobe/aio-lib-ims')

const CACHE_MAX_AGE_MS = 5 * 60 * 1000 // 5 minutes
const VALID_CACHE_ENTRIES = 10000
const INVALID_CACHE_ENTRIES = 20000
const cache = new ValidationCache(CACHE_MAX_AGE_MS, VALID_CACHE_ENTRIES, INVALID_CACHE_ENTRIES)
const ims = new Ims('prod', cache)

const token = params.theToken // May be passed via header, parameter, or other input
const imsValidation = await ims.validateToken(token)
if (!imsValidation.valid) {
  return new Error('Forbidden: This is not a valid IMS token!') // Next time validateToken() is called with this token, a call to IMS will not be made while the cache is still fresh
}
```

### 允许列表

您可以对照IMS客户端的许可列表验证一个令牌. 要使用允许列表, 请将您的令牌和一系列IMS客户端传递到 `validateTokenAllowList()`数字 :

```js
const { Ims } = require('@adobe/aio-lib-ims')
const ims = new Ims()

const token = params.theToken // May be passed via header, parameter, or other input
const allowList = ['ironmaiden', 'metallica', 'gunsandroses']
const imsValidation = await ims.validateTokenAllowList(token, allowList)
if (!imsValidation.valid) {
  return new Error('Forbidden: This client is not allowed!')
}
```

## 捐款

欢迎捐款! 读取 [贡献指南](https://npmcn.com/package/%40adobe/aio-lib-ims/CONTRIBUTING.md) 更多信息.

## 许可证发放

这个项目根据Apache V2许可证获得许可. 见 [自由主义](https://npmcn.com/package/%40adobe/aio-lib-ims/LICENSE) 更多信息.

## 常见问题

### @adobe/aio-lib-ims 是什么？

Adobe IMS\(身份管理系统\) 支持模块提供低水平的IMS HTTP API访问以及更高水平的获取令牌支持\.

### 如何安装 @adobe/aio-lib-ims？

在项目目录运行 npm install @adobe/aio-lib-ims，或使用 pnpm add / yarn add / bun add。

### @adobe/aio-lib-ims 支持 TypeScript 吗？

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

### @adobe/aio-lib-ims 支持 ESM 还是 CommonJS？

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

### @adobe/aio-lib-ims 需要什么版本的 Node\.js？

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

### @adobe/aio-lib-ims 可以商用吗？

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

### @adobe/aio-lib-ims 的下载量有多少？

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

### @adobe/aio-lib-ims 还在维护吗？

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