# @aws/amazon-location-utilities-auth-helper 中文文档

规范地址：https://npmcn.com/package/%40aws/amazon-location-utilities-auth-helper/

版本：1\.3\.3
npm 元数据更新时间：2026-06-22T20:38:51.239Z
中文译文更新时间：2026-11-07T10:59:17.712Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aws/amazon-location-utilities-auth-helper
原文对照：https://npmcn.com/package/%40aws/amazon-location-utilities-auth-helper/?lang=original
项目主页：https://github.com/aws-geospatial/amazon-location-utilities-auth-helper-js
源码仓库：https://github.com/aws-geospatial/amazon-location-utilities-auth-helper-js

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

- 包体积（解压后）：1.8 MB，29 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 20\.0\.0
- 运行依赖：4 个
- 首次发布：2023-07-03T22:37:53.088Z
- 最新版本发布：2026-05-08T16:31:01.760Z
- 近 30 天下载量：213139（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 5 个）

## 中文简介

Amazon 位置工具 - JavaScript 认证帮助器

## 安装

```sh
npm install @aws/amazon-location-utilities-auth-helper
```

也可以使用：`pnpm add @aws/amazon-location-utilities-auth-helper`、`yarn add @aws/amazon-location-utilities-auth-helper`、`bun add @aws/amazon-location-utilities-auth-helper`

## README

# Amazon 位置工具 - JavaScript 认证帮助器

[![Version](https://img.shields.io/npm/v/@aws/amazon-location-utilities-auth-helper?style=flat)](https://www.npmjs.com/package/@aws/amazon-location-utilities-auth-helper) [![Tests](https://github.com/aws-geospatial/amazon-location-utilities-auth-helper-js/actions/workflows/build.yml/badge.svg)](https://github.com/aws-geospatial/amazon-location-utilities-auth-helper-js/actions/workflows/build.yml)

这些是公用设备 用来帮助客户验证 [亚马逊定位服务](https://aws.amazon.com/location/) API从他们的JavaScript应用程序中调用. 这在使用时特别有帮助 [API 密钥](https://docs.aws.amazon.com/location/latest/developerguide/using-apikeys.html), (中文(简体) ), [亚马逊-科尼奥托](https://docs.aws.amazon.com/location/latest/developerguide/authenticating-using-cognito.html),或自定义证书提供者作为认证方法.

## 安装

从国家防范机制安装此库供模块使用:

```console
npm install @aws/amazon-location-utilities-auth-helper
```

导入 HTML 文件, 直接用于浏览器 .

```html
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-utilities-auth-helper@1"></script>
```

## 使用量

导入库并按需要调用顶级命名空间中的公用功能 。 此库用于验证独立请求 [地图](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-amzn-geomaps-client/), (中文(简体) ), [地点](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-amzn-geoplaces-client/),以及 [路线](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-amzn-georoutes-client/) SDKs,该 [地点 SDK](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-location/),在绘制地图时 [MapLibre GL 联合来文](https://maplibre.org/projects/maplibre-gl-js/)。 。 。 .

您可以在 [文档](https://npmcn.com/package/%40aws/amazon-location-utilities-auth-helper/#readme-documentation) 节.

### 模块的使用

这些例子显示在模块中导入我们的库,然后使用捆绑器将您的模块组合成一个可以在浏览器或其他环境中运行的脚本.

此示例使用独立的 [地点](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-amzn-geoplaces-client/) SDK可以提出使用API密钥认证的请求.

```console
npm install @aws-sdk/geo-places-client
```

```javascript
// Import from the AWS JavaScript SDK V3 (GeoPlacesClient)
import { GeoPlacesClient, GeocodeCommand } from "@aws-sdk/geo-places-client";
// Import the utility functions
import { withAPIKey } from "@aws/amazon-location-utilities-auth-helper";

// Create an authentication helper instance using an API key and region
const authHelper = withAPIKey("<API Key>", "<Region>");

// Configures the client to use API keys when making supported requests
const client = new GeoPlacesClient(authHelper.getClientConfig());

const input = { ... };
const command = new GeocodeCommand(input);
const response = await client.send(command);
```

此示例使用独立的 [路线](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-amzn-georoutes-client/) SDK可以提出使用API密钥认证的请求.

```console
npm install @aws-sdk/geo-routes-client
```

```javascript
// Import from the AWS JavaScript SDK V3 (GeoRoutesClient)
import { GeoRoutesClient, CalculateRoutesCommand } from "@aws-sdk/geo-routes-client";
// Import the utility functions
import { withAPIKey } from "@aws/amazon-location-utilities-auth-helper";

// Create an authentication helper instance using an API key and region
const authHelper = withAPIKey("<API Key>", "<Region>");

// Configures the client to use API keys when making supported requests
const client = new GeoRoutesClient(authHelper.getClientConfig());

const input = { ... };
const command = new CalculateRoutesCommand(input);
const response = await client.send(command);
```

此示例使用 [地点](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-location/) SDK可以提出使用API密钥认证的请求.

```console
npm install @aws-sdk/client-location
```

```javascript
// Import from the AWS JavaScript SDK V3 (LocationClient)
import { LocationClient, ListGeofencesCommand } from "@aws-sdk/client-location";
// Import the utility functions
import { withAPIKey } from "@aws/amazon-location-utilities-auth-helper";

// Create an authentication helper instance using an API key and region
const authHelper = withAPIKey("<API Key>", "<Region>");

// Configures the client to use API keys when making supported requests
const client = new LocationClient(authHelper.getClientConfig());

const input = { ... };
const command = new ListGeofencesCommand(input);
const response = await client.send(command);
```

此示例使用独立的 [路线](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-amzn-georoutes-client/) SDK要求使用Amazon Cognito认证.

```console
npm install @aws-sdk/geo-routes-client
```

```javascript
// Import from the AWS JavaScript SDK V3 (GeoRoutesClient)
import { GeoRoutesClient, CalculateRoutesCommand } from "@aws-sdk/geo-routes-client";
// Import the utility functions
import { withIdentityPoolId } from "@aws/amazon-location-utilities-auth-helper";

// Create an authentication helper instance using credentials from Cognito
const authHelper = await withIdentityPoolId("<Identity Pool ID>");

// Configures the client to use credentials obtained via Amazon Cognito
const client = new GeoRoutesClient(authHelper.getClientConfig());

const input = { ... };
const command = new CalculateRoutesCommand(input);
const response = await client.send(command);
```

此示例使用独立的 [路线](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-amzn-georoutes-client/) SDK会请求使用自定义的证书提供者进行认证.

```console
npm install @aws-sdk/geo-routes-client
```

```javascript
// Import from the AWS JavaScript SDK V3 (GeoRoutesClient)
import { GeoRoutesClient, CalculateRoutesCommand } from "@aws-sdk/geo-routes-client";
// Import the utility functions
import { withCredentialProvider } from "@aws/amazon-location-utilities-auth-helper";

// Create an authentication helper instance using a custom credential provider and region
const authHelper = await withCredentialProvider(async () => {
  // Fetch credentials from your custom source (e.g. a backend service, authenticated Cognito pool, etc.)
  return {
    accessKeyId: "<Access Key ID>",
    secretAccessKey: "<Secret Access Key>",
    sessionToken: "<Session Token>", // optional
    expiration: new Date("<Expiration>"), // optional
  };
}, "<Region>");

// Configures the client to use the custom credentials
const client = new GeoRoutesClient(authHelper.getClientConfig());

const input = { ... };
const command = new CalculateRoutesCommand(input);
const response = await client.send(command);
```

此示例使用 [MapLibre GL 联合来文](https://maplibre.org/projects/maplibre-gl-js/) 以使用自定义的证书提供者来认证资源请求.

```javascript
// Import MapLibre GL JS
import maplibregl from "maplibre-gl";
// Import the utility function
import { withCredentialProvider } from "@aws/amazon-location-utilities-auth-helper";

const region = "<Region>"; // Region containing Amazon Location resource
const styleName = "Standard"; // Standard, Monochrome, Hybrid, or Satellite

// Create an authentication helper instance using a custom credential provider
const authHelper = await withCredentialProvider(async () => {
  // Fetch credentials from your custom source
  return {
    accessKeyId: "<Access Key ID>",
    secretAccessKey: "<Secret Access Key>",
    sessionToken: "<Session Token>", // optional
    expiration: new Date("<Expiration>"), // optional
  };
}, region);

// Render the map
const map = new maplibregl.Map({
  container: "map",
  center: [-123.115898, 49.295868],
  zoom: 10,
  style: `https://maps.geo.${region}.amazonaws.com/v2/styles/${styleName}/descriptor`,
  ...authHelper.getMapAuthenticationOptions(),
});
```

此示例使用 [MapLibre GL 联合来文](https://maplibre.org/projects/maplibre-gl-js/) 以生成使用 API 键认证资源请求的地图.

> 在使用 MapLibre 来制作使用 API 密钥的地图时不需要认证帮助器,因为样式描述器 URL 和 API 密钥可以直接传递到样式端点.

```javascript
// Import MapLibre GL JS
import maplibregl from "maplibre-gl";

const apiKey = "<API Key>";
const region = "<Region>"; // Region containing Amazon Location resource
const styleName = "Standard"; // Standard, Monochrome, Hybrid, or Satellite

// Render the map
const map = new maplibregl.Map({
  container: "map",
  center: [-123.115898, 49.295868],
  zoom: 10,
  style: `https://maps.geo.${region}.amazonaws.com/v2/styles/${styleName}/descriptor?key=${apiKey}`,
});
```

此示例使用 [MapLibre GL 联合来文](https://maplibre.org/projects/maplibre-gl-js/) 以生成一个使用 Amazon Cognito 验证资源请求的地图.

```javascript
// Import MapLibre GL JS
import maplibregl from "maplibre-gl";
// Import the utility function
import { withIdentityPoolId } from "@aws/amazon-location-utilities-auth-helper";

const identityPoolId = "<Identity Pool ID>";
const region = "<Region>"; // Region containing Amazon Location resource
const styleName = "Standard"; // Standard, Monochrome, Hybrid, or Satellite

// Create an authentication helper instance using credentials from Cognito
const authHelper = await withIdentityPoolId(identityPoolId);

// Render the map
const map = new maplibregl.Map({
  container: "map",
  center: [-123.115898, 49.295868],
  zoom: 10,
  style: `https://maps.geo.${region}.amazonaws.com/v2/styles/${styleName}/descriptor`,
  ...authHelper.getMapAuthenticationOptions(),
});
```

### 使用浏览器

用户功能可在 `amazonLocationAuthHelper` 全球.

> 其中一些例子使用亚马逊地块客户端. Amazon 位置客户端基于 [JavaScript V3 的 AWS SDK 软件](https://github.com/aws/aws-sdk-js-v3) ,并允许通过 HTML 文件引用的脚本给 Amazon Location 打电话.

此示例使用 Amazon 位置客户端来请求使用 API 密钥进行认证 .

```html
<!-- Importing the Amazon Location Client (which includes the auth-helper) -->
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-client@1"></script>
```

```javascript
// Create an authentication helper instance using an API key and region
const authHelper = amazonLocationClient.withAPIKey("<API Key>", "<Region>");

// Configures the client to use API keys when making supported requests
const client = new amazonLocationClient.GeoRoutesClient(authHelper.getClientConfig());
const input = { ... };
const command = new amazonLocationClient.routes.CalculateRoutesCommand(input);
const response = await client.send(command);
```

这个例子使用亚马逊地标客户端来请求使用亚马逊地标认证.

```html
<!-- Import the Amazon Location Client (which includes the auth-helper) -->
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-client@1"></script>
```

```javascript
// Create an authentication helper instance using credentials from Cognito
const authHelper = await amazonLocationClient.withIdentityPoolId("<Identity Pool ID>");

// Configures the client to use credentials obtained via Amazon Cognito
const client = new amazonLocationClient.GeoRoutesClient(authHelper.getClientConfig());
const input = { ... };
const command = new amazonLocationClient.routes.CalculateRoutesCommand(input);
const response = await client.send(command);
```

此示例使用 [MapLibre GL 联合来文](https://maplibre.org/projects/maplibre-gl-js/) 以生成使用 API 键认证资源请求的地图.

> 在使用 MapLibre 来制作使用 API 密钥的地图时不需要认证帮助器,因为样式描述器 URL 和 API 密钥可以直接传递到样式端点.

```html
<!-- MapLibre GL JS -->
<script src="https://cdn.jsdelivr.net/npm/maplibre-gl@5"></script>
```

```javascript
const apiKey = "<API Key>";
const region = "<Region>"; // Region containing Amazon Location resource
const styleName = "Standard"; // Standard, Monochrome, Hybrid, or Satellite

// Render the map
const map = new maplibregl.Map({
  container: "map",
  center: [-123.115898, 49.295868],
  zoom: 10,
  style: `https://maps.geo.${region}.amazonaws.com/v2/styles/${styleName}/descriptor?key=${apiKey}`,
});
```

此示例使用 [MapLibre GL 联合来文](https://maplibre.org/projects/maplibre-gl-js/) 以生成一个使用 Amazon Cognito 验证资源请求的地图.

```html
<!-- MapLibre GL JS -->
<script src="https://cdn.jsdelivr.net/npm/maplibre-gl@5"></script>
<!-- Importing the authentication SDK -->
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-utilities-auth-helper@1"></script>
```

```javascript
const identityPoolId = "<Identity Pool ID>";
const region = "<Region>"; // Region containing Amazon Location resource
const styleName = "Standard"; // Standard, Monochrome, Hybrid, or Satellite

// Create an authentication helper instance using credentials from Cognito
const authHelper = await amazonLocationAuthHelper.withIdentityPoolId(identityPoolId);

// Render the map
const map = new maplibregl.Map({
  container: "map",
  center: [-123.115898, 49.295868],
  zoom: 10,
  style: `https://maps.geo.${region}.amazonaws.com/v2/styles/${styleName}/descriptor`,
  ...authHelper.getMapAuthenticationOptions(),
});
```

或者,如果您喜欢使用认证身份,您可以修改 `withIdentityPoolId` 用于提供自定义参数的签名 :

```javascript
const userPoolId = "<User pool Id>";
...

// Create an authentication helper instance using credentials from Cognito
const authHelper = await amazonLocationAuthHelper.withIdentityPoolId(identityPoolId, {
  logins: {
    [`cognito-idp.${region}.amazonaws.com/${userPoolId}`]: "cognito-id-token"
  }
});

...
```

你可以拿回来 `cognito-id-token` 从用户会话中 [使用扩展](https://docs.amplify.aws/javascript/build-a-backend/auth/manage-user-session/#retrieve-a-user-session)

此示例使用 [MapLibre GL 联合来文](https://maplibre.org/projects/maplibre-gl-js/) 以使用自定义的证书提供者来认证资源请求.

```html
<!-- MapLibre GL JS -->
<script src="https://cdn.jsdelivr.net/npm/maplibre-gl@5"></script>
<!-- Importing the authentication SDK -->
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-utilities-auth-helper@1"></script>
```

```javascript
const region = "<Region>"; // Region containing Amazon Location resource
const styleName = "Standard"; // Standard, Monochrome, Hybrid, or Satellite

// Create an authentication helper instance using a custom credential provider
const authHelper = await amazonLocationAuthHelper.withCredentialProvider(async () => {
  // Fetch credentials from your custom source
  return {
    accessKeyId: "<Access Key ID>",
    secretAccessKey: "<Secret Access Key>",
    sessionToken: "<Session Token>", // optional
    expiration: new Date("<Expiration>"), // optional
  };
}, region);

// Render the map
const map = new maplibregl.Map({
  container: "map",
  center: [-123.115898, 49.295868],
  zoom: 10,
  style: `https://maps.geo.${region}.amazonaws.com/v2/styles/${styleName}/descriptor`,
  ...authHelper.getMapAuthenticationOptions(),
});
```

## 文档

详细文件可在以下下生成: `docs/index.html` 通过运行 :

```console
npm run typedoc
```

### `withAPIKey`

使用 API 密钥( 和区域, 可选) 创建 Auth 帮助实例 .

```javascript
const authHelper = withAPIKey(apiKey, region);
```

### `withIdentityPoolId`

使用来自 Cognitto 的证书创建认证帮助实例 .

```javascript
const authHelper = await withIdentityPoolId(identityPoolId);
```

### `withCredentialProvider`

使用任意性创建认证助手实例 [证书提供者](https://www.npmjs.com/package/@aws-sdk/credential-providers#credentials-provider) 函数。 在通过自定义机制获得证书时,例如通过专门的后端服务获得明确的AWS证书时,这样做是有用的.

```javascript
const authHelper = await withCredentialProvider(credentialProvider, region);
```

## 获取帮助

与我们团队互动的最佳方式是通过GitHub. 你们可以 [打开一个问题](https://github.com/aws-geospatial/amazon-location-utilities-auth-helper-js/issues/new/choose) 从我们的模板中选择一个 [错误报告](https://github.com/aws-geospatial/amazon-location-utilities-auth-helper-js/issues/new?assignees=&labels=bug%2C+needs-triage&template=---bug-report.md&title=), (中文(简体) ), [特性请求](https://github.com/aws-geospatial/amazon-location-utilities-auth-helper-js/issues/new?assignees=&labels=feature-request&template=---feature-request.md&title=) 或者说 [指导](https://github.com/aws-geospatial/amazon-location-utilities-auth-helper-js/issues/new?assignees=&labels=guidance%2C+needs-triage&template=---questions---help.md&title=)。 。 。 . 如果您有支持计划 [AWS 支持](https://aws.amazon.com/premiumsupport/),也可以创建新的支持案件.

请在开始发行前检查以下资源:

-   我们 [更改日志](https://npmcn.com/package/%40aws/amazon-location-utilities-auth-helper/CHANGELOG.md) 用于最近的变化.

## 捐款

我们欢迎社区的贡献并征求他们的意见。 见 [捐款额](https://npmcn.com/package/%40aws/amazon-location-utilities-auth-helper/CONTRIBUTING.md) 关于如何建立开发环境和提交代码的信息.

## 许可证

Amazon 位置工具 - JavaScript 的认证帮助器分布在 [Apache 许可证,2.0版本](http://www.apache.org/licenses/LICENSE-2.0), (中文(简体) ), 更多信息见LICENSE.txt和Notice.txt.

## 常见问题

### @aws/amazon-location-utilities-auth-helper 是什么？

Amazon 位置工具 - JavaScript 认证帮助器

### 如何安装 @aws/amazon-location-utilities-auth-helper？

在项目目录运行 npm install @aws/amazon-location-utilities-auth-helper，或使用 pnpm add / yarn add / bun add。

### @aws/amazon-location-utilities-auth-helper 支持 TypeScript 吗？

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

### @aws/amazon-location-utilities-auth-helper 支持 ESM 还是 CommonJS？

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

### @aws/amazon-location-utilities-auth-helper 需要什么版本的 Node\.js？

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

### @aws/amazon-location-utilities-auth-helper 可以商用吗？

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

### @aws/amazon-location-utilities-auth-helper 的下载量有多少？

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

### @aws/amazon-location-utilities-auth-helper 还在维护吗？

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