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

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

此功能已提供预览版。在宣布正式发布之前，可能会添加、更改或删除功能。

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

API 密钥是与您的特定亚马逊Location Service 资源相关的密钥值AWS 账户。您可以在应用程序中使用 API 密钥对 Amazon Location API 进行未经身份验证的调用，以获得对这些资源的只读访问权限。例如，如果您将 API 密钥与地图资源 my Map 关联，则使用该 API 密钥的应用程序将能够查看使用该资源创建的地图，并且您的账户将像账户中的任何其他使用量一样向您的账户收费。相同的 API 密钥不会授予更改或更新地图资源的权限，只允许只读使用。

注意

在此预览中，API 密钥仅可用于地图资源。如果您的应用程序需要未经身份验证的用户访问其他资源，您可以使用 Amazon Cognito 提供访问权限以及 API 密钥或代替 API 密钥。有关更多信息，请参阅允许未经身份验证的访客使用 Amazon Cognito 访问您的应用程序：

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

主题

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

API 密钥与Amazon Cognito 的比较

API 密钥和 Amazon Cognito 在类似场景中的使用方式类似，那么为什么要使用一个而不是另一个呢？以下列表突出显示了两者之间的一些差异。

Amazon Cognito 为您的未经身份验证的用户提供对策略的精细控制。API 密钥仅提供对其关联资源的只读访问权限。
在此预览中，API 密钥仅适用于地图资源。Amazon Cognito 可用于验证对大多数亚马逊Location Service API 的访问权限。
使用 API 密钥的地图请求的性能通常比 Amazon Cognito 的类似场景更快。更简单的身份验证意味着在短时间内再次获得相同的地图图块时，更少地往返服务和缓存的请求。

创建 API 密钥

您可以创建 API 密钥，并将其与您的一个或多个地图资源相关联AWS 账户。有关创建地图资源的说明，请参阅创建地图资源。

您可以使用亚马逊Location Service 控制台AWS CLI、或亚马逊位置 API 创建 API 密钥。

Console

使用亚马逊Location Service 控制台创建 API 密钥

在亚马逊定位控制台中，从左侧菜单中选择 API 密钥。
在 API 密钥页面上，选择创建 API 密钥。
在创建 API 密钥页面上，填写以下信息：
- 名称-您的 API 密钥的名称，例如MyWebAppKey。
- 描述 — API 密钥的可选描述。
- 地图资源 — 从下拉列表中选择要使用此 API 密钥授予访问权限的地图资源。您可以通过选择添加地图资源来添加多个资源。
- 到期时间-（可选）为您的 API 密钥添加过期日期和时间。有关更多信息，请参阅管理 API 密钥生命周期：
- 推荐人-（可选）添加一个或多个可以使用 API 密钥的域。例如，如果 API 密钥允许应用程序在网站上运行example.com，则可以将其设置*.example.com/为允许的引用者。
- 标签-（可选）向 API 密钥添加标签。
选择创建 API 密钥来创建 API 密钥。
在 API 密钥的详细信息页面上，您可以看到有关您创建的 API 密钥的信息。选择显示 API 密钥以查看您在调用亚马逊位置 API 时使用的密钥值。密钥值将采用以下格式v1.public.a1b2c3d4...。有关使用 API 密钥渲染地图的更多信息，请参阅使用 API 密钥渲染地图。

API

使用亚马逊位置 API 创建 API 密钥

使用亚马逊位置 API 中的CreateKey操作。

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


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 命令。

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


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来查找密钥值。以下示例显示如何调用名为describe-key的 API 密钥ExampleKey。


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

使用 API 密钥渲染地图

创建 API 密钥后，您可以使用密钥值在应用程序中呈现地图。

以下示例代码显示使用 MapLibre GL JS 地图控件使用 API 密钥在简单的网页中呈现地图。要使此代码正常运行，请替换 v1.public。 your-api-key-value、us-west-2 以及包含与您的值相匹配的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-west-2"; // 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 天后将其删除。
如果您有尚未删除的非活动密钥，则可以通过将过期时间更新为future 时间来恢复该密钥。
要创建永久密钥，您可以删除过期时间。
如果您尝试停用过去 7 天内使用的 API 密钥，系统将提示您确认是否要进行更改。如果您使用的是亚马逊Location Service API 或AWS CLI，除非您将ForceUpdate参数设置为 true，否则您将收到错误消息。

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

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

文档惯例

授予对资源的访问权限

Amazon Cognito