Menggunakan plugin

Anda sedang melihat dokumentasi Apigee Edge.
Lihat dokumentasi Apigee X.

Edge Microgateway v. 3.3.x

Audiens

Topik ini ditujukan untuk operator Edge Microgateway yang ingin menggunakan plugin yang sudah ada yang diinstal dengan microgateway. Halaman ini juga membahas plugin lonjakan dan kuota secara mendetail (keduanya disertakan dengan penginstalan). Jika Anda adalah developer yang ingin mengembangkan plugin baru, lihat Mengembangkan plugin kustom.

Apa yang dimaksud dengan plugin Edge Microgateway?

Plugin adalah modul Node.js yang menambahkan fungsi ke Edge Microgateway. Modul plugin mengikuti pola yang konsisten dan disimpan di lokasi yang diketahui oleh Edge Microgateway, sehingga microgateway dapat menemukan dan memuatnya secara otomatis. Edge Microgateway menyertakan beberapa plugin yang sudah ada dan Anda juga dapat membuat plugin kustom, seperti yang dijelaskan dalam Mengembangkan plugin kustom.

Plugin yang sudah ada dipaketkan dengan Edge Microgateway

Sejumlah plugin dilengkapi Edge Microgateway saat penginstalan. Tabel berikut menjelaskan beberapa plugin yang paling umum digunakan.

Plugin Diaktifkan secara default Deskripsi
analytics Ya Mengirim data analisis dari Edge Microgateway ke Apigee Edge.
oauth Ya Menambahkan token OAuth dan validasi Kunci API ke Edge Microgateway. Lihat Menyiapkan dan mengonfigurasi Edge Microgateway.
kuota Tidak Menerapkan kuota pada permintaan ke Edge Microgateway. Menggunakan Apigee Edge untuk menyimpan dan mengelola kuota. Lihat Menggunakan plugin kuota.
spikearrest Tidak Melindungi dari lonjakan traffic dan serangan DoS. Lihat Menggunakan plugin tangkapan lonjakan.
header-uppercase Tidak Proxy contoh yang diberi komentar yang dimaksudkan sebagai panduan untuk membantu developer menulis plugin kustom. Lihat contoh plugin Edge Microgateway.
akumulasi-permintaan Tidak Mengumpulkan data permintaan ke dalam satu objek sebelum meneruskan data ke pengendali berikutnya dalam rantai plugin. Berguna untuk menulis plugin transformasi yang perlu beroperasi pada satu objek konten permintaan yang terakumulasi.
respons-akumulasi Tidak Mengumpulkan data respons ke dalam satu objek sebelum meneruskan data ke pengendali berikutnya dalam rantai plugin. Berguna untuk menulis plugin transformasi yang perlu beroperasi pada satu objek konten respons yang terakumulasi.
transformasi-uppercase Tidak Mengubah data permintaan atau respons. Plugin ini mewakili penerapan praktik terbaik dari plugin transformasi. Plugin contoh melakukan transformasi trivial (mengonversi data respons atau permintaan menjadi huruf besar); namun, plugin dapat dengan mudah disesuaikan untuk melakukan jenis transformasi lainnya, seperti XML ke JSON.
json2xml Tidak Mentransformasi data permintaan atau respons berdasarkan header penerimaan atau jenis konten. Untuk mengetahui detailnya, lihat dokumentasi plugin di GitHub.
quota-memory Tidak Menerapkan kuota pada permintaan ke Edge Microgateway. Menyimpan dan mengelola kuota dalam memori lokal.
healthcheck Tidak Menampilkan informasi tentang proses Edge Microgateway -- penggunaan memori, penggunaan cpu, dll. Untuk menggunakan plugin ini, panggil URL /healthcheck pada instance Edge Microgateway Anda. Plugin ini dimaksudkan sebagai contoh yang dapat Anda gunakan untuk menerapkan plugin health check Anda sendiri.

Tempat menemukan plugin yang ada

Plugin yang sudah ada yang dipaketkan dengan Edge Microgateway berada di sini, dengan [prefix] sebagai direktori awalan npm. Lihat Di mana Edge Microgateway diinstal jika Anda tidak dapat menemukan direktori ini.

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins

Menambahkan dan mengonfigurasi plugin

Ikuti pola ini untuk menambahkan dan mengonfigurasi plugin:

  1. Hentikan Edge Microgateway.
  2. Buka file konfigurasi Edge Microgateway. Untuk mengetahui detailnya, lihat Mengubah konfigurasi untuk melihat opsinya.
  3. Tambahkan plugin ke elemen plugins:sequence file konfigurasi, seperti berikut. Plugin dieksekusi sesuai urutan yang muncul dalam daftar ini.
edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
     level: info
     dir: /var/tmp
     stats_log_interval: 60
  plugins:
     dir: ../plugins
     sequence:   
     - oauth
     - plugin-name
  1. Konfigurasikan plugin. Beberapa plugin memiliki parameter opsional yang dapat Anda konfigurasi dalam file konfigurasi. Misalnya, Anda dapat menambahkan stanza berikut untuk mengonfigurasi plugin tahan lonjakan. Lihat Menggunakan plugin tangkapan lonjakan untuk informasi selengkapnya.
    edgemicro:
      home: ../gateway
      port: 8000
      max_connections: -1
      max_connections_hard: -1
      logging:
        level: info
        dir: /var/tmp
        stats_log_interval: 60
      plugins:
        dir: ../plugins
        sequence:
          - oauth
          - spikearrest
    spikearrest:
       timeUnit: minute
       allow: 10
    
  1. Simpan file tersebut.
  2. Mulai ulang atau muat ulang Edge Microgateway, bergantung pada file konfigurasi mana yang Anda edit.

Konfigurasi khusus plugin

Anda dapat mengganti parameter plugin yang ditentukan dalam file konfigurasi dengan membuat konfigurasi khusus plugin dalam direktori ini:

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins/config

dengan [prefix] adalah direktori awalan npm. Lihat Di mana Edge Microgateway diinstal jika Anda tidak dapat menemukan direktori ini.

plugins/<plugin_name>/config/default.yaml. Misalnya, Anda dapat menempatkan blok ini di plugins/spikearrest/config/default.yaml, dan blok ini akan menggantikan setelan konfigurasi lainnya.

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

Menggunakan plugin lonjakan lonjakan

Plugin lonjakan lonjakan melindungi dari lonjakan traffic. Kebijakan ini men-throttle jumlah permintaan yang diproses oleh instance Edge Microgateway.

Menambahkan plugin lonjakan

Lihat Menambahkan dan mengonfigurasi plugin.

Contoh konfigurasi untuk penangkapan lonjakan

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - spikearrest
spikearrest:
   timeUnit: minute
   allow: 10
   bufferSize: 5

Opsi konfigurasi untuk penangkapan lonjakan

  • timeUnit: Seberapa sering jendela eksekusi lonjakan lonjakan direset. Nilai yang valid adalah detik atau menit.
  • allow: Jumlah maksimum permintaan yang diizinkan selama timeUnit. Lihat juga Jika Anda menjalankan beberapa proses Edge Micro.
  • bufferSize: (opsional, default = 0) jika bufferSize > 0, lonjakan lonjakan akan menyimpan jumlah permintaan ini dalam buffer. Segera setelah "jendela" eksekusi berikutnya terjadi, permintaan yang di-buffer akan diproses terlebih dahulu. Lihat juga Menambahkan buffering.

Bagaimana cara kerja penangkapan lonjakan?

Anggap penangkapan lonjakan sebagai cara untuk melindungi dari lonjakan traffic secara umum, dan bukan sebagai cara untuk membatasi traffic ke jumlah permintaan tertentu. API dan backend Anda dapat menangani sejumlah traffic tertentu, dan kebijakan tangkapan lonjakan akan membantu Anda memperlancar traffic ke jumlah umum yang Anda inginkan.

Perilaku penghentian lonjakan runtime berbeda dari yang mungkin Anda harapkan dari nilai literal per menit atau per detik yang Anda masukkan.

Misalnya, Anda menentukan tingkat 30 permintaan per menit, seperti ini:

spikearrest:
   timeUnit: minute
   allow: 30

Dalam pengujian, Anda mungkin berpikir bahwa Anda dapat mengirim 30 permintaan dalam 1 detik, selama permintaan tersebut muncul dalam waktu satu menit. Namun, bukan itu cara kebijakan menerapkan setelan. Jika dipikirkan, 30 permintaan dalam periode 1 detik dapat dianggap sebagai lonjakan mini di beberapa lingkungan.

Apa yang sebenarnya terjadi? Untuk mencegah perilaku seperti lonjakan, lonjakan lonjakan memperlancar traffic yang diizinkan dengan membagi setelan menjadi beberapa interval yang lebih kecil, sebagai berikut:

Tarif per menit

Tarif per menit diperhalus menjadi permintaan interval detik yang diizinkan. Misalnya, 30 permintaan per menit diperhalus seperti ini:

60 detik (1 menit) / 30 = interval 2 detik, atau sekitar 1 permintaan diizinkan setiap 2 detik. Permintaan kedua dalam waktu 2 detik akan gagal. Selain itu, permintaan ke-31 dalam satu menit akan gagal.

Tarif per detik

Tarif per detik diperhalus ke dalam permintaan yang diizinkan dalam interval milidetik. Misalnya, 10 permintaan/detik akan dihaluskan seperti ini:

1000 milidetik (1 detik) / 10 = 100 milidetik interval, atau sekitar 1 permintaan diizinkan setiap 100 milidetik . Permintaan kedua dalam 100 md akan gagal. Selain itu, permintaan ke-11 dalam satu detik akan gagal.

Saat batas terlampaui

Jika jumlah permintaan melebihi batas dalam interval waktu yang ditentukan, lonjakan tangkapan akan menampilkan pesan error ini dengan status HTTP 503:

{"error": "spike arrest policy violated"}

Menambahkan buffering

Anda memiliki opsi untuk menambahkan buffering ke kebijakan. Misalnya Anda menetapkan buffering ke 10. Anda akan melihat bahwa API tidak langsung menampilkan error saat Anda melebihi batas penangkapan lonjakan. Sebagai gantinya, permintaan di-buffer (hingga jumlah yang ditentukan), dan permintaan yang di-buffer akan diproses segera setelah jendela eksekusi yang sesuai berikutnya tersedia. bufferSize default adalah 0.

Jika Anda menjalankan beberapa proses Edge Micro

Jumlah permintaan yang diizinkan bergantung pada jumlah proses pekerja Edge Micro yang berjalan. Spike arrest menghitung jumlah permintaan yang diizinkan per proses pekerja. Secara default, jumlah proses Edge Micro sama dengan jumlah CPU di mesin tempat Edge Micro diinstal. Namun, Anda dapat mengonfigurasi jumlah proses pekerja saat memulai Edge Micro menggunakan opsi --processes pada perintah start. Misalnya, jika Anda ingin lonjakan lonjakan terpicu pada 100 permintaan dalam jangka waktu tertentu, dan jika Anda memulai Edge Microgateway dengan opsi --processes 4, tetapkan allow: 25 dalam konfigurasi tangkapan lonjakan. Singkatnya, aturan umumnya adalah menetapkan parameter konfigurasi allow ke nilai "jumlah penangkapan lonjakan yang diinginkan / jumlah proses".

Menggunakan plugin kuota

Kuota menentukan jumlah pesan permintaan yang diizinkan untuk dikirim oleh aplikasi ke API selama satu jam, hari, minggu, atau bulan tersebut. Saat aplikasi mencapai batas kuota, panggilan API berikutnya akan ditolak. Lihat juga Apa perbedaan antara batas dan kuota lonjakan?

Menambahkan plugin kuota

Lihat Menambahkan dan mengonfigurasi plugin.

Konfigurasi produk di Apigee Edge

Anda dapat mengonfigurasi kuota di UI Apigee Edge tempat Anda mengonfigurasi produk API. Anda perlu mengetahui produk mana yang berisi proxy yang kompatibel dengan microgateway yang ingin Anda batasi dengan kuota. Produk ini harus ditambahkan ke aplikasi developer. Saat Anda melakukan panggilan API yang diautentikasi menggunakan kunci di aplikasi developer, kuota akan diterapkan ke panggilan API tersebut.

  1. Login ke akun organisasi Apigee Edge Anda.
  2. Di UI Edge, buka produk yang terkait dengan proxy yang berbasis microgateway tempat Anda ingin menerapkan kuota.
    1. Di UI, pilih Produk dari menu Publikasikan.
    2. Buka produk yang berisi API tempat Anda ingin menerapkan kuota.
    3. Klik Edit.
    4. Di kolom Kuota, tentukan interval kuota. Misalnya, 100 permintaan setiap satu menit. Atau 50.000 permintaan setiap 2 jam.

  1. Klik Simpan.
  2. Pastikan produk ditambahkan ke aplikasi developer. Anda akan memerlukan kunci dari aplikasi ini untuk melakukan panggilan API yang diautentikasi.

Contoh konfigurasi untuk kuota

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota

Opsi konfigurasi untuk kuota

Untuk mengonfigurasi plugin kuota, tambahkan elemen quotas ke file konfigurasi Anda, seperti ditunjukkan dalam contoh berikut:

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota
quotas:
    bufferSize:
      hour: 20000
      minute: 500
      month: 1
      default: 10000
    useDebugMpId: true
    failOpen: true
    isHTTPStatusTooManyRequestEnabled: true
...
Opsi Deskripsi
bufferSize

(Bilangan bulat) Konfigurasi bufferSize memungkinkan Anda menyesuaikan seberapa sering Edge Microgateway menyinkronkan jumlah kuotanya dengan Apigee Edge. Untuk memahami bufferSize, pertimbangkan contoh konfigurasi berikut:

quotas:
 bufferSize:
  minute: 500
  default: 10000
 useDebugMpId: true
 failOpen: true

Secara default, microgateway menyinkronkan penghitung kuotanya dengan Apigee Edge setiap 5 detik jika interval kuota disetel ke "menit". Konfigurasi di atas menyatakan bahwa jika interval kuota ditetapkan di produk API ke "minute", Edge Microgateway akan disinkronkan dengan Edge untuk mendapatkan jumlah kuota saat ini setelah setiap 500 permintaan atau setelah 5 detik, mana saja yang lebih dulu. Untuk mengetahui informasi selengkapnya, lihat Memahami cara penghitungan kuota.

Unit waktu yang diizinkan meliputi: minute, hour, day, week, month, dan default.

isHTTPStatusTooManyRequestEnabled

Mengonfigurasi plugin kuota untuk menampilkan status respons HTTP 429, bukan status 403, jika ada pelanggaran kuota.

Default: false. Secara default, atau jika flag ditetapkan ke false, kuota akan menampilkan status HTTP 403 saat kuota terlampaui.

Jika flag ini disetel ke true, kuota akan menampilkan status HTTP 429 saat kuota terlampaui.

Untuk mengubah status pengembalian HTTP default menjadi 429, gunakan konfigurasi berikut:

edgemicro:
...
quotas:
  isHTTPStatusTooManyRequestEnabled: true
...
failOpen Saat fitur ini diaktifkan, jika terjadi error pemrosesan kuota atau jika permintaan "kuota diterapkan" ke Edge gagal memperbarui penghitung kuota jarak jauh, kuota akan diproses berdasarkan jumlah lokal hanya sampai sinkronisasi kuota jarak jauh berikutnya berhasil. Dalam kedua kasus ini, flag quota-failed-open ditetapkan di objek permintaan.

Untuk mengaktifkan fitur kuota "fail open", tetapkan konfigurasi berikut:

edgemicro:
...
quotas:
  failOpen: true
...
useDebugMpId Tetapkan flag ini ke true untuk mengaktifkan logging ID MP (pemroses pesan) dalam respons kuota.

Untuk menggunakan fitur ini, Anda harus menetapkan konfigurasi berikut:

edgemicro:
...
quotas:
  useDebugMpId: true
...

Jika useDebugMpId disetel, respons kuota dari Edge akan berisi ID MP dan akan dicatat dalam log oleh Edge Microgateway. Contoh:

{
    "allowed": 20,
    "used": 3,
    "exceeded": 0,
    "available": 17,
    "expiryTime": 1570748640000,
    "timestamp": 1570748580323,
    "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
}
useRedis Jika ditetapkan ke true, plugin akan menggunakan Redis untuk penyimpanan cadangan kuota. Untuk mengetahui detailnya, lihat Menggunakan penyimpanan cadangan Redis untuk kuota.

Memahami cara penghitungan kuota

Secara default, microgateway menyinkronkan penghitung kuotanya dengan Apigee Edge setiap 5 detik jika interval kuota disetel ke "menit". Jika interval disetel ke level yang lebih tinggi dari "menit", seperti "minggu" atau "bulan", periode pembaruan default-nya adalah 1 menit.

Penting untuk diperhatikan bahwa Anda menentukan interval kuota dalam produk API yang ditentukan di Apigee Edge. Interval kuota menentukan jumlah permintaan yang diizinkan untuk satu menit, satu jam, satu hari, satu minggu, atau satu bulan. Misalnya, Produk A mungkin memiliki interval kuota 100 permintaan per menit dan Produk B mungkin memiliki interval kuota 10.000 permintaan per jam.

Konfigurasi YAML plugin Edge Microgateway quota tidak menetapkan interval kuota. Namun, konfigurasi ini memberikan cara untuk menyesuaikan frekuensi instance Edge Microgateway lokal menyinkronkan jumlah kuotanya dengan Apigee Edge.

Misalnya, asumsikan ada tiga produk API yang ditentukan di Apigee Edge dengan interval kuota berikut yang ditentukan:

  • Produk A memiliki kuota 100 permintaan per menit
  • Produk B memiliki kuota 5.000 permintaan per jam
  • Produk C memiliki kuota 1000.000 permintaan per bulan

Dengan mempertimbangkan setelan kuota tersebut, bagaimana seharusnya konfigurasi plugin quota Edge Microgateway ? Praktik terbaiknya adalah mengonfigurasi Edge Microgateway dengan interval sinkronisasi yang lebih rendah dari interval kuota yang ditentukan dalam produk API. Contoh:

quotas:
    bufferSize:
      hour: 2000
      minute: 50
      month: 1
      default: 10000

Konfigurasi ini menentukan interval sinkronisasi berikut untuk produk API yang dijelaskan sebelumnya:

  • Produk A ditetapkan ke interval "menit". Edge Microgateway akan disinkronkan ke Edge setelah setiap permintaan ke-50 atau 5 detik, mana saja yang lebih dulu.
  • Produk B ditetapkan ke interval "jam". Edge Microgateway akan disinkronkan ke Edge setelah setiap permintaan ke-2000 atau 1 menit, mana saja yang lebih dulu.
  • Produk C ditetapkan ke interval "bulan". Edge Microgateway akan disinkronkan ke Edge setelah setiap permintaan atau 1 menit, mana saja yang lebih dulu.

Setiap kali instance microgateway disinkronkan dengan Edge, jumlah kuota microgate akan ditetapkan ke jumlah kuota yang diambil.

Setelan bufferSize memungkinkan Anda menyesuaikan sinkronisasi penghitung kuota dengan Edge. Dalam situasi traffic tinggi, setelan bufferSize memungkinkan penghitung buffering disinkronkan sebelum sinkronisasi berbasis waktu default dipicu.

Memahami cakupan kuota

Jumlah kuota dicakupkan ke lingkungan dalam organisasi. Untuk mencapai cakupan ini, Edge Microgateway membuat ID kuota yang merupakan kombinasi dari "org + env + appName + productName".

Menggunakan penyimpanan cadangan Redis untuk kuota

Untuk menggunakan penyimpanan cadangan Redis untuk kuota, gunakan konfigurasi yang sama dengan yang digunakan untuk fitur Sinkronisasi. Berikut adalah konfigurasi dasar yang diperlukan agar Anda dapat menggunakan Redis untuk penyimpanan kuota:

edgemicro:
  redisHost: localhost
  redisPort: 6379
  redisDb: 2
  redisPassword: codemaster

quotas:
  useRedis: true
Untuk detail terkait parameter edgemicro.redis*, lihat Menggunakan sinkronisasi.

Menguji plugin kuota

Jika kuota terlampaui, status HTTP 403 akan ditampilkan ke klien, beserta pesan berikut:

{"error": "exceeded quota"}

Apa perbedaan antara lonjakan dan kuota lonjakan?

Anda harus memilih alat yang tepat untuk tugas yang sedang dikerjakan. Kebijakan kuota mengonfigurasi jumlah pesan permintaan yang diizinkan untuk dikirim oleh aplikasi klien ke API selama satu jam, hari, minggu, atau bulan. Kebijakan kuota menerapkan batas pemakaian pada aplikasi klien dengan mempertahankan penghitung terdistribusi yang menghitung permintaan yang masuk.

Gunakan kebijakan kuota untuk menerapkan kontrak bisnis atau SLA dengan developer dan partner, bukan untuk pengelolaan traffic operasional. Misalnya, kuota dapat digunakan untuk membatasi traffic untuk layanan gratis, sekaligus memungkinkan akses penuh untuk pelanggan yang membayar.

Gunakan penangkapan lonjakan untuk menghindari lonjakan tiba-tiba dalam traffic API. Biasanya, penangkapan lonjakan digunakan untuk mencegah kemungkinan DDoS atau serangan berbahaya lainnya.