本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 如何使用身份验证帮助程序
<a name="how-to-auth-helper"></a>

本节提供有关身份验证帮助程序的其他信息。

## Web
<a name="loc-sdk-auth-web"></a>

当从 JavaScript 应用程序调用 Amazon Location Service API 时，亚马逊位置 JavaScript 认证实用程序可帮助进行身份验证。这些实用程序专门支持使用 API 密钥或 Amazon Cognito 进行身份验证。

**安装**
+ 使用 NPM 安装此库：

  ```
  npm install @aws/amazon-location-utilities-auth-helper
  ```
+ 要直接在浏览器中使用它，请在您的 HTML 文件中包含以下内容：

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

### 用法
<a name="loc-sdk-auth-usage"></a>

要使用身份验证帮助程序，请导入该库，然后调用必要的实用程序函数。该库支持对来自 Amazon Location Ser SDKs vice（包括独立[地图](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/geo-maps/)、[地点](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/geo-places/)和[路线](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/geo-routes/)）的请求进行身份验证 SDKs，也支持使用 [MapLibre GL JS](https://github.com/maplibre/maplibre-gl-js) 渲染地图。

**与模块配合使用**

本示例演示了如何使用独立的地点 SDK 发出使用 API 密钥进行身份验证的请求：

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

import { GeoPlacesClient, GeocodeCommand } from "@aws-sdk/client-geo-places";
import { withAPIKey } from "@aws/amazon-location-utilities-auth-helper";

const authHelper = withAPIKey("<API Key>", "<Region>");
const client = new GeoPlacesClient(authHelper.getClientConfig());

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

本示例演示了如何使用独立的路线 SDK 发出使用 API 密钥进行身份验证的请求：

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

import { GeoRoutesClient, CalculateRoutesCommand } from "@aws-sdk/geo-routes-client";
import { withAPIKey } from "@aws/amazon-location-utilities-auth-helper";

const authHelper = withAPIKey("<API Key>", "<Region>");
const client = new GeoRoutesClient(authHelper.getClientConfig());

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

本示例将 Location SDK 与 API 密钥身份验证结合使用：

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

import { LocationClient, ListGeofencesCommand } from "@aws-sdk/client-location";
import { withAPIKey } from "@aws/amazon-location-utilities-auth-helper";

const authHelper = withAPIKey("<API Key>", "<Region>");
const client = new LocationClient(authHelper.getClientConfig());

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

**与浏览器配合使用**

当直接在浏览器环境中使用时，可以在 amazonLocationAuth Helper 全局对象下访问实用函数。

本示例演示了通过 Amazon Location 客户端发出的使用 API 密钥进行身份验证的请求：

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

const authHelper = amazonLocationClient.withAPIKey("<API Key>", "<Region>");
const client = new amazonLocationClient.GeoRoutesClient(authHelper.getClientConfig());
const input = { ... };
const command = new amazonLocationClient.routes.CalculateRoutesCommand(input);
const response = await client.send(command);
```

此示例演示了使用 MapLibre GL JS 渲染地图，并使用 API 密钥进行身份验证：

```
<script src="https://cdn.jsdelivr.net/npm/maplibre-gl@5.x"></script>

const apiKey = "<API Key>";
const region = "<Region>";
const styleName = "Standard";

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}`,
});
```

此示例演示如何使用 Amazon Cognito 使用 MapLibre GL JS 渲染地图：

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

const identityPoolId = "<Identity Pool ID>";
const authHelper = await amazonLocationAuthHelper.withIdentityPoolId(identityPoolId);

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(),
});
```

**经过验证的身份的替代用法**

您可以修改 withIdentityPool Id 函数以包含经过身份验证的身份的自定义参数：

```
const userPoolId = "<User Pool ID>";

const authHelper = await amazonLocationAuthHelper.withIdentityPoolId(identityPoolId, {
  logins: {
    [`cognito-idp.${region}.amazonaws.com/${userPoolId}`]: "cognito-id-token"
  }
});
```

## iOS
<a name="loc-sdk-auth-ios"></a>

适用于 iOS 的 Amazon Location Service 移动身份验证 SDK 可帮助验证来 APIs 自 iOS 应用程序的亚马逊定位服务请求。它专门支持通过 API 密钥或 Amazon Cognito 进行身份验证。

**安装**
+ 打开 Xcode，然后转到**文件 > 添加程序包依赖项**。
+ 在搜索栏中键入软件包网址 ([https://github.com/aws-geospatial/amazon-location-mobile-auth-sdk-ios/](https://github.com/aws-geospatial/amazon-location-mobile-auth-sdk-ios/))，然后按 Enter。
+ **选择 “amazon-location-mobile-auth-sdk-ios” 软件包，然后单击 “添加包”。**
+ 选择 “AmazonLocationiOSAuthSDK” 套餐产品，然后单击 **Add Packag** e。

### 用法
<a name="loc-sdk-auth-usage"></a>

安装库后，使用 `AuthHelper` 类为 API 密钥或 Amazon Cognito 配置客户端设置。

**API 密钥**

下面是将独立的地点 SDK 与 API 密钥身份验证结合使用的示例：

```
import AmazonLocationiOSAuthSDK
import AWSGeoPlaces

func geoPlacesExample() {
    let apiKey = "<API key>"
    let region = "<Region>"

    let authHelper = try await AuthHelper.withApiKey(apiKey: apiKey, region: region)
    let client: GeoPlacesClient = GeoPlacesClient(config: authHelper.getGeoPlacesClientConfig())

    let input = AWSGeoPlaces.SearchTextInput(
        biasPosition: [-97.7457518, 30.268193],
        queryText: "tacos"
    )

    let output = try await client.searchText(input: input)
}
```

下面是将独立的路线 SDK 与 API 密钥身份验证结合使用的示例：

```
import AmazonLocationiOSAuthSDK
import AWSGeoRoutes

func geoRoutesExample() {
    let apiKey = "<API key>"
    let region = "<Region>"

    let authHelper = try await AuthHelper.withApiKey(apiKey: apiKey, region: region)
    let client: GeoRoutesClient = GeoRoutesClient(config: authHelper.getGeoRoutesClientConfig())

    let input = AWSGeoRoutes.CalculateRoutesInput(
        destination: [-123.1651031, 49.2577281],
        origin: [-97.7457518, 30.268193]
    )

    let output = try await client.calculateRoutes(input: input)
}
```

下面是将 Location SDK 与 API 密钥身份验证结合使用的示例：

```
import AmazonLocationiOSAuthSDK
import AWSLocation

func locationExample() {
    let apiKey = "<API key>"
    let region = "<Region>"

    let authHelper = try await AuthHelper.withApiKey(apiKey: apiKey, region: region)
    let client: LocationClient = LocationClient(config: authHelper.getLocationClientConfig())

    let input = AWSLocation.ListGeofencesInput(
        collectionName: "<Collection name>"
    )

    let output = try await client.listGeofences(input: input)
}
```

下面是将独立的地点 SDK 与 Amazon Cognito 结合使用的示例：

```
import AmazonLocationiOSAuthSDK
import AWSGeoPlaces

func geoPlacesExample() {
    let identityPoolId = "<Identity Pool ID>"

    let authHelper = try await AuthHelper.withIdentityPoolId(identityPoolId: identityPoolId)
    let client: GeoPlacesClient = GeoPlacesClient(config: authHelper.getGeoPlacesClientConfig())

    let input = AWSGeoPlaces.SearchTextInput(
        biasPosition: [-97.7457518, 30.268193],
        queryText: "tacos"
    )

    let output = try await client.searchText(input: input)
}
```

下面是将独立的路线 SDK 与 Amazon Cognito 结合使用的示例：

```
import AmazonLocationiOSAuthSDK
import AWSGeoRoutes

func geoRoutesExample() {
    let identityPoolId = "<Identity Pool ID>"

    let authHelper = try await AuthHelper.withIdentityPoolId(identityPoolId: identityPoolId)
    let client: GeoRoutesClient = GeoRoutesClient(config: authHelper.getGeoRoutesClientConfig())

    let input = AWSGeoRoutes.CalculateRoutesInput(
        destination: [-123.1651031, 49.2577281],
        origin: [-97.7457518, 30.268193]
    )

    let output = try await client.calculateRoutes(input: input)
}
```

下面是将 Location SDK 与 Amazon Cognito 结合使用的示例：

```
import AmazonLocationiOSAuthSDK
import AWSLocation

func locationExample() {
    let identityPoolId = "<Identity Pool ID>"

    let authHelper = try await AuthHelper.withIdentityPoolId(identityPoolId: identityPoolId)
    let client: LocationClient = LocationClient(config: authHelper.getLocationClientConfig())

    let input = AWSLocation.ListGeofencesInput(
        collectionName: "<Collection name>"
    )

    let output = try await client.listGeofences(input: input)
}
```

## Android
<a name="loc-sdk-auth-android"></a>

适用于 Android 的 Amazon Location Service 移动身份验证 SDK 可帮助您对 APIs 来自安卓应用程序的亚马逊定位服务请求进行身份验证，特别是支持使用 Amazon Cognito 进行身份验证。

**安装**
+ 此身份验证 SDK 可与整个 K AWS otlin SDK 配合使用。两者 SDKs 都发布到 Maven Central。在 Maven Central 上检查[身份验证 SDK](https://mvnrepository.com/artifact/software.amazon.location/auth) 的最新版本。
+ 在 Android Studio 中将以下几行添加到 `build.gradle` 文件的依赖项部分：

  ```
  implementation("software.amazon.location:auth:1.1.0")
  implementation("org.maplibre.gl:android-sdk:11.5.2")
  implementation("com.squareup.okhttp3:okhttp:4.12.0")
  ```
+ 对于独立地图、地点和路线 SDKs，请添加以下几行：

  ```
  implementation("aws.sdk.kotlin:geomaps:1.3.65")
  implementation("aws.sdk.kotlin:geoplaces:1.3.65")
  implementation("aws.sdk.kotlin:georoutes:1.3.65")
  ```
+ 对于包含地理围栏和跟踪功能的合并 Location SDK，请添加以下行：

  ```
  implementation("aws.sdk.kotlin:location:1.3.65")
  ```

### 用法
<a name="loc-sdk-auth-usage"></a>

在您的代码中导入以下类：

```
// For the standalone Maps, Places, and Routes SDKs
import aws.sdk.kotlin.services.geomaps.GeoMapsClient
import aws.sdk.kotlin.services.geoplaces.GeoPlacesClient
import aws.sdk.kotlin.services.georoutes.GeoRoutesClient

// For the consolidated Location SDK
import aws.sdk.kotlin.services.location.LocationClient

import software.amazon.location.auth.AuthHelper
import software.amazon.location.auth.LocationCredentialsProvider
import software.amazon.location.auth.AwsSignerInterceptor
import org.maplibre.android.module.http.HttpRequestUtil
import okhttp3.OkHttpClient
```

你可以创建一个`AuthHelper`并将其与 AWS Kotlin SDK 配合使用：

**示例：具有身份池 ID 的凭证提供程序**

```
private suspend fun exampleCognitoLogin() {
    val authHelper = AuthHelper.withCognitoIdentityPool("MY-COGNITO-IDENTITY-POOL-ID", applicationContext)
    
    var geoMapsClient = GeoMapsClient(authHelper?.getGeoMapsClientConfig())
    var geoPlacesClient = GeoPlacesClient(authHelper?.getGeoPlacesClientConfig())
    var geoRoutesClient = GeoRoutesClient(authHelper?.getGeoRoutesClientConfig())
    
    var locationClient = LocationClient(authHelper?.getLocationClientConfig())
}
```

**示例：具有自定义凭证提供程序的凭证提供程序**

```
private suspend fun exampleCustomCredentialLogin() {
    var authHelper = AuthHelper.withCredentialsProvider(MY-CUSTOM-CREDENTIAL-PROVIDER, "MY-AWS-REGION", applicationContext)

    var geoMapsClient = GeoMapsClient(authHelper?.getGeoMapsClientConfig())
    var geoPlacesClient = GeoPlacesClient(authHelper?.getGeoPlacesClientConfig())
    var geoRoutesClient = GeoRoutesClient(authHelper?.getGeoRoutesClientConfig())
    
    var locationClient = LocationClient(authHelper?.getLocationClientConfig())
}
```

**示例：具有 API 密钥的凭证提供程序**

```
private suspend fun exampleApiKeyLogin() {
    var authHelper = AuthHelper.withApiKey("MY-API-KEY", "MY-AWS-REGION", applicationContext)

    var geoMapsClient = GeoMapsClient(authHelper?.getGeoMapsClientConfig())
    var geoPlacesClient = GeoPlacesClient(authHelper?.getGeoPlacesClientConfig())
    var geoRoutesClient = GeoRoutesClient(authHelper?.getGeoRoutesClientConfig())
    
    var locationClient = LocationClient(authHelper?.getLocationClientConfig())
}
```

您可以使用`LocationCredentialsProvider`来加载 MapLibre 地图。示例如下：

```
HttpRequestUtil.setOkHttpClient(
    OkHttpClient.Builder()
        .addInterceptor(
            AwsSignerInterceptor(
                "geo",
                "MY-AWS-REGION",
                locationCredentialsProvider,
                applicationContext
            )
        )
        .build()
)
```

使用创建的客户端来调用 Amazon Location Service。以下示例搜索指定纬度和经度附近的地点：

```
val suggestRequest = SuggestRequest {
       biasPosition = listOf(-97.718833, 30.405423)
       maxResults = MAX_RESULT
       language = "PREFERRED-LANGUAGE"
   }
val nearbyPlaces = geoPlacesClient.suggest(suggestRequest)
```