翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# API キーを使用して認証する
<a name="using-apikeys"></a>

**注記**  
API キーは**マップ**、**配置**、**ルート**リソースでのみ使用でき、これらのリソースを変更または作成することはできません。アプリケーションが他のリソースにアクセスしたり、認証されていないユーザーがアクションにアクセスしたりする必要がある場合は、Amazon Cognito を使用して API キーと一緒に、または代わりに API キーへのアクセスを提供することができます。詳細については、「[Amazon Cognito を使用して認証する](authenticating-using-cognito.md)」を参照してください。

*API キー*は、 内の特定の Amazon Location Service リソースまたは API AWS アカウント、およびそれらのリソースに対して実行できる特定のアクションに関連付けられたキー値です。アプリケーションの API キーを使用して、それらのリソースの Amazon Location API を認証なしで呼び出すことができます。

例えば、API キーをリソースや `GetPlace*` API に関連付けると、その API キーを使用するアプリケーションは特定の API を呼び出すことができます。同じ API キーは、関連付けられていないリソースを変更または更新、あるいは API を呼び出すアクセス許可を付与しません。

アプリケーションで Amazon Location Service API を呼び出すときは、通常、API コールを行う権限を持つ*認証済みユーザー*としてこの呼び出しを行います。ただし、アプリケーションのすべてのユーザーを認証しない場合もあるでしょう。

例えば、会社の所在地を表示する Web アプリケーションを、ログインしているかどうかに関係なく、Web サイトを使用するすべてのユーザーが利用できるようにしたい場合があります。この場合API キーを使ってAPI 呼び出しを行うという方法もあります。

API キーを使用するタイミングの詳細については、「[API キーのベストプラクティス](#api-keys-best-practices)」を参照してください。

Amazon Location Service API を使用したキーの操作の詳細については、*Amazon Location Service API リファレンス*の以下のトピックを参照してください。
+ [CreateKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_CreateKey.html)
+ [DeleteKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_DeleteKey.html)
+ [DescribeKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_DescribeKey.html)
+ [ListKeys](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_ListKeys.html)

## Amazon Location Service の API キーを作成する
<a name="create-api-key"></a>

API キーは、Amazon Location Service コンソール AWS CLI、または Amazon Location API を使用して作成できます。以下の適切な手順に進みます。

------
#### [ Amazon Location console ]

**Amazon Location Service コンソールを使用して API キーを作成する**

1. [https://console.aws.amazon.com/location](https://console.aws.amazon.com/location)で、左側のメニューから **API キー**を選択します。

1. **[API キー]** ページで、**[API キーの作成]** を選択します。

1. **API キー**の作成ページで、次の情報を入力します。
   + **名前**— API キーの名前、例えば `ExampleKey`。
   + **説明** — API キーのオプションの説明。
   + **リソース** — ドロップダウンで、この API キーを使用してアクセスを許可する Amazon Location リソースを選択します。**リソースの追加**を選択すると、複数のリソースを追加できます。
   + **アクション** — この API キーを利用して、承認したアクションを指定します。選択した各リソースタイプと一致するアクションを少なくとも 1 つ選択する必要があります。例えば、Place リソースを選択した場合は、**Places Actions** の下にある選択肢を少なくとも 1 つ選択する必要があります。
   + **有効期限** — API キーの有効期限を任意で追加することができます。詳細については、「[API キーのベストプラクティス](#api-keys-best-practices)」を参照してください。
   + **[クライアントの制限]** – オプションで、API キーを使用できる 1 つ以上のウェブドメインまたは 1 つ以上の Android または Apple アプリを追加します。例えば、API キーがウェブサイト `example.com` で実行されるアプリケーションを許可するものであれば、許可されるリファラーとして `*.example.com/` を置くことができます。
   + **タグ** — オプションで API キーにタグを追加します。

1. **API キーを作成**を選択して API キーを作成します。

1. API キーの詳細ページには、作成した API キーに関する情報が表示されます。**API キーを表示**を選択すると、Amazon Location API を呼び出すときに使用するキーバリューが表示されます。キー値は次のフォーマットになります`v1.public.a1b2c3d4...`。

------
#### [ AWS CLI ]

1. [create-key](https://docs.aws.amazon.com/cli/latest/reference/location/create-key.html) コマンドを使用します。次の例では、有効期限なしで `ExampleKey` という名前の API キーを作成し、1 つのマップリソースにアクセスします。

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

1. レスポンスには、アプリケーション内のリソースにアクセスするときに使用する API キーバリューが含まれています。キー値は次のフォーマットになります`v1.public.a1b2c3d4...`。マップのレンダリングに API キーを使用する方法については、「[API キーを使用して Amazon Location API を呼び出す](#using-apikeys-in-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"
   }
   ```

1. `describe-key`を使用してキーバリューを後で検索することもできます。次の例は、`describe-key` という API キーで `ExampleKey` を呼び出す方法を示しています。

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

------
#### [ Amazon Location API ]

Amazon Location API の [CreateKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_CreateKey.html) オペレーションを使用してください。次の例は、`ExampleKey` という名前の API キーを作成し、有効期限なしで 1 つのマップリソースにアクセスする API リクエストです。

```
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](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_DescribeKey.html) API を使用してキーのキー値を後で検索することもできます。

------

## API キーを使用して Amazon Location API を呼び出す
<a name="using-apikeys-in-api"></a>

API キーを作成したら、そのキーバリューを使用してアプリケーションの Amazon Location API を呼び出すことができます。

------
#### [ API ]

API キーをサポートする API には、API キーバリューを取る追加パラメータがあります。例えば、`GetPlace` API を呼び出す場合、以下のように[キー](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_GetPlace.html)パラメータを入力できます

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

------
#### [ AWS CLI ]

Sig v4 での署名を避けるため、`--key` パラメータを使用する場合、`--no-sign-request` パラメータも使用する必要があります。

```
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()
    }
}
```

------

## リクエストオリジン別の API キーの使用を制限する
<a name="restrict-usage-by-origin"></a>

特定のドメインまたはモバイルアプリケーションへのアクセスを制限するクライアント制限を使用して API キーを設定できます。ドメインで制限する場合、リクエストは HTTP リファラーヘッダーが指定した値と一致する場合にのみ承認されます。Android または Apple アプリケーションによって制限する場合、リクエストは、アプリケーション識別子の HTTP ヘッダーフィールドが指定した値と一致する場合にのみ承認されます。

詳細については、「*Amazon Location Service API リファレンス*」の「[ApiKeyRestrictions](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_ApiKeyRestrictions.html)」を参照してください。

**Android アプリケーション識別子:**
+ `X-Android-Package`:

  Android アプリケーションの一意の識別子。アプリの `build.gradle` ファイルで定義され、通常はリバースドメイン形式に従います。

  例:

  `com.mydomain.appname`
+ `X-Android-Cert`:

  Android APK の署名に使用される署名証明書の SHA-1 ハッシュ。

  例:

  `BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75`

**Apple アプリケーション識別子:**
+ `X-Apple-Bundle-Id `:

  Apple (iOS、macOS など) アプリケーションの一意の識別子。アプリケーションの `Info.plist` で定義され、通常はリバースドメイン形式に従います。

  例:

  `com.mydomain.appname`

## API キーのベストプラクティス
<a name="api-keys-best-practices"></a>

API キーには、 AWS アカウント内の 1 つ以上のリソースへのアクセスを許可するプレーンテキストの*値*が含まれています。API キーをコピーしたユーザーは、同じリソースと API にアクセスできます。潜在的な影響を最小限に抑えるには、次のベストプラクティスを確認します。
+ **API キーを制限する**

  このような状況を回避するには、API キーを制限することをお勧めします。キーを作成するとき、キーを使用できる、ドメイン、Android アプリまたは Apple アプリを指定できます。
+ **API キーの有効期間を管理する**

  無期限に機能する API キーの作成ができます。ただし、一時的な API キーを作成したり、API キーを定期的にローテーションしたり、既存の API キーを取り消したりする場合は、*API キーの有効期限*を使用できます。
  + API キーを作成または更新するときに、API キーの有効期限を設定できます。
  + API キーの有効期限が切れると、キーは自動的に無効化されます。非アクティブなキーはマップリクエストには使用できなくなります。
  + 一時キーを永続的キーに変更するには、有効期限を削除します。
  + API キーは、非アクティブ化してから 90 日後に削除することができます。
  + 過去 7 日以内に使用された API キーを非アクティブ化しようとすると、変更の確認を求めるメッセージが表示されます。

    Amazon Location Service API または を使用している場合は AWS CLI、 `ForceUpdate`パラメータを に設定します。`true`そうしないと、エラーが発生します。