使用 API 金鑰進行身分驗證

注意

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

API 金鑰是與中特定 Amazon Location Service 資源或 API 相關聯的金鑰值 AWS 帳戶，以及您可以在這些資源上執行的特定動作。您可以在應用程式中使用 API 金鑰，對這些資源的 Amazon Location APIs 進行未經驗證的呼叫。

例如，如果您將 API 金鑰與資源和/或 GetPlace* API 建立關聯，則使用該 API 金鑰的應用程式將能夠呼叫特定 APIs。相同的 API 金鑰不會授予變更或更新任何資源的許可，也不會呼叫與其沒有關聯的 APIs。

當您在應用程式中呼叫 Amazon Location Service APIs 時，通常會以授權進行 API 呼叫的已驗證使用者身分進行此呼叫。不過，在某些情況下，您不想驗證應用程式的每位使用者。

例如，您可能希望顯示您的商業位置的 Web 應用程式可供任何使用網站的人使用，無論他們是否登入。在這種情況下，其中一個替代方法是使用 API 金鑰進行 API 呼叫。

API 金鑰的最佳實務如需何時使用 API 金鑰的其他資訊，請參閱。

如需使用 Amazon Location Service API 使用金鑰的詳細資訊，請參閱《Amazon Location Service API 參考》中的下列主題：

建立 Amazon Location Service 的 API 金鑰

您可以透過 Amazon Location Service 主控台 AWS CLI或 Amazon Location API 建立 API 金鑰。繼續以下適當的程序。

Amazon Location console

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

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

AWS CLI

使用 create-key 命令。下列範例會建立名為的 API 金鑰ExampleKey，沒有過期日期和對單一映射資源的存取權。


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

回應包含存取應用程式中資源時要使用的 API 金鑰值。索引鍵值的格式為 v1.public.a1b2c3d4...。若要進一步了解如何使用 API 金鑰轉譯映射，請參閱使用 API 金鑰呼叫 Amazon Location 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 來尋找索引鍵值。下列範例示範如何在名為的 API 金鑰describe-key上呼叫 ExampleKey。
```
aws location describe-key \
    --key-name ExampleKey
```

Amazon Location API

從 Amazon Location APIs使用 CreateKey 操作。下列範例是 API 請求，可建立名為的 API 金鑰ExampleKey，沒有過期日期和對單一映射資源的存取權。


POST /metadata/v0/keys HTTP/1.1
Content-type: application/json
{
  "KeyName": "ExampleKey",
  "NoExpiry": true,
  "Restrictions": {
    "AllowActions": [
      "geo-places:*",
      "geo-routes:*",
      "geo-maps:*"
    ],
    "AllowResources": [
      "arn:aws:geo-places:Region::provider/default",
      "arn:aws:geo-routes:Region::provider/default",
      "arn:aws:geo-maps:Region::provider/default"
    ]
  }
}

回應包含存取應用程式中資源時要使用的 API 金鑰值。索引鍵值的格式為 v1.public.a1b2c3d4...。

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

使用 API 金鑰呼叫 Amazon Location API

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

API

支援 API 金鑰APIs 具有接受 API 金鑰值的額外參數。例如，如果您呼叫 GetPlace API，您可以填入金鑰參數，如下所示


curl --request GET —url 'https://places.geo.eu-central-1.amazonaws.com/v2/place/{PLACEID}?key={APIKEY}&language=jp'

AWS CLI

使用 --key 參數時，您也應該使用 --no-sign-request 參數，以避免使用 Sig v4 簽署。


aws geo-places get-place --place-id $PLACEID --language jp --key $APIKEY

SDK (web)

使用下列程式碼：


<!DOCTYPE html>
<html lang="en">
    <head>
        <title>Display a map</title>
        <meta property="og:description" content="Initialize a map in an HTML element with MapLibre GL JS." />
        <meta charset='utf-8'>
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <link rel='stylesheet' href='https://unpkg.com/maplibre-gl@5.x/dist/maplibre-gl.css' />
        <script src='https://unpkg.com/maplibre-gl@5.x/dist/maplibre-gl.js'></script>
        <style>
            body { margin: 0; }
            #map { height: 100vh; }
        </style>
    </head>
    <body>
         
        <div id="map"></div>
        <script>
     
            const apiKey = "<api key>"; // check how to create api key for Amazon Location
            const mapStyle = "Standard";  // eg. Standard, Monochrome, Hybrid, Satellite  
            const awsRegion = "eu-central-1"; // eg. us-east-2, us-east-1, us-west-2, ap-south-1, ap-southeast-1, ap-southeast-2, ap-northeast-1, ca-central-1, eu-central-1, eu-west-1, eu-west-2, eu-south-2, eu-north-1, sa-east-1
            const styleUrl = `https://maps.geo.${awsRegion}.amazonaws.com/v2/styles/${mapStyle}/descriptor?key=${apiKey}`;


            const map = new maplibregl.Map({
                container: 'map', // container id
                style: styleUrl, // style URL
                center: [25.24,36.31], // starting position [lng, lat]
                zoom: 2, // starting zoom
            });
        </script>
    </body>
</html>

SDK (iOS, Swift)

使用下列程式碼：


import UIKit
import MapLibre

class ViewController: UIViewController {
    let apiKey = "Enter your API key" // The previously-created API Key to use
    let regionName = "Enter your region name" // The service region - us-east-1, ap-south-1, etc
    var mapView: MLNMapView!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        loadMap()
    }
    
    func loadMap() {
        let styleName = "Standard" // The map style - Standard, Monochrome, Hybrid, Satellite
        let colorName = "Light" // The color scheme - Light, Dark
        
        // The Amazon Location Service map style URL that MapLibre will use to render the maps.
        let styleURL = URL(string: "https://maps.geo.\(regionName).amazonaws.com/v2/styles/\(styleName)/descriptor?key=\(apiKey)&color-scheme=\(colorName)")

        // Initialize MapLibre        
        mapView = MLNMapView(frame: view.bounds)
        mapView.styleURL = styleURL
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        // Set the starting camera position and zoom level for the map
        mapView.setCenter(CLLocationCoordinate2D(latitude: 49.246559, longitude: -123.063554), zoomLevel: 10, animated: false)
        view.addSubview(mapView!)
    }
}

SDK (Android, Kotlin)

使用下列程式碼：


class MapActivity : Activity(), OnMapReadyCallback {

    private lateinit var mBinding: ActivityMapBinding

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        initializeMap(savedInstanceState)
    }

    private fun initializeMap(savedInstanceState: Bundle?) {
        // Init MapLibre
        // See the MapLibre Getting Started Guide for more details
        // https://maplibre.org/maplibre-native/docs/book/android/getting-started-guide.html
        MapLibre.getInstance(this@MapActivity)
        mBinding = ActivityMapBinding.inflate(layoutInflater)
        setContentView(mBinding.root)
        mBinding.mapView.onCreate(savedInstanceState)
        mBinding.mapView.getMapAsync(this)
    }

    override fun onMapReady(mapLibreMap: MapLibreMap) {
        mapLibreMap.setStyle(Style.Builder().fromUri(getMapUrl())) {
            // Set the starting camera position
            mapLibreMap.cameraPosition = CameraPosition.Builder().target(LatLng(49.246559, -123.063554)).zoom(10.0).build()
            mapLibreMap.uiSettings.isLogoEnabled = false
            mapLibreMap.uiSettings.attributionGravity = Gravity.BOTTOM or Gravity.END
            mapLibreMap.uiSettings.setAttributionDialogManager(AttributionDialogManager(this, mapLibreMap))
        }
    }

    // Return the Amazon Location Service map style URL
    // MapLibre will use this to render the maps.
    // awsRegion: The service region - us-east-1, ap-south-1, etc
    // mapStyle: The map style - Standard, Monochrome, Hybrid, Satellite  
    // API_KEY: The previously-created API Key to use
    // colorName: The color scheme to use - Light, Dark
    private fun getMapUrl() =
           "https://maps.geo.${getString(R.string.awsRegion)}.amazonaws.com/v2/styles/${getString(R.string.mapStyle)}/descriptor?key=${BuildConfig.API_KEY}&color-scheme=${getString(R.string.colorName)}"

    override fun onStart() {
        super.onStart()
        mBinding.mapView.onStart()
    }

    override fun onResume() {
        super.onResume()
        mBinding.mapView.onResume()
    }

    override fun onPause() {
        super.onPause()
        mBinding.mapView.onPause()
    }

    override fun onStop() {
        super.onStop()
        mBinding.mapView.onStop()
    }

    override fun onSaveInstanceState(outState: Bundle) {
        super.onSaveInstanceState(outState)
        mBinding.mapView.onSaveInstanceState(outState)
    }

    override fun onLowMemory() {
        super.onLowMemory()
        mBinding.mapView.onLowMemory()
    }

    override fun onDestroy() {
        super.onDestroy()
        mBinding.mapView.onDestroy()
    }
}

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

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

文件慣用形式

選擇身分驗證方法

使用 Amazon Cognito