Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi
Apigee X. info

Apa
Kebijakan Verifikasi Kunci API memungkinkan Anda menerapkan verifikasi kunci API saat runtime, sehingga hanya aplikasi dengan kunci API yang disetujui yang dapat mengakses API Anda. Kebijakan ini memastikan bahwa kunci API valid, belum dicabut, dan disetujui untuk menggunakan resource tertentu yang terkait dengan produk API Anda.
Contoh
Kunci di parameter kueri
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.queryparam.apikey" /> </VerifyAPIKey>
Dalam contoh ini, kebijakan mengharapkan untuk menemukan kunci API dalam variabel alur yang disebut
request.queryparam.apikey
. Variabel request.queryparam.{name}
adalah variabel alur Edge standar yang diisi dengan nilai parameter kueri yang diteruskan
dalam permintaan klien.
Perintah curl
berikut meneruskan kunci API dalam parameter kueri:
curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls
Kunci di header
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.header.x-apikey" /> </VerifyAPIKey>
Dalam contoh ini, kebijakan mengharapkan untuk menemukan kunci API dalam variabel alur yang disebut
request.header.x-apikey
. Variabel request.header.{name}
adalah variabel alur Edge standar yang diisi dengan nilai header yang diteruskan
dalam permintaan klien.
cURL berikut menunjukkan cara meneruskan kunci API di header:
curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"
Kunci dalam variabel
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="requestAPIKey.key"/> </VerifyAPIKey>
Kebijakan dapat merujuk ke variabel apa pun yang berisi kunci. Kebijakan dalam contoh ini mengekstrak kunci API dari variabel bernama requestAPIKey.key.
Cara pengisian variabel tersebut terserah Anda. Misalnya, Anda dapat menggunakan kebijakan Extract Variables untuk mengisi requestAPIKey.key dari parameter kueri bernama myKey, seperti yang ditunjukkan di bawah:
<ExtractVariables async="false" continueOnError="false" enabled="true" name="SetAPIKeyVar"> <Source>request</Source> <QueryParam name="myKey"> <Pattern ignoreCase="true">{key}</Pattern> </QueryParam> <VariablePrefix>requestAPIKey</VariablePrefix> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>
Variabel alur kebijakan akses
<AssignMessage async="false" continueOnError="false" enabled="true" name="accessverifyvars"> <AssignVariable> <Name>devFirstName</Name> <Ref>verifyapikey.verify-api-key.developer.firstName</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>devLastName</Name> <Ref>verifyapikey.verify-api-key.developer.lastName</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>devEmail</Name> <Ref>verifyapikey.verify-api-key.developer.email</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
Edge otomatis mengisi serangkaian variabel alur saat menjalankan kebijakan Verifikasi Kunci API untuk kunci API yang valid. Anda dapat menggunakan variabel ini untuk mengakses informasi seperti nama aplikasi, ID aplikasi, dan informasi tentang developer atau perusahaan yang mendaftarkan aplikasi. Dalam contoh di atas, Anda menggunakan kebijakan Assign Message untuk mengakses nama depan, nama belakang, dan alamat email developer setelah Verify API Key dieksekusi.
Semua variabel ini diawali dengan:
verifyapikey.{policy_name}
Dalam contoh ini, nama kebijakan Verify API key adalah "verify-api-key". Oleh karena itu, Anda mereferensikan
nama depan developer yang membuat permintaan dengan mengakses
variabel verifyapikey.verify-api-key.developer.firstName.
Mempelajari Edge
Tentang kebijakan Verify API Key
Saat developer mendaftarkan aplikasi di Edge, Edge akan otomatis membuat pasangan kunci rahasia dan konsumen. Anda dapat melihat pasangan kunci konsumen dan rahasia aplikasi di UI Edge atau mengaksesnya dari Edge API.
Pada saat pendaftaran aplikasi, developer memilih satu atau beberapa produk API untuk dikaitkan dengan aplikasi, dengan produk API adalah kumpulan resource yang dapat diakses melalui proxy API. Kemudian, developer meneruskan kunci API (kunci konsumen) sebagai bagian dari setiap permintaan ke API dalam produk API yang terkait dengan aplikasi. Lihat Ringkasan publikasi untuk mengetahui informasi selengkapnya.
Kunci API dapat digunakan sebagai token autentikasi, atau dapat digunakan untuk mendapatkan token akses OAuth. Di OAuth, kunci API disebut sebagai "client id". Nama-nama tersebut dapat digunakan secara bergantian. Lihat beranda OAuth untuk mengetahui informasi selengkapnya.
Edge otomatis mengisi serangkaian variabel alur saat menjalankan kebijakan Verify API Key. Lihat Variabel alur di bawah untuk mengetahui informasi selengkapnya.
Referensi Elemen
Berikut adalah elemen dan atribut yang dapat Anda konfigurasi pada kebijakan ini:
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1"> <DisplayName>Custom label used in UI</DisplayName> <APIKey ref="variable_containing_api_key"/> </VerifyAPIKey>
Atribut <VerifyAPIKey>
Contoh berikut menunjukkan atribut pada tag <VerifyAPIKey>
:
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
Tabel berikut menjelaskan atribut yang umum untuk semua elemen induk kebijakan:
Atribut | Deskripsi | Default | Ketersediaan |
---|---|---|---|
name |
Nama internal kebijakan. Nilai atribut Secara opsional, gunakan elemen |
T/A | Wajib |
continueOnError |
Tetapkan ke Setel ke |
salah | Opsional |
enabled |
Setel ke Setel ke |
true | Opsional |
async |
Atribut ini tidak digunakan lagi. |
salah | Tidak digunakan lagi |
<DisplayName> elemen
Gunakan selain atribut name
untuk memberi label kebijakan di
editor proxy UI dengan nama natural language yang berbeda.
<DisplayName>Policy Display Name</DisplayName>
Default |
T/A Jika Anda menghapus elemen ini, nilai atribut |
---|---|
Ketersediaan | Opsional |
Jenis | String |
Elemen <APIKey>
Elemen ini menentukan variabel alur yang berisi kunci API. Biasanya, klien mengirimkan kunci API
dalam parameter kueri, header HTTP, atau parameter formulir. Misalnya, jika kunci dikirim di header
yang disebut x-apikey
, kunci akan ditemukan dalam variabel: request.header.x-apikey
Default | NA |
---|---|
Ketersediaan | Wajib |
Jenis | String |
Atribut
Tabel berikut menjelaskan atribut elemen <APIKey>
Atribut | Deskripsi | Default | Ketersediaan |
---|---|---|---|
ref |
Referensi ke variabel yang berisi kunci API. Hanya satu lokasi yang diizinkan per kebijakan. |
T/A | Wajib |
Contoh
Dalam contoh ini, kunci diteruskan dalam parameter dan header yang disebut x-apikey
.
Sebagai parameter kueri:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.queryparam.x-apikey"/> </VerifyAPIKey>
Sebagai header HTTP:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.header.x-apikey"/> </VerifyAPIKey>
Sebagai parameter formulir HTTP:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.formparam.x-apikey"/> </VerifyAPIKey>
Skema
Variabel alur
Jika kebijakan Verifikasi Kunci API diterapkan pada kunci API yang valid, Edge akan mengisi serangkaian variabel aliran. Variabel ini tersedia untuk kebijakan atau kode yang dieksekusi nanti dalam alur, dan sering digunakan untuk melakukan pemrosesan kustom berdasarkan atribut kunci API seperti nama aplikasi, produk API yang digunakan untuk mengotorisasi kunci, atau atribut kustom kunci API.
Kebijakan ini mengisi beberapa jenis variabel alur yang berbeda, termasuk:
- Umum
- Aplikasi
- Developer
- Perusahaan
- Analytics
Setiap jenis variabel alur memiliki awalan yang berbeda. Semua variabel adalah skalar kecuali yang secara khusus ditunjukkan sebagai array.
Variabel alur umum
Tabel berikut mencantumkan variabel alur umum yang diisi oleh kebijakan Verifikasi Kunci API. Semua variabel ini diawali dengan:
verifyapikey.{policy_name}
Contoh: verifyapikey.{policy_name}.client_id
Variabel yang tersedia meliputi:
Variabel | Deskripsi |
---|---|
client_id |
Kunci konsumen (alias kunci API atau kunci aplikasi) yang disediakan oleh aplikasi yang meminta. |
client_secret |
Rahasia konsumen yang terkait dengan kunci konsumen. |
redirection_uris |
URI pengalihan apa pun dalam permintaan. |
developer.app.id |
ID aplikasi developer yang membuat permintaan. |
developer.app.name |
Nama aplikasi dari aplikasi developer yang membuat permintaan. |
developer.id |
ID developer yang terdaftar sebagai pemilik aplikasi yang meminta. |
developer.{custom_attrib_name} |
Atribut khusus apa pun yang berasal dari profil kunci aplikasi |
DisplayName |
Nilai atribut <DisplayName> kebijakan. |
failed |
Ditetapkan ke "true" jika validasi Kunci API gagal. |
{custom_app_attrib} |
Atribut kustom apa pun yang berasal dari profil aplikasi. Tentukan nama atribut kustom. |
apiproduct.name* |
Nama produk API yang digunakan untuk memvalidasi permintaan. |
apiproduct.{custom_attrib_name}* |
Atribut kustom apa pun yang berasal dari profil produk API. |
apiproduct.developer.quota.limit* |
Batas kuota yang ditetapkan pada produk API, jika ada. |
apiproduct.developer.quota.interval* |
Interval kuota yang ditetapkan pada produk API, jika ada. |
apiproduct.developer.quota.timeunit* |
Unit waktu kuota yang ditetapkan pada produk API, jika ada. |
* Variabel produk API diisi secara otomatis jika produk API dikonfigurasi dengan lingkungan, proxy, dan resource yang valid (berasal dari
proxy.pathsuffix ). Untuk mengetahui petunjuk tentang cara menyiapkan produk API, lihat
Menggunakan Edge
Management API untuk Memublikasikan API. |
Variabel alur aplikasi
Variabel alur berikut yang berisi informasi tentang aplikasi diisi oleh kebijakan. Semua variabel ini diawali dengan:
verifyapikey.{policy_name}.app
.
Contoh:
verifyapikey.{policy_name}.app.name
Variabel yang tersedia meliputi:
Variabel | Deskripsi |
---|---|
name |
Nama aplikasi. |
id |
ID aplikasi. |
accessType |
Tidak digunakan oleh Apigee. |
callbackUrl |
URL callback aplikasi. Biasanya hanya digunakan untuk OAuth. |
DisplayName |
Nama tampilan aplikasi. |
status |
Status aplikasi, seperti 'disetujui' atau 'dicabut'. |
apiproducts |
Array yang berisi daftar produk API yang terkait dengan aplikasi. |
appFamily |
Setiap keluarga aplikasi yang berisi aplikasi, atau "default". |
appParentStatus |
Status induk aplikasi, seperti 'aktif' atau 'tidak aktif' |
appType |
Jenis aplikasi, sebagai "Perusahaan" atau "Developer". |
appParentId |
ID aplikasi induk. |
created_at |
Stempel tanggal/waktu saat aplikasi dibuat. |
created_by |
Alamat email developer yang membuat aplikasi. |
last_modified_at |
Stempel tanggal/waktu saat aplikasi terakhir diperbarui. |
last_modified_by |
Alamat email developer yang terakhir kali memperbarui aplikasi. |
{app_custom_attributes} |
Atribut aplikasi kustom apa pun. Tentukan nama atribut kustom. |
Variabel alur developer
Variabel alur berikut yang berisi informasi tentang developer diisi oleh kebijakan. Semua variabel ini diawali dengan:
verifyapikey.{policy_name}.developer
Contoh:
verifyapikey.{policy_name}.developer.id
Variabel yang tersedia meliputi:
Variabel | Deskripsi |
---|---|
id |
Menampilkan {org_name}@@@{developer_id} |
userName |
Nama pengguna developer. |
firstName |
Nama depan developer. |
lastName |
Nama belakang developer. |
email |
Alamat email developer. |
status |
Status developer, sebagai aktif, tidak aktif, atau login_lock. |
apps |
Array aplikasi yang terkait dengan developer. |
created_at |
Stempel tanggal/waktu saat developer dibuat. |
created_by |
Alamat email pengguna yang membuat developer. |
last_modified_at |
Stempel tanggal/waktu saat developer terakhir diubah. |
last_modified_by |
Alamat email pengguna yang mengubah developer. |
{developer_custom_attributes} |
Atribut developer kustom apa pun. Tentukan nama atribut kustom. |
Company |
Nama perusahaan, jika ada, yang terkait dengan developer. |
Variabel alur perusahaan
Variabel alur berikut yang berisi informasi tentang perusahaan diisi oleh kebijakan. Semua variabel ini diawali dengan:
verifyapikey.{policy_name}.company
Contoh:
verifyapikey.{policy_name}.company.name
Variabel yang tersedia meliputi:
Variabel | Deskripsi |
---|---|
name |
Nama perusahaan. |
displayName |
Nama tampilan perusahaan. |
id |
ID perusahaan. |
apps |
Array yang berisi daftar aplikasi perusahaan. |
appOwnerStatus |
Status pemilik aplikasi, sebagai aktif, tidak aktif, atau login_lock.
|
created_at |
Stempel tanggal/waktu saat perusahaan dibuat. |
created_by |
Alamat email pengguna yang membuat perusahaan. |
last_modified_at |
Stempel tanggal/waktu saat perusahaan terakhir diubah. |
last_modified_by |
Alamat email pengguna yang terakhir mengubah perusahaan. |
{company_custom_attributes} |
Atribut perusahaan kustom apa pun. Tentukan nama atribut kustom. |
Variabel Analytics
Variabel berikut diisi secara otomatis di Analytics saat kebijakan Verifikasi Kunci API diterapkan untuk kunci API yang valid. Variabel ini hanya diisi oleh kebijakan Verify API Key dan kebijakan OAuth.
Variabel dan nilai dapat digunakan sebagai dimensi untuk membuat laporan Analytics guna mendapatkan visibilitas ke dalam pola penggunaan oleh developer dan aplikasi.
- apiproduct.name
- developer.app.name
- client_id
- developer.id
Referensi error
Bagian ini menjelaskan kode kesalahan dan pesan kesalahan yang dikembalikan dan variabel kesalahan yang disetel oleh Edge saat kebijakan ini memicu kesalahan. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan kesalahan untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Penanganan kesalahan.
Error runtime
Error ini dapat terjadi saat kebijakan dijalankan.
Kode error | Status HTTP | Penyebab |
---|---|---|
keymanagement.service.CompanyStatusNotActive |
401 | Perusahaan yang terkait dengan Aplikasi Pengembang yang memiliki kunci API yang Anda gunakan memiliki status tidak aktif. Jika status Perusahaan disetel ke tidak aktif, Anda tidak dapat mengakses developer atau aplikasi yang terkait dengan Perusahaan tersebut. Admin org dapat mengubah status Perusahaan menggunakan API pengelolaan. Lihat Menetapkan Status milik suatu Perusahaan. |
keymanagement.service.DeveloperStatusNotActive |
401 |
Developer yang membuat Aplikasi Developer yang memiliki kunci API yang Anda gunakan memiliki status tidak aktif. Jika status Pengembang Aplikasi disetel ke tidak aktif, semua Aplikasi Pengembang yang dibuat oleh pengembang tersebut dinonaktifkan. Pengguna admin dengan izin yang sesuai (seperti Administrator Organisasi) dapat mengubah status developer di beberapa hal cara:
|
keymanagement.service.invalid_client-app_not_approved |
401 | Aplikasi Developer yang terkait dengan kunci API dicabut. Aplikasi yang dicabut tidak dapat mengakses produk API apa pun dan tidak dapat memanggil API apa pun yang dikelola oleh Apigee Edge. Admin org dapat mengubah status Aplikasi Developer menggunakan API pengelolaan. Lihat Menyetujui atau Mencabut Aplikasi Developer. |
oauth.v2.FailedToResolveAPIKey |
401 | Kebijakan ini mengharapkan menemukan kunci API dalam variabel yang ditentukan dalam <APIKey> elemen ini. Error ini muncul jika ekspektasi variabel tidak ada (tidak dapat diselesaikan). |
oauth.v2.InvalidApiKey |
401 | Kunci API diterima oleh Edge, tetapi tidak valid. Saat Edge mencari kunci pada {i>database<i}, itu harus sama persis dengan yang dikirim dalam permintaan. Jika API berfungsi sebelumnya, pastikan kunci tidak dibuat ulang. Jika kunci telah dibuat ulang, Anda akan melihat kesalahan ini jika Anda mencoba menggunakan kunci lama. Untuk detailnya, lihat Mendaftarkan aplikasi dan mengelola API . |
oauth.v2.InvalidApiKeyForGivenResource |
401 | Kunci API diterima oleh Edge, dan valid; namun, tidak sesuai dengan kunci yang disetujui di Aplikasi Developer yang terkait dengan proxy API Anda melalui Produk. |
Error saat deployment
Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.
Nama error | Penyebab |
---|---|
SpecifyValueOrRefApiKey |
Elemen <APIKey> tidak memiliki nilai atau kunci yang ditentukan. |
Variabel kesalahan
Variabel ini ditetapkan saat terjadi error runtime. Untuk informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.
Variabel | Di mana | Contoh |
---|---|---|
fault.name="fault_name" |
fault_name adalah nama kesalahan, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan. | fault.name Matches "FailedToResolveAPIKey" |
oauthV2.policy_name.failed |
policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan. | oauthV2.VK-VerifyAPIKey.failed = true |
Contoh respons error
{ "fault":{ "faultstring":"Invalid ApiKey", "detail":{ "errorcode":"oauth.v2.InvalidApiKey" } } }
{ "fault":{ "detail":{ "errorcode":"keymanagement.service.DeveloperStatusNotActive" }, "faultstring":"Developer Status is not Active" } }
Contoh aturan kesalahan
<FaultRule name="FailedToResolveAPIKey"> <Step> <Name>AM-FailedToResolveAPIKey</Name> </Step> <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition> </FaultRule>