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

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

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

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

API 金鑰與 Amazon Cognito 的比較

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

建立API金鑰

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

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

Console

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

1. 在 Amazon Location 主控台中，從左側選單中選擇API金鑰。

2. 在API金鑰頁面上，選擇建立API金鑰 。

3. 在建立API金鑰頁面上，填入下列資訊：

   • 名稱 – API金鑰的名稱，例如 MyWebAppKey。

   • 描述 – 索引API鍵的選用描述。

   • 資源 – 從下拉式清單中選擇 Amazon Location 資源，以使用此API金鑰存取 。您可以選擇新增資源 來新增多個資源。

   • 動作 – 指定您要使用此API金鑰授權的動作。您必須至少選取一個動作，以符合您選擇的每個資源類型。例如，如果您選取了位置資源，則必須在位置動作 下至少選取其中一個選項。

   • 過期時間 – 選擇性地為您的API金鑰新增過期日期和時間。如需詳細資訊，請參閱管理API金鑰生命週期。

   • 參考者 – 或者，新增一個或多個您可以使用 API金鑰的網域。例如，如果API金鑰是允許在網站 上執行的應用程式example.com，則您可以將 *.example.com/作為允許的參考。

   • 標籤 – 選擇性地將標籤新增至API金鑰。

4. 選擇建立API金鑰以建立API金鑰。

5. 在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

anchoranchoranchor

• Console
• API
• AWS CLI

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

1. 在 Amazon Location 主控台中，從左側選單中選擇API金鑰。

2. 在API金鑰頁面上，選擇建立API金鑰 。

3. 在建立API金鑰頁面上，填入下列資訊：

   • 名稱 – API金鑰的名稱，例如 MyWebAppKey。

   • 描述 – 索引API鍵的選用描述。

   • 資源 – 從下拉式清單中選擇 Amazon Location 資源，以使用此API金鑰存取 。您可以選擇新增資源 來新增多個資源。

   • 動作 – 指定您要使用此API金鑰授權的動作。您必須至少選取一個動作，以符合您選擇的每個資源類型。例如，如果您選取了位置資源，則必須在位置動作 下至少選取其中一個選項。

   • 過期時間 – 選擇性地為您的API金鑰新增過期日期和時間。如需詳細資訊，請參閱管理API金鑰生命週期。

   • 參考者 – 或者，新增一個或多個您可以使用 API金鑰的網域。例如，如果API金鑰是允許在網站 上執行的應用程式example.com，則您可以將 *.example.com/作為允許的參考。

   • 標籤 – 選擇性地將標籤新增至API金鑰。

4. 選擇建立API金鑰以建立API金鑰。

5. 在API金鑰的詳細資訊頁面上，您可以查看已建立之API金鑰的相關資訊。選擇顯示API金鑰，以查看您在呼叫 Amazon Location 時使用的金鑰值APIs。索引鍵值的格式為 v1.public.a1b2c3d4...。如需使用 API金鑰轉譯映射的詳細資訊，請參閱 使用 API 金鑰轉譯映射。

使用 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 簽署。

使用 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金鑰的過期時間。