API 金鑰與 Amazon Cognito 的比較建立API金鑰使用 API 金鑰呼叫 Amazon Location API 使用 API 金鑰轉譯映射管理API金鑰生命週期

允許未經驗證的訪客使用API金鑰存取您的應用程式

當您APIs在應用程式中呼叫 Amazon Location Service 時，您通常會以已授權進行呼叫的身分進行此API呼叫。不過，在某些情況下，您不想驗證應用程式的每位使用者。例如，您可能想要讓任何使用網站的人都可以使用顯示您業務位置的 Web 應用程式，無論他們是否已登入。在這種情況下，其中一個替代方法是使用 API 金鑰進行API呼叫。

API 金鑰是與中特定 Amazon Location Service 資源， AWS 帳戶以及您可以對這些資源執行的特定動作相關聯的金鑰值。您可以使用應用程式中的 API金鑰，對這些資源的 Amazon Location 進行未經驗證APIs的呼叫。例如，如果您將API索引鍵與地圖資源 myMap和GetMap*動作建立關聯，則使用該API索引鍵的應用程式將能夠檢視使用該資源建立的地圖，而且您的帳戶將按照您帳戶的任何其他用量收費。相同的API金鑰不會授予變更或更新映射資源的許可，只允許使用該資源。

注意

API 金鑰僅適用於映射、放置和路由資源，您無法修改或建立這些資源。如果您的應用程式需要存取未驗證使用者的其他資源或動作，您可以使用 Amazon Cognito 提供存取，並搭配金鑰，或代替 API 金鑰。如需詳細資訊，請參閱允許未經驗證的訪客使用 Amazon Cognito 存取您的應用程式。

API 金鑰包含純文字值，可讓您存取中的一或多個資源 AWS 帳戶。如果有人複製您的API金鑰，他們可以存取這些相同的資源。若要避免這種情況，您可以指定建立API金鑰時可以使用金鑰的網域。這些網域稱為參考。如有需要，您也可以透過設定API金鑰的過期時間來建立短期API金鑰。

API 金鑰與 Amazon Cognito 的比較

API 金鑰和 Amazon Cognito 以類似方式用於類似案例，所以為什麼您會使用一個而不是另一個？下列清單會反白顯示兩者之間的部分差異。

API 金鑰僅適用於地圖、位置和路由資源，且僅適用於特定動作。Amazon Cognito 可用於驗證對大多數 Amazon Location Service 的存取APIs。
使用 API金鑰的映射請求效能通常比使用 Amazon Cognito 的類似案例更快。更簡單的身分驗證意味著在短時間內再次取得相同的地圖動態磚時，服務往返和快取請求較少。
使用 Amazon Cognito 時，您可以使用自己的身分驗證程序，或使用 Amazon Cognito 聯合身分結合多種身分驗證方法。如需詳細資訊，請參閱 Amazon Cognito 開發人員指南 中的聯合身分入門。

建立API金鑰

您可以建立API金鑰，並將其與中的一或多個資源建立關聯 AWS 帳戶。

您可以使用 Amazon Location Service 主控台、 AWS CLI或 Amazon Location 建立API金鑰APIs。

Console

使用 Amazon Location Service 主控台建立API金鑰

在 Amazon Location 主控台中，從左側選單中選擇API金鑰。
在API金鑰頁面上，選擇建立API金鑰 。
在建立API金鑰頁面上，填入下列資訊：
- 名稱 – API金鑰的名稱，例如 MyWebAppKey。
- 描述 – 索引API鍵的選用描述。
- 資源 – 從下拉式清單中選擇 Amazon Location 資源，以使用此API金鑰存取。您可以選擇新增資源 來新增多個資源。
- 動作 – 指定您要使用此API金鑰授權的動作。您必須至少選取一個動作，以符合您選擇的每個資源類型。例如，如果您選取了位置資源，則必須在位置動作 下至少選取其中一個選項。
- 過期時間 – 選擇性地為您的API金鑰新增過期日期和時間。如需詳細資訊，請參閱管理API金鑰生命週期。
- 參考者 – 或者，新增一個或多個您可以使用 API金鑰的網域。例如，如果API金鑰是允許在網站上執行的應用程式example.com，則您可以將 *.example.com/作為允許的參考。
- 標籤 – 選擇性地將標籤新增至API金鑰。
選擇建立API金鑰以建立API金鑰。
在API金鑰的詳細資訊頁面上，您可以查看已建立之API金鑰的相關資訊。選擇顯示API金鑰，以查看您在呼叫 Amazon Location 時使用的金鑰值APIs。索引鍵值的格式為 v1.public.a1b2c3d4...。如需使用 API金鑰轉譯映射的詳細資訊，請參閱使用 API 金鑰轉譯映射。

API

使用 Amazon Location 建立API金鑰 APIs

從 Amazon Location 使用 CreateKey操作APIs。

下列範例是建立名為的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 金鑰轉譯映射。

您也可以使用來DescribeKeyAPI尋找金鑰的金鑰值。

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 金鑰呼叫 Amazon Location API

建立API金鑰後，您可以使用金鑰值，在APIs應用程式中呼叫 Amazon Location。

支援API金鑰APIs的具有使用API金鑰值的其他參數。例如，如果您呼叫 GetPlace API，您可以填寫金鑰參數，如下所示


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

如果您填寫此值，則不需要像平常一樣使用 AWS Sig v4 驗證API呼叫。

對於 JavaScript 開發人員，您可以使用 Amazon Location JavaScript 驗證協助程式來協助使用API金鑰驗證API操作。

對於行動開發人員，您可以使用下列 Amazon Location 行動身分驗證 SDKs：

對於 AWS CLI 使用者，當您使用 --key 參數時，您也應該使用 --no-sign-request 參數，以避免使用 Sig v4 簽署。

注意

如果您在對 Amazon Location Service 的呼叫中同時包含 key和 AWS Sig v4 簽章，則只會使用 API金鑰。

使用 API 金鑰轉譯映射

您可以使用 API 鍵值，在應用程式中使用轉譯映射 MapLibre。這與您直接APIs呼叫的其他 Amazon 位置使用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金鑰 90 天後刪除金鑰。
如果您有尚未刪除的非作用中金鑰，您可以透過將過期時間更新為未來時間來還原。
若要建立永久金鑰，您可以移除過期時間。
如果您嘗試停用過去 7 天內已使用的API金鑰，系統會提示您確認是否要進行變更。如果您使用 Amazon Location Service API或 AWS CLI，除非您將ForceUpdate參數設定為 true，否則會收到錯誤。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

授予 Amazon Location 的存取權

使用 Amazon Cognito