Kebijakan VerifyAPIKey

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

Apa

Kebijakan Verify API Key memungkinkan Anda menerapkan verifikasi kunci API saat runtime, aplikasi dengan kunci API yang disetujui akan mengakses API Anda. Kebijakan ini memastikan bahwa kunci API valid, memiliki belum dicabut, dan disetujui untuk menggunakan sumber daya tertentu yang terkait dengan API Google.

Contoh

Kunci dalam parameter kueri

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>

Dalam contoh ini, kebijakan mengharapkan 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 akan meneruskan kunci API dalam parameter kueri:

curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls

{i>Key in header<i}

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey" />
</VerifyAPIKey>

Dalam contoh ini, kebijakan mengharapkan menemukan kunci API dalam variabel alur yang disebut request.header.x-apikey. Variabel request.header.{name} adalah variabel aliran 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"

Variabel kunci

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="requestAPIKey.key"/>
</VerifyAPIKey>

Kebijakan ini dapat mereferensikan variabel apa pun yang berisi kunci. Kebijakan dalam contoh ini mengekstrak kunci API dari variabel bernama requestAPIKey.key.

Anda bebas menentukan cara variabel tersebut diisi. Misalnya, Anda bisa menggunakan alat Kebijakan variabel untuk mengisi requestAPIKey.key dari parameter kueri bernama myKey, seperti ditunjukkan di bawah ini:

<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 secara otomatis mengisi rangkaian variabel alur saat mengeksekusi Kunci Verifikasi API kebijakan untuk kunci API yang valid. Anda dapat menggunakan variabel ini untuk mengakses informasi seperti aplikasi nama, ID aplikasi, dan informasi tentang pengembang atau perusahaan yang mendaftarkan aplikasi tersebut. Di kolom contoh di atas, Anda menggunakan kebijakan Tetapkan Pesan untuk mengakses nama depan, nama belakang pengembang nama, dan alamat email setelah Kunci Verifikasi API dieksekusi.

Semua variabel ini diawali oleh:

verifyapikey.{policy_name}

Dalam contoh ini, nama kebijakan kunci Verify API adalah "verify-api-key". Oleh karena itu, Anda mereferensikan nama depan developer yang membuat permintaan dengan mengakses variabel verifyapikey.verify-api-key.developer.firstName.

Pelajari Edge


Tentang kebijakan Verify API Key

Saat pengembang mendaftarkan aplikasi di Edge, Edge secara otomatis menghasilkan kunci konsumen dan pasangan secret. Anda dapat melihat kunci konsumen dan pasangan 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, yang mana produk API merupakan kumpulan resource dapat diakses melalui proxy API. Developer kemudian 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 akses OAuth token kata. Di OAuth, kunci API disebut sebagai "client id". Nama tersebut dapat digunakan secara bergantian. Lihat beranda OAuth untuk mengetahui informasi selengkapnya.

Edge secara otomatis mengisi serangkaian variabel alur saat menjalankan kebijakan Verify API Key. Lihat Alur variabel di bawah ini untuk mengetahui informasi lebih lanjut.

Referensi Elemen

Berikut adalah elemen dan atribut yang dapat Anda konfigurasi di 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>

&lt;VerifyAPIKey&gt; atribut

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 name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter.

Secara opsional, gunakan elemen <DisplayName> untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural language yang berbeda.

T/A Wajib
continueOnError

Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Diharapkan untuk sebagian besar kebijakan.

Setel ke true agar eksekusi alur dapat dilanjutkan bahkan setelah kebijakan gagal.

salah Opsional
enabled

Setel ke true untuk menerapkan kebijakan.

Setel ke false untuk menonaktifkan kebijakan. Kebijakan ini tidak akan ditegakkan meskipun tetap terikat pada alur.

true Opsional
async

Atribut ini tidak digunakan lagi.

salah Tidak digunakan lagi

&lt;DisplayName&gt; 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 name kebijakan akan menjadi data

Ketersediaan Opsional
Jenis String

&lt;APIKey&gt; elemen

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 dalam header disebut x-apikey, kuncinya 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
referensi

Referensi ke variabel yang berisi kunci API. Hanya satu lokasi yang diizinkan sesuai dengan 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 flow

Saat kebijakan Verify API Key diterapkan pada kunci API yang valid, Edge akan mengisi rangkaian alur variabel. Variabel-variabel ini tersedia untuk kebijakan atau kode yang dieksekusi nanti dalam alur, dan yang sering digunakan untuk melakukan pemrosesan khusus berdasarkan atribut kunci API seperti nama aplikasi, produk API yang digunakan untuk memberi otorisasi pada kunci, atau atribut khusus 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 ditunjukkan secara khusus sebagai himpunan (array).

Variabel aliran umum

Tabel berikut mencantumkan variabel alur umum yang diisi oleh kebijakan Verify API Key. Semua variabel ini diawali oleh:

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 diberikan 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 <DisplayName> kebijakan .
failed Tetapkan ke "true" saat validasi Kunci API gagal.
{custom_app_attrib} Atribut khusus apa pun yang berasal dari profil aplikasi. Tentukan nama pelanggan .
apiproduct.name* Nama produk API yang digunakan untuk memvalidasi permintaan.
apiproduct.{custom_attrib_name}* Atribut khusus 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 dengan lingkungan, proxy, dan resource yang valid (berasal dari proxy.pathsuffix). Untuk mendapatkan petunjuk tentang cara menyiapkan produk API, lihat Menggunakan Edge management API ke Publish API.

Variabel alur aplikasi

Variabel alur berikut yang berisi informasi tentang aplikasi akan diisi oleh kebijakan. Semua variabel ini diawali oleh:

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 berisi daftar produk API yang terkait dengan aplikasi.
appFamily Semua kelompok aplikasi yang berisi aplikasi, atau "default".
appParentStatus Status induk aplikasi, seperti 'aktif' atau 'tidak aktif'
appType Jenis aplikasi, baik 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 Tanggal/waktu stempel waktu aplikasi terakhir diupdate.
last_modified_by Alamat email developer yang terakhir kali mengupdate aplikasi.
{app_custom_attributes} Atribut aplikasi khusus apa pun. Tentukan nama atribut khusus.

Variabel alur developer

Variabel alur berikut yang berisi informasi tentang developer diisi oleh lebih lanjut. Semua variabel ini diawali oleh:

verifyapikey.{policy_name}.developer

Contoh:

verifyapikey.{policy_name}.developer.id

Variabel yang tersedia meliputi:

Variabel Deskripsi
id Mengembalikan {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} Semua atribut developer kustom. Tentukan nama atribut khusus.
Company Nama perusahaan, jika ada, yang terkait dengan developer.

Variabel alur perusahaan

Variabel alur berikut yang berisi informasi tentang perusahaan diisi oleh lebih lanjut. Semua variabel ini diawali oleh:

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 khusus apa pun. Tentukan nama atribut khusus.

Variabel Analytics

Variabel berikut secara otomatis diisi di Analytics saat kebijakan Verifikasi Kunci API diterapkan untuk kunci API yang valid. Variabel ini hanya diisi oleh Kunci Verify API dan beberapa kebijakan OAuth.

Variabel dan nilai dapat digunakan sebagai dimensi untuk membuat laporan Analytics guna memperoleh visibilitas terhadap pola konsumsi 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 &lt;APIKey&gt; 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>

Topik terkait