Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Paket penggunaan dan kunci API untuk REST APIs di API Gateway
Setelah membuat, menguji, dan menerapkan APIs, Anda dapat menggunakan paket penggunaan API Gateway untuk membuatnya tersedia sebagai penawaran produk bagi pelanggan Anda. Anda dapat mengonfigurasi paket penggunaan dan kunci API untuk memungkinkan pelanggan mengakses yang dipilih APIs, dan mulai membatasi permintaan APIs berdasarkan batas dan kuota yang ditentukan. Ini dapat diatur pada API, atau tingkat metode API.
## Apa itu paket penggunaan dan kunci API?
*Paket penggunaan* menentukan siapa yang dapat mengakses satu atau beberapa tahapan dan metode API yang disebarkan—dan secara opsional menetapkan tingkat permintaan target untuk memulai pembatasan permintaan. Paket menggunakan kunci API untuk mengidentifikasi klien API dan siapa yang dapat mengakses tahapan API terkait untuk setiap kunci.
*Kunci API* adalah nilai string alfanumerik yang Anda distribusikan ke pelanggan pengembang aplikasi untuk memberikan akses ke API Anda. Anda dapat menggunakan kunci API bersama dengan [otorisasi Lambda](apigateway-use-lambda-authorizer.md), [peran IAM](permissions.md), atau Amazon Cognito untuk mengontrol [akses](apigateway-integrate-with-cognito.md) ke Anda. APIs API Gateway dapat menghasilkan kunci API atas nama Anda, atau Anda dapat mengimpornya dari [file CSV](api-key-file-format.md). Anda dapat membuat kunci API di API Gateway, atau mengimpornya ke API Gateway dari sumber eksternal. Untuk informasi selengkapnya, lihat [Siapkan kunci API untuk REST APIs di API Gateway](api-gateway-setup-api-keys.md).
Kunci API memiliki nama dan nilai. (Istilah “kunci API” dan “nilai kunci API” sering digunakan secara bergantian.) Nama tidak boleh melebihi 1024 karakter. Nilainya adalah string alfanumerik antara 20 dan 128 karakter, misalnya,. `apikey1234abcdefghij0123456789`
**penting**
Nilai kunci API harus unik. Jika Anda mencoba membuat dua kunci API dengan nama berbeda dan nilai yang sama, API Gateway menganggapnya sebagai kunci API yang sama.
Kunci API dapat dikaitkan dengan lebih dari satu paket penggunaan. Rencana penggunaan dapat dikaitkan dengan lebih dari satu tahap. Namun, kunci API tertentu hanya dapat dikaitkan dengan satu paket penggunaan untuk setiap tahap API Anda.
*Batas pelambatan* menetapkan titik target di mana pelambatan permintaan harus dimulai. Ini dapat diatur pada tingkat metode API atau API.
*Batas kuota* menetapkan jumlah maksimum target permintaan dengan kunci API tertentu yang dapat dikirimkan dalam interval waktu tertentu. Anda dapat mengonfigurasi metode API individual agar memerlukan otorisasi kunci API berdasarkan konfigurasi paket penggunaan.
Batas pembatasan dan kuota berlaku untuk permintaan kunci API individual yang digabungkan di semua tahapan API dalam paket penggunaan.
**catatan**
Pelambatan rencana penggunaan dan kuota bukanlah batas yang sulit, dan diterapkan atas dasar upaya terbaik. Dalam beberapa kasus, klien dapat melebihi kuota yang Anda tetapkan. Jangan mengandalkan kuota paket penggunaan atau pembatasan untuk mengontrol biaya atau memblokir akses ke API. Pertimbangkan [AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html)untuk menggunakan untuk memantau biaya dan [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html)mengelola permintaan API.
## Praktik terbaik untuk kunci API dan paket penggunaan
Berikut ini adalah praktik terbaik yang disarankan untuk diikuti saat menggunakan kunci API dan rencana penggunaan.
**penting**
Jangan gunakan kunci API untuk otentikasi atau otorisasi untuk mengontrol akses ke Anda. APIs Jika Anda memiliki beberapa APIs dalam paket penggunaan, pengguna dengan kunci API yang valid untuk satu API dalam paket penggunaan tersebut dapat mengakses *semua* APIs dalam paket penggunaan tersebut. Sebagai gantinya, untuk mengontrol akses ke API Anda, gunakan peran IAM, otorisasi [Lambda](apigateway-use-lambda-authorizer.md), atau kumpulan pengguna Amazon [Cognito](apigateway-integrate-with-cognito.md).
Gunakan kunci API yang dihasilkan API Gateway. Kunci API tidak boleh menyertakan informasi rahasia; klien biasanya mengirimkannya dalam header yang dapat dicatat.
+ Jika Anda menggunakan portal pengembang untuk mempublikasikan APIs, perhatikan bahwa semua paket penggunaan Anda APIs dapat berlangganan oleh pelanggan, bahkan jika Anda belum membuatnya terlihat oleh pelanggan Anda.
+ Dalam beberapa kasus, klien dapat melebihi kuota yang Anda tetapkan. Jangan mengandalkan rencana penggunaan untuk mengontrol biaya. Pertimbangkan [AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html)untuk menggunakan untuk memantau biaya dan [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html)mengelola permintaan API.
+ Setelah Anda menambahkan kunci API ke paket penggunaan, operasi pembaruan mungkin memerlukan beberapa menit untuk menyelesaikannya.
# Pilih sumber kunci API di API Gateway
Saat Anda mengaitkan rencana penggunaan dengan API dan mengaktifkan kunci API pada metode API, setiap permintaan masuk ke API harus berisi [kunci API](api-gateway-basic-concept.md#apigateway-definition-api-key). API Gateway membaca kunci dan membandingkannya dengan kunci dalam paket penggunaan. Jika ada kecocokan, API Gateway membatasi permintaan berdasarkan batas permintaan dan kuota paket. Kalau tidak, itu melempar `InvalidKeyParameter` pengecualian. Akibatnya, penelepon menerima `403 Forbidden` respons.
API Gateway API Anda dapat menerima kunci API dari salah satu dari dua sumber:
**`HEADER`**
Anda mendistribusikan kunci API ke pelanggan Anda dan meminta mereka untuk meneruskan kunci API sebagai `X-API-Key` header dari setiap permintaan yang masuk.
**`AUTHORIZER`**
Anda memiliki otorisasi Lambda yang mengembalikan kunci API sebagai bagian dari respons otorisasi. Untuk informasi selengkapnya tentang respons otorisasi, lihat[Keluaran dari otorisasi API Gateway Lambda](api-gateway-lambda-authorizer-output.md).
**catatan**
Untuk praktik terbaik untuk dipertimbangkan, lihat[Praktik terbaik untuk kunci API dan paket penggunaan](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices).
Prosedur berikut menunjukkan cara memilih sumber kunci API untuk API.
------
#### [ Konsol Manajemen AWS ]
**Untuk memilih sumber kunci API untuk API**
1. Masuk ke konsol API Gateway.
1. Pilih API yang sudah ada atau buat yang baru.
1. Di panel navigasi utama, pilih **pengaturan API**.
1. Di bagian **detail API**, pilih **Edit**.
1. Di bawah **sumber kunci API**, pilih `Header` atau `Authorizer` dari daftar tarik-turun.
1. Pilih **Simpan perubahan**.
------
#### [ AWS CLI ]
[update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)Perintah berikut memperbarui API untuk menyetel sumber kunci API ke`AUTHORIZER`:
```
aws apigateway update-rest-api --rest-api-id 1234123412 --patch-operations op=replace,path=/apiKeySource,value=AUTHORIZER
```
Agar klien mengirimkan kunci API, atur `value` ke `HEADER` dalam perintah sebelumnya.
------
#### [ REST API ]
Untuk memilih sumber kunci API untuk API dengan menggunakan API Gateway REST API, panggil [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html)sebagai berikut:
```
PATCH /restapis/fugvjdxtri/ HTTP/1.1
Content-Type: application/json
Host: apigateway.us-east-1.amazonaws.com
X-Amz-Date: 20160603T205348Z
Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160603/us-east-1/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature={sig4_hash}
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/apiKeySource",
"value" : "HEADER"
}
]
}
```
Agar otorisasi mengembalikan kunci API, setel `value` ke `AUTHORIZER` dalam `patchOperations` input sebelumnya.
------
# Format file kunci API untuk API Gateway
API Gateway dapat mengimpor kunci API dari file eksternal dengan format nilai dipisahkan koma (CSV), lalu mengaitkan kunci yang diimpor dengan satu atau beberapa paket penggunaan. File yang diimpor harus berisi `Key` kolom `Name` dan. Nama header kolom tidak peka huruf besar/kecil, dan kolom dapat dalam urutan apa pun, seperti yang ditunjukkan pada contoh berikut:
```
Key,name
apikey1234abcdefghij0123456789,MyFirstApiKey
```
`Key`Nilai harus antara 20 dan 128 karakter. `Name`Nilai tidak boleh melebihi 1024 karakter.
File kunci API juga dapat memiliki`Description`,`Enabled`, atau `UsagePlanIds` kolom, seperti yang ditunjukkan pada contoh berikut:
```
Name,key,description,Enabled,usageplanIds
MyFirstApiKey,apikey1234abcdefghij0123456789,An imported key,TRUE,c7y23b
```
Ketika kunci dikaitkan dengan lebih dari satu paket penggunaan, `UsagePlanIds` nilainya adalah string yang dipisahkan koma dari rencana penggunaan IDs, diapit dengan sepasang tanda kutip ganda atau tunggal, seperti yang ditunjukkan pada contoh berikut:
```
Enabled,Name,key,UsageplanIds
true,MyFirstApiKey,apikey1234abcdefghij0123456789,"c7y23b,glvrsr"
```
Kolom yang tidak dikenal diizinkan, tetapi diabaikan. Nilai default adalah string kosong atau nilai `true` Boolean.
Kunci API yang sama dapat diimpor beberapa kali, dengan versi terbaru menimpa yang sebelumnya. Dua kunci API identik jika memiliki `key` nilai yang sama.
**catatan**
Untuk praktik terbaik untuk dipertimbangkan, lihat[Praktik terbaik untuk kunci API dan paket penggunaan](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices).
# Siapkan kunci API untuk REST APIs di API Gateway
Untuk menyiapkan kunci API, lakukan hal berikut:
+ Konfigurasikan metode API untuk memerlukan kunci API.
+ Membuat atau mengimpor kunci API untuk API di Wilayah.
Sebelum menyiapkan kunci API, Anda harus membuat API dan menerapkannya ke panggung. Setelah Anda membuat nilai kunci API, nilai tersebut tidak dapat diubah.
Untuk petunjuk tentang cara membuat dan menerapkan API menggunakan konsol API Gateway, lihat [Kembangkan REST APIs di API Gateway](rest-api-develop.md) dan[Menerapkan REST APIs di API Gateway](how-to-deploy-api.md), masing-masing.
Setelah membuat kunci API, Anda harus mengaitkannya dengan paket penggunaan. Untuk informasi selengkapnya, lihat [Siapkan paket penggunaan untuk REST APIs di API Gateway](api-gateway-create-usage-plans.md).
**catatan**
Untuk praktik terbaik untuk dipertimbangkan, lihat[Praktik terbaik untuk kunci API dan paket penggunaan](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices).
**Topics**
+ [Memerlukan kunci API pada suatu metode](#api-gateway-usage-plan-configure-apikey-on-method)
+ [Membuat kunci API](#api-gateway-usage-plan-create-apikey)
+ [Impor kunci API](#api-gateway-usage-pan-import-apikey)
## Memerlukan kunci API pada suatu metode
Prosedur berikut menjelaskan cara mengonfigurasi metode API agar memerlukan kunci API.
------
#### [ Konsol Manajemen AWS ]
**Untuk mengonfigurasi metode API agar memerlukan kunci API**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Di panel navigasi utama API Gateway, pilih **Resources**.
1. Di bawah **Sumber Daya**, buat metode baru atau pilih yang sudah ada.
1. Pada tab **Permintaan metode**, di bawah **Pengaturan permintaan metode**, pilih **Edit**.
![\[Menambahkan kunci API ke metode\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/api-gateway-new-console-add-key-to-method.png)
1. Pilih **kunci API yang diperlukan**.
1. Pilih **Simpan**.
1. Menerapkan atau menerapkan ulang API agar persyaratan diterapkan.
Jika opsi yang **diperlukan kunci API** disetel ke `false` dan Anda tidak menjalankan langkah sebelumnya, kunci API apa pun yang terkait dengan tahap API tidak akan digunakan untuk metode tersebut.
------
#### [ AWS CLI ]
Perintah [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) berikut membuat `PUT` metode yang memerlukan kunci API:
```
aws apigateway put-method \
--rest-api-id 1234123412 \
--resource-id a1b2c3 \
--http-method PUT \
--authorization-type "NONE" \
--api-key-required
```
Perintah [update-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-method.html) berikut memperbarui metode yang ada untuk memerlukan kunci API:
```
aws apigateway update-method \
--rest-api-id 1234123412 \
--resource-id a1b2c3 \
--http-method PUT \
--patch-operations op="replace",path="/apiKeyRequired",value="true"
```
------
#### [ REST API ]
Untuk mewajibkan kunci API pada suatu metode, lakukan salah satu hal berikut:
+ Panggilan [https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html)untuk membuat metode. Setel `apiKeyRequired` ke `true` dalam payload permintaan.
+ Panggilan [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html)untuk mengatur `apiKeyRequired` ke`true`.
------
## Membuat kunci API
Prosedur berikut menunjukkan cara membuat kunci API. Jika Anda ingin mengimpor kunci API Anda, lewati langkah ini.
------
#### [ Konsol Manajemen AWS ]
**Untuk membuat kunci API**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Di panel navigasi utama API Gateway, pilih **kunci API**.
1. Pilih **Buat kunci API**.
![\[Buat kunci API untuk paket penggunaan\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-choose-create-api-key-from-actions-menu.png)
1. Untuk **Nama**, masukkan nama.
1. (Opsional) Untuk **Deskripsi**, masukkan deskripsi.
1. Untuk **kunci API**, pilih **Auto generate** agar API Gateway menghasilkan nilai kunci, atau pilih **Custom** untuk membuat nilai kunci Anda sendiri.
1. Pilih **Simpan**.
------
#### [ AWS CLI ]
[create-api-key](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-api-key.html)Perintah berikut membuat kunci API:
```
aws apigateway create-api-key \
--name 'Dev API key' \
--description 'API key for Devs' \
--enabled
```
------
#### [ REST API ]
Panggilan [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateApiKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateApiKey.html)untuk membuat kunci API.
------
## Impor kunci API
Prosedur berikut menjelaskan cara mengimpor kunci API. Jika Anda sudah membuat kunci API, lewati langkah ini.
------
#### [ Konsol Manajemen AWS ]
**Untuk mengimpor kunci API**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Di panel navigasi utama, pilih **kunci API**.
1. Pilih menu tarik-turun **Tindakan**, lalu pilih **Impor kunci API**.
1. Untuk memuat file kunci yang dipisahkan koma, pilih **Pilih** file. Anda juga dapat memasukkan tombol di editor teks. Untuk informasi tentang format file, lihat[Format file kunci API untuk API Gateway](api-key-file-format.md).
1. Pilih **Gagal pada peringatan** untuk menghentikan impor ketika ada kesalahan, atau pilih **Abaikan peringatan** untuk terus mengimpor entri kunci yang valid saat ada peringatan.
1. Pilih **Impor** untuk mengimpor kunci API Anda.
------
#### [ AWS CLI ]
[import-api-keys](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-api-keys.html)Perintah berikut mengimpor kunci API:
```
aws apigateway import-api-key \
a--body fileb://keys.csv \
--format csv
```
------
#### [ REST API ]
Panggilan [https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html)untuk mengimpor kunci API dari file. Untuk format file, lihat[Format file kunci API untuk API Gateway](api-key-file-format.md).
------
Anda tidak dapat mengubah nilai kunci API baru. Setelah membuat API, Anda mengonfigurasi paket penggunaan. Untuk informasi selengkapnya, lihat [Siapkan paket penggunaan untuk REST APIs di API Gateway](api-gateway-create-usage-plans.md).
# Siapkan paket penggunaan untuk REST APIs di API Gateway
Sebelum membuat paket penggunaan, pastikan Anda telah menyiapkan kunci API Anda. Untuk informasi selengkapnya, lihat [Siapkan kunci API untuk REST APIs di API Gateway](api-gateway-setup-api-keys.md).
**Topics**
+ [Migrasi API Anda ke paket penggunaan default (jika diperlukan)](#api-gateway-usage-plan-migrate-to-default)
+ [Buat rencana penggunaan](#api-gateway-usage-plan-create)
+ [Tambahkan tahapan ke paket penggunaan](#api-gateway-usage-plan-add-stage)
+ [Menambahkan kunci API ke paket penggunaan](#api-gateway-usage-plan-add-key)
## Migrasi API Anda ke paket penggunaan default (jika diperlukan)
Jika Anda mulai menggunakan API Gateway *setelah* fitur paket penggunaan diluncurkan pada 11 Agustus 2016, Anda akan secara otomatis mengaktifkan paket penggunaan untuk Anda di semua Wilayah yang didukung.
Jika Anda mulai menggunakan API Gateway sebelum tanggal tersebut, Anda mungkin perlu bermigrasi ke paket penggunaan default. Anda akan diminta dengan opsi **Aktifkan Paket Penggunaan** sebelum menggunakan paket penggunaan untuk pertama kalinya di Wilayah yang dipilih. Saat mengaktifkan opsi ini, Anda memiliki paket penggunaan default yang dibuat untuk setiap tahap API unik yang terkait dengan kunci API yang ada. Dalam paket penggunaan default, tidak ada batas throttle atau kuota yang ditetapkan pada awalnya, dan asosiasi antara kunci API dan tahapan API disalin ke paket penggunaan. API berperilaku sama seperti sebelumnya. Namun, Anda harus menggunakan [https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html)`apiStages`properti untuk mengaitkan nilai tahap API tertentu (`apiId`dan`stage`) dengan kunci API yang disertakan (via [https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlanKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlanKey.html)), alih-alih menggunakan [ApiKey](https://docs.aws.amazon.com/apigateway/latest/api/API_ApiKey.html)`stageKeys`properti.
Untuk memeriksa apakah Anda sudah bermigrasi ke paket penggunaan default, gunakan perintah [https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-account.html](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-account.html)CLI. Dalam output perintah, `features` daftar menyertakan entri `"UsagePlans"` kapan rencana penggunaan diaktifkan.
Anda juga dapat memigrasikan APIs ke paket penggunaan default dengan menggunakan AWS CLI sebagai berikut:
**Untuk bermigrasi ke paket penggunaan default menggunakan AWS CLI**
1. Panggil perintah CLI ini:. [https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html)
1. Untuk `cli-input-json` parameter, gunakan JSON berikut:
```
[
{
"op": "add",
"path": "/features",
"value": "UsagePlans"
}
]
```
## Buat rencana penggunaan
Prosedur berikut menjelaskan cara membuat rencana penggunaan.
------
#### [ Konsol Manajemen AWS ]
**Untuk membuat rencana penggunaan**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Di panel navigasi utama API Gateway, pilih **Paket penggunaan**, lalu pilih **Buat paket penggunaan**.
![\[Entitas rencana penggunaan API\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-setup.png)
1. Untuk **Nama**, masukkan nama.
1. (Opsional) Untuk **Deskripsi**, masukkan deskripsi.
1. Secara default, paket penggunaan mengaktifkan pelambatan. Masukkan **Rate** dan **Burst** untuk paket penggunaan Anda. Pilih **Throttling** untuk mematikan throttling.
1. Secara default, paket penggunaan mengaktifkan kuota untuk jangka waktu tertentu. Untuk **Permintaan**, masukkan jumlah total permintaan yang dapat dibuat pengguna dalam periode waktu paket penggunaan Anda. Pilih **Kuota** untuk mematikan kuota.
1. Pilih **Buat paket penggunaan**.
------
#### [ AWS CLI ]
[create-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-usage-plan.html)Perintah berikut membuat paket penggunaan yang mengatur ulang pada awal bulan:
```
aws apigateway create-usage-plan \
--name "New Usage Plan" \
--description "A new usage plan" \
--throttle burstLimit=10,rateLimit=5 \
--quota limit=500,offset=0,period=MONTH
```
------
#### [ REST API ]
Hubungi [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlan.html)untuk membuat paket penggunaan.
------
## Tambahkan tahapan ke paket penggunaan
Prosedur berikut menjelaskan cara menambahkan tahapan ke rencana penggunaan.
------
#### [ Konsol Manajemen AWS ]
**Untuk menambahkan tahapan ke rencana penggunaan**
1. Pilih paket penggunaan Anda.
1. Di bawah tab **Tahapan terkait**, pilih **Tambahkan tahap**.
![\[Tambahkan tahap API ke paket penggunaan.\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-add-stage.png)
1. Untuk **API**, pilih API.
1. Untuk **Stage**, pilih panggung.
1. (Opsional) Untuk mengaktifkan pelambatan tingkat metode, lakukan hal berikut:
1. **Pilih **pelambatan tingkat metode**, lalu pilih Tambahkan metode.**
1. Untuk **Sumber Daya**, pilih sumber daya dari API Anda.
1. Untuk **Metode**, pilih metode dari API Anda.
1. Masukkan **Rate** dan **Burst** untuk paket penggunaan Anda.
1. Pilih **Tambahkan ke paket penggunaan**.
------
#### [ AWS CLI ]
[update-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-usage-plan.html)Perintah berikut menambahkan `Prod` tahap API ke paket penggunaan:
```
aws apigateway update-usage-plan \
--usage-plan-id abc123 \
--patch-operations op="add",path="/apiStages",value="a1b1c2:Prod"
```
------
#### [ REST API ]
Hubungi [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html)untuk memperbarui paket penggunaan.
------
## Menambahkan kunci API ke paket penggunaan
Prosedur berikut menunjukkan cara menambahkan kunci API ke paket penggunaan.
------
#### [ Konsol Manajemen AWS ]
**Untuk menambahkan kunci ke paket penggunaan**
1. Di bawah tab **Kunci API Terkait**, pilih **Tambahkan kunci API**.
![\[Entitas rencana penggunaan API\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-add-key.png)
1.
1. Untuk mengaitkan kunci yang ada ke paket penggunaan Anda, pilih **Tambahkan kunci yang ada**, lalu pilih kunci yang ada dari menu tarik-turun.
1. Untuk membuat kunci API baru, pilih **Buat dan tambahkan kunci baru**, lalu buat kunci baru. Untuk informasi selengkapnya tentang cara membuat kunci baru, lihat[Membuat kunci API](api-gateway-setup-api-keys.md#api-gateway-usage-plan-create-apikey).
1. Pilih **Tambahkan kunci API**.
------
#### [ AWS CLI ]
[create-usage-plan-key](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-usage-plan-key.html)Perintah berikut mengaitkan kunci API yang ada dengan paket penggunaan:
```
aws apigateway create-usage-plan-key \
--usage-plan-id a1b2c3 \
--key-type "API_KEY" \
--key-id aaa111bbb
```
------
#### [ REST API ]
Panggilan [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlanKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlanKey.html)untuk mengaitkan kunci API yang ada dengan paket penggunaan.
Anda juga dapat langsung mengaitkan APIs kunci Anda dengan paket penggunaan saat Anda mengimpornya. Panggil [https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html)untuk menambahkan satu atau beberapa kunci API langsung ke paket penggunaan yang ditentukan. Payload permintaan harus berisi nilai kunci API, pengenal paket penggunaan terkait, flag Boolean untuk menunjukkan bahwa kunci diaktifkan untuk paket penggunaan, dan, mungkin, nama dan deskripsi kunci API.
Contoh `apikey:import` permintaan berikut ini menambahkan tiga kunci API (seperti yang diidentifikasi oleh`key`,`name`, dan`description`) ke satu paket penggunaan (seperti yang diidentifikasi oleh`usageplanIds`):
```
POST /apikeys?mode=import&format=csv&failonwarnings=fase HTTP/1.1
Host: apigateway.us-east-1.amazonaws.com
Content-Type: text/csv
Authorization: ...
key,name, description, enabled, usageplanIds
abcdef1234ghijklmnop8901234567, importedKey_1, firstone, tRuE, n371pt
abcdef1234ghijklmnop0123456789, importedKey_2, secondone, TRUE, n371pt
abcdef1234ghijklmnop9012345678, importedKey_3, , true, n371pt
```
Akibatnya, tiga `UsagePlanKey` sumber daya dibuat dan ditambahkan ke`UsagePlan`.
Anda juga dapat menambahkan kunci API ke lebih dari satu paket penggunaan dengan cara ini. Untuk melakukan ini, ubah setiap nilai `usageplanIds` kolom menjadi string yang dipisahkan koma yang berisi pengidentifikasi rencana penggunaan yang dipilih, dan diapit dalam sepasang tanda kutip (atau). `"n371pt,m282qs"` `'n371pt,m282qs'`
------
**catatan**
Kunci API dapat dikaitkan dengan lebih dari satu paket penggunaan. Rencana penggunaan dapat dikaitkan dengan lebih dari satu tahap. Namun, kunci API tertentu hanya dapat dikaitkan dengan satu paket penggunaan untuk setiap tahap API Anda.
# Mempertahankan rencana penggunaan untuk REST APIs di API Gateway
Mempertahankan rencana penggunaan melibatkan pemantauan kuota yang digunakan dan yang tersisa selama periode waktu tertentu dan, jika diperlukan, memperpanjang kuota yang tersisa dengan jumlah tertentu. Prosedur berikut menjelaskan cara memantau kuota.
------
#### [ Konsol Manajemen AWS ]
**Untuk memantau kuota yang digunakan dan yang tersisa**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Di panel navigasi utama API Gateway, pilih **Paket penggunaan**.
1. Pilih paket penggunaan.
1. Pilih tab **Kunci API Terkait** untuk melihat jumlah permintaan yang tersisa untuk periode waktu untuk setiap kunci.
1. (Opsional) Pilih **Ekspor data penggunaan**, lalu pilih Tanggal **Dari** dan Tanggal **Sampai** saat ini. **Kemudian pilih **JSON** atau **CSV** untuk format data yang diekspor, lalu pilih Ekspor.**
Contoh berikut menunjukkan file yang diekspor.
```
{
"px1KW6...qBazOJH": [
[
0,
5000
],
[
0,
5000
],
[
0,
10
]
]
}
```
Data penggunaan dalam contoh menunjukkan data penggunaan harian untuk klien API, seperti yang diidentifikasi oleh kunci API (`px1KW6...qBazOJH`), antara 1 Agustus 2016 dan 3 Agustus 2016. Setiap data penggunaan harian menunjukkan kuota yang digunakan dan yang tersisa. Dalam contoh ini, pelanggan belum menggunakan kuota yang dialokasikan, dan pemilik atau administrator API telah mengurangi sisa kuota dari 5000 menjadi 10 pada hari ketiga.
Prosedur berikut menjelaskan cara memodifikasi kuota.
**Untuk memperpanjang kuota yang tersisa**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Di panel navigasi utama API Gateway, pilih **Paket penggunaan**.
1. Pilih paket penggunaan.
1. Pilih tab **Kunci API Terkait** untuk melihat jumlah permintaan yang tersisa untuk periode waktu untuk setiap kunci.
1. Pilih kunci API, lalu pilih **Grant usage extension**.
1. Masukkan nomor untuk kuota **Permintaan yang tersisa**. Anda dapat meningkatkan permintaan penggantian nama atau mengurangi permintaan yang tersisa untuk jangka waktu paket penggunaan Anda.
1. Pilih **Perbarui kuota**.
------
#### [ AWS CLI ]
[update-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-usage-plan.html)Contoh berikut menambah, menghapus, atau memodifikasi pengaturan pelambatan tingkat metode dalam paket penggunaan.
**catatan**
Pastikan untuk mengubah `us-east-1` ke nilai Region yang sesuai untuk API Anda.
Untuk menambah atau mengganti batas tarif untuk membatasi sumber daya dan metode individual:
```
aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="replace",path="/apiStages/apiId:stage/throttle/resourcePath/httpMethod/rateLimit",value="0.1"
```
Untuk menambah atau mengganti batas burst untuk membatasi sumber daya dan metode individual:
```
aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="replace",path="/apiStages/apiId:stage/throttle/resourcePath/httpMethod/burstLimit",value="1"
```
Untuk menghapus pengaturan pelambatan tingkat metode untuk sumber daya dan metode individual:
```
aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="remove",path="/apiStages/apiId:stage/throttle/resourcePath/httpMethod",value=""
```
Untuk menghapus semua setelan pelambatan tingkat metode untuk API:
```
aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="remove",path="/apiStages/apiId:stage/throttle ",value=""
```
Berikut adalah contoh menggunakan contoh API Pet Store:
```
aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="replace",path="/apiStages/apiId:stage/throttle",value='"{\"/pets/GET\":{\"rateLimit\":1.0,\"burstLimit\":1},\"//GET\":{\"rateLimit\":1.0,\"burstLimit\":1}}"'
```
------
#### [ REST API ]
Hubungi [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html)untuk mempertahankan rencana penggunaan.
------
# Membuat dan mengonfigurasi kunci API dan rencana penggunaan dengan CloudFormation
Anda dapat menggunakan CloudFormation untuk mewajibkan kunci API pada metode API dan membuat rencana penggunaan untuk API. Contoh CloudFormation template melakukan hal berikut:
+ Membuat API Gateway API dengan `GET` dan `POST` metode.
+ Memerlukan kunci API untuk `GET` dan `POST` metode. API ini menerima kunci dari `X-API-KEY` header setiap permintaan yang masuk.
+ Membuat kunci API.
+ Membuat paket penggunaan untuk menentukan kuota bulanan 1.000 permintaan setiap bulan, batas laju pelambatan 100 permintaan setiap detik, dan batas burst throttling 200 permintaan setiap detik.
+ Menentukan batas laju pelambatan tingkat metode 50 permintaan setiap detik dan batas burst throttling tingkat metode 100 permintaan per detik untuk metode tersebut. `GET`
+ Mengaitkan tahap API dan kunci API dengan paket penggunaan.
```
AWSTemplateFormatVersion: 2010-09-09
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
KeyName:
Type: String
Default: MyKeyName
Description: Name of an API key
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: keys-api
ApiKeySourceType: HEADER
PetsResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'pets'
PetsMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: GET
ApiKeyRequired: true
AuthorizationType: NONE
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
PetsMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: POST
ApiKeyRequired: true
AuthorizationType: NONE
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- PetsMethodGet
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
UsagePlan:
Type: AWS::ApiGateway::UsagePlan
DependsOn:
- ApiDeployment
Properties:
Description: Example usage plan with a monthly quota of 1000 calls and method-level throttling for /pets GET
ApiStages:
- ApiId: !Ref Api
Stage: !Sub '${StageName}'
Throttle:
"/pets/GET":
RateLimit: 50.0
BurstLimit: 100
Quota:
Limit: 1000
Period: MONTH
Throttle:
RateLimit: 100.0
BurstLimit: 200
UsagePlanName: "My Usage Plan"
ApiKey:
Type: AWS::ApiGateway::ApiKey
Properties:
Description: API Key
Name: !Sub '${KeyName}'
Enabled: True
UsagePlanKey:
Type: AWS::ApiGateway::UsagePlanKey
Properties:
KeyId: !Ref ApiKey
KeyType: API_KEY
UsagePlanId: !Ref UsagePlan
Outputs:
ApiRootUrl:
Description: Root Url of the API
Value: !Sub 'https://${Api}.execute-api.${AWS::Region}.amazonaws.com/${StageName}'
```
# Konfigurasikan metode untuk menggunakan kunci API dengan definisi OpenAPI
Anda dapat menggunakan definisi OpenAPI untuk meminta kunci API pada suatu metode.
Untuk setiap metode, buat objek persyaratan keamanan untuk meminta kunci API untuk menjalankan metode tersebut. Kemudian, tentukan `api_key` dalam definisi keamanan. Setelah membuat API, tambahkan tahap API baru ke paket penggunaan Anda.
Contoh berikut membuat API dan memerlukan kunci API untuk `POST` dan `GET` metode:
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"version" : "2024-03-14T20:20:12Z",
"title" : "keys-api"
},
"basePath" : "/v1",
"schemes" : [ "https" ],
"paths" : {
"/pets" : {
"get" : {
"responses" : { },
"security" : [ {
"api_key" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"type" : "http_proxy",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/",
"passthroughBehavior" : "when_no_match"
}
},
"post" : {
"responses" : { },
"security" : [ {
"api_key" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"type" : "http_proxy",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/",
"passthroughBehavior" : "when_no_match"
}
}
}
},
"securityDefinitions" : {
"api_key" : {
"type" : "apiKey",
"name" : "x-api-key",
"in" : "header"
}
}
}
```
------
#### [ OpenAPI 3.0 ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "keys-api",
"version" : "2024-03-14T20:20:12Z"
},
"servers" : [ {
"url" : "{basePath}",
"variables" : {
"basePath" : {
"default" : "v1"
}
}
} ],
"paths" : {
"/pets" : {
"get" : {
"security" : [ {
"api_key" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/",
"passthroughBehavior" : "when_no_match",
"type" : "http_proxy"
}
},
"post" : {
"security" : [ {
"api_key" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/",
"passthroughBehavior" : "when_no_match",
"type" : "http_proxy"
}
}
}
},
"components" : {
"securitySchemes" : {
"api_key" : {
"type" : "apiKey",
"name" : "x-api-key",
"in" : "header"
}
}
}
}
```
------
# Uji paket penggunaan untuk REST APIs di API Gateway
Sebagai contoh, mari kita gunakan PetStore API, yang dibuat di[Tutorial: Buat REST API dengan mengimpor contoh](api-gateway-create-api-from-example.md). Asumsikan bahwa API dikonfigurasi untuk menggunakan kunci API dari`Hiorr45VR...c4GJc`. Langkah-langkah berikut menjelaskan cara menguji rencana penggunaan.
**Untuk menguji paket penggunaan Anda**
+ Buat `GET` permintaan pada resource Pets (`/pets`), dengan parameter `?type=...&page=...` kueri, API (misalnya,`xbvxlpijch`) dalam paket penggunaan:
```
GET /testStage/pets?type=dog&page=1 HTTP/1.1
x-api-key: Hiorr45VR...c4GJc
Content-Type: application/x-www-form-urlencoded
Host: xbvxlpijch.execute-api.ap-southeast-1.amazonaws.com
X-Amz-Date: 20160803T001845Z
Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160803/ap-southeast-1/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-api-key, Signature={sigv4_hash}
```
**catatan**
Anda harus mengirimkan permintaan ini ke `execute-api` komponen API Gateway dan memberikan kunci API yang diperlukan (misalnya,`Hiorr45VR...c4GJc`) di `x-api-key` header yang diperlukan.
Respons yang berhasil mengembalikan kode `200 OK` status dan payload yang berisi hasil yang diminta dari backend. Jika Anda lupa mengatur `x-api-key` header atau mengaturnya dengan kunci yang salah, Anda mendapatkan `403 Forbidden` respons. Namun, jika Anda tidak mengonfigurasi metode untuk memerlukan kunci API, kemungkinan besar Anda akan mendapatkan `200 OK` respons apakah Anda menyetel `x-api-key` header dengan benar atau tidak, dan batas throttle dan kuota paket penggunaan dilewati.
Kadang-kadang, ketika terjadi kesalahan internal di mana API Gateway tidak dapat menerapkan batas pembatasan rencana penggunaan atau kuota untuk permintaan, API Gateway melayani permintaan tanpa menerapkan batas pembatasan atau kuota seperti yang ditentukan dalam paket penggunaan. Tapi, itu mencatat pesan kesalahan `Usage Plan check failed due to an internal error` in CloudWatch. Anda dapat mengabaikan kesalahan sesekali seperti itu.
# Panggil metode menggunakan kunci API
Bergantung pada jenis sumber kunci API yang Anda pilih, gunakan salah satu prosedur berikut untuk menggunakan kunci API bersumber header atau kunci API yang dikembalikan oleh otorisasi dalam pemanggilan metode:
**Untuk menggunakan kunci API bersumber header:**
1. Buat API dengan metode API yang diinginkan, lalu terapkan API ke panggung.
1. Buat paket penggunaan baru atau pilih yang sudah ada. Tambahkan tahap API yang diterapkan ke paket penggunaan. Lampirkan kunci API ke paket penggunaan atau pilih kunci API yang ada dalam paket. Perhatikan nilai kunci API yang dipilih.
1. Siapkan metode API untuk memerlukan kunci API.
1. Menerapkan ulang API ke tahap yang sama. Jika Anda menerapkan API ke tahap baru, pastikan untuk memperbarui paket penggunaan untuk melampirkan tahap API baru.
1. Panggil API menggunakan kunci API. Contoh perintah curl berikut memanggil `GET` metode pada `getUsers` sumber daya `prod` tahap API menggunakan kunci API.
```
curl -H "X-API-Key: abcd1234" 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers'
```
Klien sekarang dapat memanggil metode API sambil memasok `x-api-key` header dengan kunci API yang dipilih sebagai nilai header. Panggilan mungkin terlihat seperti berikut:
**Untuk menggunakan kunci API yang bersumber dari otorisasi:**
1. Buat API dengan metode API yang diinginkan, lalu terapkan API ke panggung.
1. Buat paket penggunaan baru atau pilih yang sudah ada. Tambahkan tahap API yang diterapkan ke paket penggunaan. Lampirkan kunci API ke paket penggunaan atau pilih kunci API yang ada dalam paket. Perhatikan nilai kunci API yang dipilih.
1. Buat otorisasi Lambda berbasis token. Sertakan, `usageIdentifierKey:{api-key}` sebagai properti tingkat root dari respons otorisasi. Untuk petunjuk cara membuat otorisasi berbasis token, lihat. [Contoh fungsi Lambda `TOKEN` authorizer](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-token-lambda-function-create)
1. Siapkan metode API untuk memerlukan kunci API dan aktifkan otorisasi Lambda pada metode juga.
1. Menerapkan ulang API ke tahap yang sama. Jika Anda menerapkan API ke tahap baru, pastikan untuk memperbarui paket penggunaan untuk melampirkan tahap API baru.
Klien sekarang dapat memanggil metode yang diperlukan kunci API tanpa secara eksplisit memasok kunci API apa pun. Kunci API yang dikembalikan authorizer digunakan secara otomatis.