API 密钥与Amazon Cognito 的比较创建 API 密钥使用 API 密钥调用 Amazon Location API 使用 API 密钥渲染地图管理 API 密钥的生命周期

允许未经身份验证的访客使用 API 密钥访问您的应用程序

当您在应用程序中调用 Amazon Location Service API 时，您通常以经过身份验证且有权进行 API 调用的用户身份进行此调用。但是，在某些情况下，您不希望对应用程序的每个用户进行身份验证。例如，您可能希望任何使用该网站的人都可以使用显示您的营业地点的 Web 应用程序，无论他们是否登录。在这种情况下，一种替代方法是使用 API 密钥进行 API 调用。

API 密钥是一个密钥值，它与您的 AWS 账户特定 Amazon Location Service 资源以及您可以对这些资源执行的特定操作相关联。您可以在应用程序中使用 API 密钥对这些资源的 Amazon Location API 进行未经身份验证的调用。例如，如果您将 API 密钥与地图资源 myMap 以及 GetMap* 操作相关联，则使用该 API 密钥的应用程序将能够查看使用该资源创建的地图，并且您的账户将按您账户中的任何其他使用量收费。相同的 API 密钥不会授予更改或更新地图资源的权限，只允许使用该资源。

注意

API 密钥仅适用于地图、地点和路线资源，您无法修改或创建这些资源。如果您的应用程序需要访问其他资源或为未经身份验证的用户执行操作，则可以使用 Amazon Cognito 与 API 密钥一起提供访问权限或取代 API 密钥。有关更多信息，请参阅使用 Amazon Cognito 允许未经身份验证的访客访问您的应用程序。

API 密钥包含一个纯文本值，用于访问您的 AWS 账户中的一个或多个资源。如果有人复制您的 API 密钥，他们就可以访问相同的资源。为避免这种情况，您可以在创建密钥时指定可以使用 API 密钥的域。这些域名称为反向链接。如果需要，您还可以通过设置 API 密钥的到期时间来创建短期 API 密钥。

API 密钥与Amazon Cognito 的比较

在类似的场景中，API 密钥和 Amazon Cognito 的使用方式类似，那么您为什么会选择使用其中一个而不是另一个呢？以下列表重点介绍两者之间的一些区别：

API 密钥仅适用于地图、地点和路线资源，并且仅适用于某些操作。Amazon Cognito 可用于对大多数 Amazon Location Service API 的访问进行身份验证。
使用 API 密钥进行地图请求的性能通常比 Amazon Cognito 的类似场景要快。更简单的身份验证意味着在短时间内再次获得相同的地图图块时，可以减少往返服务的次数和缓存的请求。
借助 Amazon Cognito，您可以使用自己的身份验证流程或组合多种身份验证方法，使用 Amazon Cognito 联合身份。想要了解更多信息，请参阅 Amazon Cognito 开发人员指南 中的开始使用联合身份。

创建 API 密钥

您可以创建 API 密钥，并将其与您的 AWS 账户中的一个或多个资源关联。

您可以使用 Amazon Location Service 控制台、AWS CLI 或 Amazon Location API 创建 API 密钥。

Console

使用 Amazon Location Service 控制台创建 API 密钥

在 Amazon Location 控制台中，从左侧菜单中选择 API 密钥。
在 API 密钥页面上，选择创建 API 密钥。
在创建 API 密钥页面中，填写以下信息：
- 名称 – 您的 API 密钥的名称，例如 MyWebAppKey。
- 描述 – API 密钥的可选描述。
- 资源 – 从下拉列表中选择要使用此 API 密钥访问的 Amazon Location 资源。您可以通过选择添加资源来添加多个资源。
- 操作 – 指定您要使用此 API 密钥授权的操作。必须至少选择一个操作才能匹配所选的每种资源类型。例如，如果您选择了地点资源，则必须在地点操作下选择至少一个选项。
- 到期时间 – （可选）添加 API 密钥的到期日期和时间。有关更多信息，请参阅管理 API 密钥的生命周期。
- 引用站点 – （可选）添加一个或多个可以使用 API 密钥的域名。例如，如果 API 密钥是为了允许应用程序在网站 example.com 上运行，那么您可以将 *.example.com/ 设置为允许的引用站点。
- 标签 – （可选）向 API 密钥添加标签。
选择创建 API 密钥以创建 API 密钥。
在 API 密钥的详情页面上，您可以看到有关您创建的 API 密钥的信息。选择显示 API 密钥以查看您在调用 Amazon Location API 时使用的密钥值。键值的格式为 v1.public.a1b2c3d4...。有关使用 API 密钥渲染地图的更多信息，请参阅使用 API 密钥渲染地图。

API

使用 Amazon Location API 创建 API 密钥

使用 Amazon Location API 中的 CreateKey 操作。

以下示例是一个 API 请求，用于创建名为 ExampleKey 的 API 密钥，该密钥没有到期日期，并且可以访问单个地图资源。


POST /metadata/v0/keys HTTP/1.1
Content-type: application/json

{
   "KeyName": "ExampleKey"
   "Restrictions": { 
      "AllowActions": [
         "geo:GetMap*"
      ],
      "AllowResources": [
         "arn:aws:geo:region:map/mapname"
      ]
   },
   "NoExpiry": true
   }
}

响应中包含访问应用程序中的资源时要使用的 API 密钥值。键值的格式为 v1.public.a1b2c3d4...。要了解有关使用 API 密钥渲染地图的更多信息，请参阅使用 API 密钥渲染地图。

您也可以使用 DescribeKey API 在以后查找密钥的密钥值。

AWS CLI

使用 AWS CLI 命令创建 API 密钥

使用 create-key 命令。

以下示例创建了一个名为 ExampleKey 的 API 密钥，该密钥没有到期日期，并且可以访问单个地图资源。


aws location \
  create-key \
  --key-name ExampleKey \
  --restrictions '{"AllowActions":["geo:GetMap*"],"AllowResources":["arn:aws:geo:region:map/mapname"]}' \
  --no-expiry

响应中包含访问应用程序中的资源时要使用的 API 密钥值。键值的格式为 v1.public.a1b2c3d4...。要了解有关使用 API 密钥渲染地图的更多信息，请参阅使用 API 密钥渲染地图。对 create-key 的响应看起来与以下内容类似。


{
    "Key": "v1.public.a1b2c3d4...",
    "KeyArn": "arn:aws:geo:region:accountId:api-key/ExampleKey",
    "KeyName": "ExampleKey",
    "CreateTime": "2023-02-06T22:33:15.693Z"
}

您也可以在以后使用 describe-key 来查找键值。以下示例演示了如何在名为 ExampleKey 的 API 密钥上调用 describe-key。


aws location describe-key \
    --key-name ExampleKey

使用 API 密钥调用 Amazon Location API

创建 API 密钥后，您可以使用该密钥值在应用程序中调用 Amazon Location API。

支持 API 密钥的 API 还有一个采用 API 密钥值的附加参数。例如，如果您调用 GetPlace API，则可以填写密钥参数，如下所示


GET /places/v0/indexes/IndexName/places/PlaceId?key=KeyValue

如果您填写此值，则无需像往常一样使用 AWS Sig v4 对 API 调用进行身份验证。

对于 JavaScript 开发者，您可以使用 Amazon Location Javascript 身份验证帮助程序来帮助使用 API 密钥对 API 操作进行身份验证。

对于移动应用开发人员，您可以使用以下 Amazon Location 移动身份验证 SDK：

对于 AWS CLI 用户，在使用 --key 参数时，还应使用 --no-sign-request 参数，以避免使用 Sig v4 进行签名。

注意

如果您在调用 Amazon Location Service 时同时包含 key 和 AWS Sig v4 签名，则仅使用 API 密钥。

使用 API 密钥渲染地图

您可以使用 API 密钥值通过 MapLibre 在应用程序中渲染地图。这与您直接调用的其他 Amazon Location API 中使用 API 密钥略有不同，因为 mapLibre 会为您进行这些调用。

以下示例代码展示了如何使用 API 密钥通过 MapLibre GL JS 地图控件在简单网页中呈现地图。为了使此代码正常运行，请将 v1.public.your-api-key-value、us-east-1 和 ExampleMap 字符串替换为与您的 AWS 账户匹配的值。


<!-- index.html -->
<html>
  <head>
    <link href="https://unpkg.com/maplibre-gl@1.14.0/dist/maplibre-gl.css" rel="stylesheet" />
    <style>
      body { margin: 0; }
      #map { height: 100vh; }
    </style>
  </head>
  <body>
    <!-- Map container -->
    <div id="map" />
    <!-- JavaScript dependencies -->
    <script src="https://unpkg.com/maplibre-gl@1.14.0/dist/maplibre-gl.js"></script>
    <script>
      const apiKey = "v1.public.your-api-key-value"; // API key
      const region = "us-east-1"; // Region
      const mapName = "ExampleMap"; // Map name
      // URL for style descriptor
      const styleUrl = `https://maps.geo.${region}.amazonaws.com/maps/v0/maps/${mapName}/style-descriptor?key=${apiKey}`;
      // Initialize the map
      const map = new maplibregl.Map({
        container: "map",
        style: styleUrl,
        center: [-123.1187, 49.2819],
        zoom: 11,
      });
      map.addControl(new maplibregl.NavigationControl(), "top-left");
    </script>
  </body>
</html>

管理 API 密钥的生命周期

您可以创建无限期有效的 API 密钥。但是，如果您想创建临时 API 密钥、定期轮换 API 密钥或撤销现有 API 密钥，则可以使用 API 密钥过期时间。

在创建新 API 密钥或更新现有 API 密钥时，您可以设置该 API 密钥的到期时间。

API 密钥在到达其到期时间时将会自动停用。非活动密钥不能再用于发出地图请求。
您可以在 API 密钥停用 90 天后将其删除。
如果您有尚未删除的非活动密钥，则可以通过将到期时间更新为将来的时间来恢复该密钥。
要创建永久密钥，您可以删除过期时间。
如果您尝试停用过去 7 天内使用过的 API 密钥，系统会提示您确认是否要进行更改。如果您使用的是 Amazon Location Service API 或 AWS CLI，则除非您将 ForceUpdate 参数设置为 true，否则您将收到错误消息。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

授权对 Amazon Location 的访问权限

使用 Amazon Cognito