# @esri/telemetry-amazon 中文文档

规范地址：https://npmcn.com/package/%40esri/telemetry-amazon/

版本：6\.0\.6
npm 元数据更新时间：2026-11-10T23:08:11.694Z
中文译文更新时间：2026-11-13T22:48:54.093Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：1.5 MB，152 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：@esri/telemetry ^9\.0\.0
- 首次发布：2021-11-09T17:07:04.349Z
- 最新版本发布：2026-11-10T23:08:11.485Z
- 近 30 天下载量：10456（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：76（近 12 个月 28 个）

## 中文简介

Amazon “ 遥测. js” 库插件

## 安装

```sh
npm install @esri/telemetry-amazon
```

也可以使用：`pnpm add @esri/telemetry-amazon`、`yarn add @esri/telemetry-amazon`、`bun add @esri/telemetry-amazon`

## README

# `@esri/telemetry-amazon`

> 这是一个插件,用于 `Telemetry.js` 与 AWS 分析存储交互的软件包.

## 目录

-   [`@esri/telemetry-amazon`](https://npmcn.com/package/%40esri/telemetry-amazon/#readme-esritelemetry-amazon)
    -   [Amazon Pinpoint 退休和迁移](https://npmcn.com/package/%40esri/telemetry-amazon/#readme-amazon-pinpoint-retirement--Migration)
    -   [如何使用](https://npmcn.com/package/%40esri/telemetry-amazon/#readme-how-to-use)
    -   [亚马逊配置](https://npmcn.com/package/%40esri/telemetry-amazon/#readme-amazon-configuration)
    -   [示例](https://npmcn.com/package/%40esri/telemetry-amazon/#readme-example)
        -   [`telemetry.logEvent(event)`](https://npmcn.com/package/%40esri/telemetry-amazon/#readme-telemetrylogeventevent)
    -   [遥测共享权限](https://npmcn.com/package/%40esri/telemetry-amazon/#readme-telemetry-sharing-permissions)
        -   [门户项目](https://npmcn.com/package/%40esri/telemetry-amazon/#readme-portal-items)
        -   [使用量](https://npmcn.com/package/%40esri/telemetry-amazon/#readme-usage)
    -   [问题](https://npmcn.com/package/%40esri/telemetry-amazon/#readme-issues)
    -   [捐款](https://npmcn.com/package/%40esri/telemetry-amazon/#readme-contributing)
    -   [许可证](https://npmcn.com/package/%40esri/telemetry-amazon/#readme-license)

```sh
npm install @esri/telemetry
npm install @esri/telemetry-amazon
```

## Amazon Pinpoint 退休和迁移

Amazon Pinpoint 将在 **2026年10月30日 (中文(简体) )**。在此日期之后,Pinpoint不能再用于遥测传输。 见 [aWS官方退休公告](https://docs.aws.amazon.com/pinpoint/latest/userguide/migrate.html) 详细情况.

默认情况下,亚马逊追踪器现在将事件发送到埃斯里后端而不是平分. 一旦在兼容版本 `@esri/telemetry-amazon` 图书馆(`^6.0.0`,更新您的配置,以指向匹配您的应用程序 id 的环境 :

```js
const amazonTracker = new Amazon({
  env: 'production' | 'qa' | 'dev',
  ....
});
```

所有其他配置保持不变.

说明: **2026年10月30日 (中文(简体) )** 页:1 `mode: 'pinpoint'` 所有交通都会通过Esri后端.

## 如何使用

`@esri/telemetry-amazon` 软件包在客户端浏览器和服务器端节点.js中工作. 要使用它, 安装软件包, 把它包含在您的工程中, 创建一个 Amazon 插件实例, 并添加到 `plugins` 以 [@esri/遥测](https://npmcn.com/package/README.md)。 。 。 .

以下是如何使用遥测-AMazon插件的例子.

```js
import { Telemetry } from '@esri/telemetry';
import { Amazon } from '@esri/telemetry-amazon';

const amazonTracker = new Amazon({
  userPoolID: USER_POOL_ID,
  env: 'production' | 'qa' | 'dev',
  fips: true, // defaults to false
  app: {
    name: APP_NAME,
    id: APP_ID,
    version: APP_VERSION,
  },
  mode: 'pinpoint', // Pinpoint retires on October 30, 2026. Use 'esri' or omit this field for continued support.
});

const telemetryOptions = {
  plugins: [amazonTracker],
  portal: {
    subscriptionInfo: {},
    user: {},
  },
};

const telemetry = new Telemetry(telemetryOptions);

telemetry.logPageView();

telemetry.logEvent();
```

初始化后 `Telemetry.js` 与 Amazon 插件,遥测数据将发送到配置的目的地.

### 处理错误

临时网络故障( E)`500`, (中文(简体) ), `503`)和HTTP 软件 `408`, (中文(简体) ), `429`,以及 `ThrottlingException` `400` 反应以指数倒置重试;其他 `4xx` 答复被视为长期失败. `Retry-After` 代替图书馆的后退时间 `429` 财务报告和审定财务报表 `503` 回应.

### 后端有效载荷限制

后端规定了以下限制:

-   事件有效载荷中的个人属性被封为500个字符. 属性长于此被切为前500个字符.
    
-   接连收到的事件要排队分批发送。 当符合下列任何条件时,批次将提交服务器:
    
    -   五百多场活动已经排队
    -   有效载荷的总尺寸超过3mb
        -   如果单个事件超过这个尺寸,则有效载荷将被抛出. 这是不可能的,但是一个在字符限制上有很多属性的事件可以达到几个mb
    -   上次事件发生5秒后
    -   用户导航远离页面

## 亚马逊配置

-   从 AWS 获取您的应用程序和用户池ID
-   在选项中通过对象创建亚马逊插件实例
-   页:1 `fips` 选项确定是否对认知请求使用 AWS FIPS 端点
-   这个 `env` 选项指定 Esri 端点事件将设定为哪个,默认为 `"dev"`
    -   将来发行这个 `env` 将自动检测,但此参数将保持为手动覆盖
-   在包含您自定义维度和度量的映射对象中通过

```js
// or if you are using optional custom dimensions and/or custom metrics
const amazonTracker = new Amazon({
  dimensions: {
    datasetID: 1,
    attribute: 2,
    serviceQuery: 3,
  },
  metrics: {
    duration: 1,
    size: 2,
  },
});
```

如果您需要禁用跟踪, 您可以设定 `disabled: true` 初始化时 `Telemetry` 对象。 然后,你可以继续使用 方法在你的例子 `Telemetry` 没有丢弃例外 或记录错误.

此外,您可以在初始化时禁用单个跟踪器 `Telemetry` 通过移动对象 `disabled: true` 在跟踪选项中.

```js
const amazonTracker = new Amazon({
  disabled: true,
});
```

初始化后,可以禁用并启用特定的跟踪器 `disableTracker` 财务报告和审定财务报表 `enableTracker` 方法。 。 .

```js
telemetry.disableTracker('amazon');

telemetry.logPageView(); // no amazon page view logged

telemetry.logEvent(); // no amazon event logged

telemetry.enableTracker('amazon');

telemetry.logPageView(); // amazon page view logged

telemetry.logEvent(); // amazon event logged
```

## 示例

#### `telemetry.logEvent(event)`

**重要性**

-   除下列情况外,不要通过用户名: `event.user`否则,它不会被匿名化.

举个例子.

```js
const event = {
  category: 'Dataset',
  action: 'Attribute Inspect',
  label: 'Crimes 2016',
  datasetID: '1ef',
  attribute: 'crime_type',
  user: 'amazing_map_woman',
};

telemetry.logEvent(event);
```

## 遥测共享权限

### 门户项目

`telemetry-amazon` 包含用于设置和获取门户项目的遥测访问的静态方法.

### 使用量

```js
import { Amazon } from '@esri/telemetry-amazon'
...

// see https://developers.arcgis.com/arcgis-rest-js/api-reference/arcgis-rest-request/ArcGISIdentityManager/
const authentication = await ArcGISIdentityManager.signIn(username, password)

const getAccessParams = {
  id: '1ef',
  authentication,
}

const access = await Amazon.getAccessPermissions(getAccessParams: IGetAccessPermissionsParams)

const setAccessParams = {
  id: '1ef',
  authentication,
  username: 'dev_pre_a_hub_admin',
  accessChangeset: [
    {
      action: 'add',
      targetProperty: 'public',
    }
  ]
}

const result = await Amazon.setAccessPermissions(setAccessParams: ISetAccessPermissionsParams)
```

## 问题

如果有什么不起作用,请看一看 [以往问题](https://devtopia.esri.com/WebGIS/arcgis-telemetry.js/issues) 先说 你找到新窃听器了吗? 创建问题 [这里](https://devtopia.esri.com/WebGIS/arcgis-telemetry.js/issues/new)。 。 。 .

## 捐款

Esri欢迎所有人的贡献。 请看我们的 [提交文件的准则](https://npmcn.com/package/CONTRIBUTING.md)。 。 。 .

## 许可证

版权: 2026 Esri

根据Apache许可证第2.0版("License"); 您不得使用此文件,除非符合许可证. 您可在下列地点获得许可证副本:

> [http://www.apache.org/licenses/LICENSE-2.0 (中文(简体) )](http://www.apache.org/licenses/LICENSE-2.0)

除非适用的法律要求或书面同意,否则软件 根据许可证发放的是在“AS IS”BASIS上发放的, 没有任何明示或暗示的警告或条件. 有关许可的特定语言的许可证 许可证的限制.

许可证副本可到存放处索取 [自由主义](https://npmcn.com/package/LICENSE) 文档.

## 常见问题

### @esri/telemetry-amazon 是什么？

Amazon “ 遥测\. js” 库插件

### 如何安装 @esri/telemetry-amazon？

在项目目录运行 npm install @esri/telemetry-amazon，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@esri/telemetry（^9\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @esri/telemetry-amazon 支持 TypeScript 吗？

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

### @esri/telemetry-amazon 支持 ESM 还是 CommonJS？

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

### @esri/telemetry-amazon 可以商用吗？

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

### @esri/telemetry-amazon 的下载量有多少？

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

### @esri/telemetry-amazon 还在维护吗？

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