Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Gunakan kunci API untuk mengautentikasi
<a name="using-apikeys"></a>

**catatan**  
Kunci API hanya tersedia untuk digunakan dengan **peta**, **tempat**, dan sumber daya **rute**, dan Anda tidak dapat memodifikasi atau membuat sumber daya tersebut. Jika aplikasi Anda memerlukan akses ke sumber daya atau tindakan lain untuk pengguna yang tidak diautentikasi, Anda dapat menggunakan Amazon Cognito untuk menyediakan akses bersama dengan, atau bukan, kunci API. Untuk informasi selengkapnya, lihat [Gunakan Amazon Cognito untuk mengautentikasi](authenticating-using-cognito.md).

*Kunci API* adalah nilai kunci yang dikaitkan dengan sumber daya atau API Amazon Location Service tertentu di Anda Akun AWS, dan tindakan spesifik yang dapat Anda lakukan pada sumber daya tersebut. Anda dapat menggunakan kunci API dalam aplikasi Anda untuk membuat panggilan yang tidak diautentikasi ke Lokasi Amazon APIs untuk sumber daya tersebut. 

Misalnya, jika Anda mengaitkan kunci API dengan sumber daya and/or `GetPlace*` API, maka aplikasi yang menggunakan kunci API tersebut akan dapat memanggil spesifik APIs. Kunci API yang sama tidak akan memberikan izin untuk mengubah atau memperbarui sumber daya atau panggilan apa pun APIs yang tidak terkait dengannya.

Ketika Anda memanggil Amazon Location Service APIs di aplikasi Anda, Anda biasanya membuat panggilan ini sebagai *pengguna yang diautentikasi* yang diberi wewenang untuk melakukan panggilan API. Namun, ada beberapa kasus di mana Anda tidak ingin mengautentikasi setiap pengguna aplikasi Anda. 

Misalnya, Anda mungkin ingin aplikasi web yang menunjukkan lokasi bisnis Anda tersedia bagi siapa saja yang menggunakan situs web, apakah mereka masuk atau tidak. Dalam hal ini, salah satu alternatifnya adalah menggunakan kunci API untuk melakukan panggilan API.

Lihat [Praktik terbaik kunci API](#api-keys-best-practices) untuk informasi tambahan tentang kapan menggunakan kunci API.

Untuk informasi selengkapnya tentang bekerja dengan kunci menggunakan Amazon Location Service API, lihat topik berikut di *Referensi API Amazon Location Service*:
+ [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)

## Membuat kunci API untuk Amazon Location Service
<a name="create-api-key"></a>

Anda dapat membuat kunci API melalui Amazon Location Service console AWS CLI, atau Amazon Location API. Lanjutkan dengan prosedur yang sesuai di bawah ini.

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

**Untuk membuat kunci API menggunakan konsol Amazon Location Service**

1. Di [https://console.aws.amazon.com/location](https://console.aws.amazon.com/location), pilih **kunci API** dari menu sebelah kiri.

1. Pada halaman **kunci API**, pilih **Create API key**.

1. Pada halaman **Create API key**, isi informasi berikut:
   + **Nama** - Nama untuk kunci API Anda, seperti`ExampleKey`.
   + **Deskripsi — Deskripsi** opsional untuk kunci API Anda.
   + **Sumber Daya** — Di menu tarik-turun, pilih sumber daya Lokasi Amazon untuk diberikan akses dengan kunci API ini. Anda dapat menambahkan lebih dari satu sumber daya dengan memilih **Tambah sumber daya**.
   + **Tindakan** - Tentukan tindakan yang ingin Anda otorisasi dengan kunci API ini. Anda harus memilih setidaknya satu tindakan untuk mencocokkan setiap jenis sumber daya yang telah Anda pilih. Misalnya, jika Anda memilih sumber daya tempat, Anda harus memilih setidaknya salah satu pilihan di bawah **Tindakan Tempat**.
   + **Waktu kedaluwarsa** - Secara opsional, tambahkan tanggal kedaluwarsa dan waktu untuk kunci API Anda. Untuk informasi selengkapnya, lihat [Praktik terbaik kunci API](#api-keys-best-practices).
   + **Pembatasan klien** — Secara opsional, tambahkan satu atau beberapa domain web atau satu atau beberapa aplikasi Android atau Apple tempat Anda dapat menggunakan kunci API. Misalnya, jika kunci API adalah untuk mengizinkan aplikasi berjalan di situs web`example.com`, maka Anda dapat menempatkan `*.example.com/` sebagai perujuk yang diizinkan.
   + **Tag** - Secara opsional, tambahkan tag ke kunci API.

1. Pilih **Buat kunci API** untuk membuat kunci API.

1. Pada halaman detail untuk kunci API, Anda dapat melihat informasi tentang kunci API yang telah Anda buat. Pilih **Tampilkan kunci API** untuk melihat nilai kunci yang Anda gunakan saat memanggil Lokasi Amazon APIs. Nilai kunci akan memiliki format`v1.public.a1b2c3d4...`. 

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

1. Gunakan perintah [create-key](https://docs.aws.amazon.com/cli/latest/reference/location/create-key.html). Contoh berikut membuat kunci API yang dipanggil tanpa tanggal `ExampleKey` kedaluwarsa dan akses ke sumber daya peta tunggal.

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

1. Responsnya mencakup nilai kunci API yang akan digunakan saat mengakses sumber daya di aplikasi Anda. Nilai kunci akan memiliki format`v1.public.a1b2c3d4...`. Untuk mempelajari selengkapnya tentang menggunakan kunci API untuk merender peta, lihat[Menggunakan kunci API untuk memanggil Amazon Location API](#using-apikeys-in-api). Respons terhadap create-key terlihat seperti berikut:

   ```
   {
       "Key": "v1.public.a1b2c3d4...",
       "KeyArn": "arn:aws:geo:region:accountId:api-key/ExampleKey",
       "KeyName": "ExampleKey",
       "CreateTime": "2023-02-06T22:33:15.693Z"
   }
   ```

1. Anda juga dapat menggunakan `describe-key` untuk menemukan nilai kunci di lain waktu. Contoh berikut menunjukkan cara memanggil `describe-key` kunci API bernama`ExampleKey`.

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

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

Gunakan [CreateKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_CreateKey.html)operasi dari Lokasi Amazon APIs. Contoh berikut adalah permintaan API untuk membuat kunci API yang dipanggil tanpa tanggal `ExampleKey` kedaluwarsa dan akses ke sumber daya peta tunggal.

```
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"
    ]
  }
}
```

Responsnya mencakup nilai kunci API yang akan digunakan saat mengakses sumber daya di aplikasi Anda. Nilai kunci akan dimilikiformat. `v1.public.a1b2c3d4...`

Anda juga dapat menggunakan [DescribeKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_DescribeKey.html)API untuk menemukan nilai kunci untuk kunci di lain waktu.

------

## Menggunakan kunci API untuk memanggil Amazon Location API
<a name="using-apikeys-in-api"></a>

Setelah membuat kunci API, Anda dapat menggunakan nilai kunci untuk melakukan panggilan ke Lokasi Amazon APIs di aplikasi Anda.

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

Kunci API APIs yang mendukung memiliki parameter tambahan yang mengambil nilai kunci API. Misalnya, jika Anda memanggil `GetPlace` API, Anda dapat mengisi parameter [kunci](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_GetPlace.html), sebagai berikut

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

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

Bila Anda menggunakan `--key` parameter, Anda juga harus menggunakan `--no-sign-request` parameter, untuk menghindari penandatanganan dengan Sig v4.

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

------
#### [ SDK (web) ]

Gunakan kode berikut:

```
<!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) ]

Gunakan kode berikut:

```
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) ]

Gunakan kode berikut:

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

------

## Batasi penggunaan kunci API berdasarkan asal permintaan
<a name="restrict-usage-by-origin"></a>

Anda dapat mengonfigurasi kunci API dengan batasan klien yang membatasi akses ke domain atau aplikasi seluler tertentu. Saat membatasi berdasarkan domain, permintaan akan diotorisasi hanya jika header HTTP Referer cocok dengan nilai yang Anda berikan. Saat membatasi oleh aplikasi Android atau Apple, permintaan akan diotorisasi hanya jika bidang header HTTP pengenal aplikasi cocok dengan nilai yang Anda berikan.

Untuk informasi selengkapnya, lihat [ApiKeyRestrictions](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_ApiKeyRestrictions.html)di *Referensi API Amazon Location Service*.

**Pengidentifikasi aplikasi Android:**
+ `X-Android-Package`:

  Pengenal unik untuk aplikasi Android, yang ditentukan dalam `build.gradle` file aplikasi, biasanya mengikuti format domain terbalik.

  Contoh:

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

  Hash SHA-1 dari sertifikat penandatanganan yang digunakan untuk menandatangani APK Android.

  Contoh:

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

**Pengidentifikasi aplikasi Apple:**
+ `X-Apple-Bundle-Id `:

  Pengenal unik untuk aplikasi Apple (iOS, macOS, dll.), yang ditentukan dalam aplikasi`Info.plist`, biasanya mengikuti format domain terbalik.

  Contoh:

  `com.mydomain.appname`

## Praktik terbaik kunci API
<a name="api-keys-best-practices"></a>

Kunci API menyertakan *nilai* teks biasa yang memberikan akses ke satu atau beberapa sumber daya atau APIs di sumber daya Anda Akun AWS. Jika seseorang menyalin kunci API Anda, mereka dapat mengakses sumber daya yang sama dan APIs. Untuk meminimalkan dampak potensial, tinjau praktik terbaik berikut:
+ **Batasi kunci API**

  Untuk menghindari situasi di atas, yang terbaik adalah membatasi kunci API Anda. Saat membuat kunci, Anda dapat menentukan domain, aplikasi Android, atau aplikasi Apple tempat kunci tersebut dapat digunakan.
+ **Kelola masa pakai kunci API**

  Anda dapat membuat kunci API yang berfungsi tanpa batas waktu. Namun, jika Anda ingin membuat kunci API sementara, memutar kunci API secara teratur, atau mencabut kunci API yang ada, Anda dapat menggunakan kedaluwarsa *kunci API*.
  + Anda dapat mengatur waktu kedaluwarsa untuk kunci API saat membuat atau memperbaruinya.
  + Ketika kunci API mencapai waktu kedaluwarsa, kunci secara otomatis dinonaktifkan. Kunci tidak aktif tidak lagi dapat digunakan untuk membuat permintaan.
  + Anda dapat mengubah kunci sementara menjadi kunci permanen dengan menghapus waktu kedaluwarsa.
  + Anda dapat menghapus kunci API 90 hari setelah menonaktifkannya.
  + Jika Anda mencoba menonaktifkan kunci API yang telah digunakan dalam tujuh hari terakhir, Anda akan diminta untuk mengonfirmasi bahwa Anda ingin melakukan perubahan. 

    Jika Anda menggunakan Amazon Location Service API atau AWS CLI, atur `ForceUpdate` parameternya ke`true`, jika tidak, Anda akan menerima kesalahan.