Menggunakan plugin

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

Edge Microgateway v. 3.1.5 dan yang lebih baru

Audiens

Topik ini ditujukan bagi operator Edge Microgateway yang ingin menggunakan plugin yang sudah ada yang diinstal dengan microgateway. Plugin ini juga membahas plugin pembatasan 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 ada yang disertakan dengan Edge Microgateway

Beberapa plugin yang ada disediakan dengan Edge Microgateway saat penginstalan. Hal ini mencakup:

Tempat menemukan plugin yang ada

Plugin yang ada dan dibundel dengan Edge Microgateway terletak di sini, dengan [prefix] adalah 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 Melakukan perubahan konfigurasi untuk opsi.
3. Tambahkan plugin ke elemen plugins:sequence file konfigurasi, seperti berikut. Plugin dijalankan sesuai urutan kemunculannya 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

4. Konfigurasi plugin. Beberapa plugin memiliki parameter opsional yang dapat Anda konfigurasi di file konfigurasi. Misalnya, Anda dapat menambahkan stanza berikut untuk mengonfigurasi plugin spike arrest. Lihat Menggunakan plugin penahan lonjakan untuk mengetahui 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

5. Simpan file.
6. Mulai ulang atau muat ulang Edge Microgateway, bergantung pada file konfigurasi yang Anda edit.

Konfigurasi khusus plugin

Anda dapat mengganti parameter plugin yang ditentukan dalam file konfigurasi dengan membuat konfigurasi khusus plugin di 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 peredam lonjakan

Plugin penahan lonjakan melindungi dari lonjakan traffic. Kebijakan ini membatasi jumlah permintaan yang diproses oleh instance Edge Microgateway.

Menambahkan plugin penahan lonjakan

Lihat Menambahkan dan mengonfigurasi plugin.

Contoh konfigurasi untuk penahanan 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 penahanan lonjakan

• timeUnit: Seberapa sering periode eksekusi penahanan 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, spike arrest menyimpan jumlah permintaan ini dalam buffer. Segera setelah "periode" eksekusi berikutnya terjadi, permintaan yang di-buffer akan diproses terlebih dahulu. Lihat juga Menambahkan buffer.

Bagaimana cara kerja penekanan lonjakan?

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

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

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

spikearrest:
   timeUnit: minute
   allow: 30

Saat pengujian, Anda mungkin berpikir bahwa Anda dapat mengirim 30 permintaan dalam 1 detik, selama permintaan tersebut masuk dalam satu menit. Namun, kebijakan tidak menerapkan setelan dengan cara tersebut. Jika dipikir-pikir, 30 permintaan dalam periode 1 detik dapat dianggap sebagai lonjakan kecil di beberapa lingkungan.

Lalu, apa yang sebenarnya terjadi? Untuk mencegah perilaku seperti lonjakan, penahanan lonjakan memperlancar traffic yang diizinkan dengan membagi setelan Anda ke dalam interval yang lebih kecil, sebagai berikut:

Tarif per menit

Rasio per menit dihaluskan menjadi interval detik yang diizinkan untuk permintaan. Misalnya, 30 permintaan per menit akan dihaluskan 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

Rasio per detik dihaluskan menjadi permintaan yang diizinkan dalam interval milidetik. Misalnya, 10 permintaan/detik akan dihaluskan seperti ini:

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

Jika batas terlampaui

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

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

Menambahkan buffer

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

Jika Anda menjalankan beberapa proses Edge Micro

Jumlah permintaan yang diizinkan bergantung pada jumlah proses pekerja Edge Micro yang sedang berjalan. Pembatasan lonjakan 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 pembatasan lonjakan dipicu pada 100 permintaan dalam jangka waktu tertentu, dan jika Anda memulai Edge Microgateway dengan opsi --processes 4, tetapkan allow: 25 dalam konfigurasi pembatasan lonjakan. Singkatnya, aturan umumnya adalah menetapkan parameter konfigurasi allow ke nilai "jumlah penekanan lonjakan yang diinginkan / jumlah proses".

Menggunakan plugin kuota

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

Menambahkan plugin kuota

Lihat Menambahkan dan mengonfigurasi plugin.

Konfigurasi produk di Apigee Edge

Anda 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 kompatibel dengan microgateway yang ingin Anda terapkan kuotanya.
   1. Di UI, pilih Produk dari menu Publikasikan.
   2. Buka produk yang berisi API yang kuotanya ingin Anda terapkan.
   3. Klik Edit.
   4. Di kolom Kuota, tentukan interval kuota. Misalnya, 100 permintaan setiap satu menit. Atau 50.000 permintaan setiap 2 jam.
      
      

3. Klik Simpan.
4. 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 yang 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
...

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

edgemicro:
...
quotas:
  failOpen: true

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

{
    "allowed": 20,
    "used": 3,
    "exceeded": 0,
    "available": 17,
    "expiryTime": 1570748640000,
    "timestamp": 1570748580323,
    "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
}

Memahami cara penghitungan kuota

Secara default, microgateway menyinkronkan penghitung kuotanya dengan Apigee Edge setiap 5 detik jika interval kuota ditetapkan ke "menit". Jika interval ditetapkan ke tingkat yang lebih tinggi dari "menit", seperti "minggu" atau "bulan", periode refresh default 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, jam, hari, minggu, atau 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 quota Edge Microgateway tidak menetapkan interval kuota; melainkan, memberikan cara untuk menyesuaikan frekuensi saat 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 1000000 permintaan per bulan

Dengan mempertimbangkan setelan kuota tersebut, bagaimana plugin quota Edge Microgateway harus dikonfigurasi? Praktik terbaiknya adalah mengonfigurasi Edge Microgateway dengan interval sinkronisasi yang lebih rendah daripada 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 disetel ke interval "menit". Edge Microgateway akan disinkronkan ke Edge setelah setiap permintaan ke-50 atau 5 detik, mana saja yang terjadi 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 microgateway ditetapkan ke jumlah kuota yang diambil.

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

Memahami cakupan kuota

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

Menggunakan penyimpanan pendukung Redis untuk kuota

Untuk menggunakan penyimpanan pendukung Redis untuk kuota, gunakan konfigurasi yang sama dengan yang digunakan untuk fitur Synchronizer. Berikut adalah konfigurasi dasar yang diperlukan untuk menggunakan Redis bagi penyimpanan kuota:

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

quotas:
  useRedis: true

Menguji plugin kuota

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

{"error": "exceeded quota"}

Apa perbedaan antara pembatasan lonjakan dan kuota?

Penting untuk memilih alat yang tepat untuk pekerjaan yang sedang dilakukan. Kebijakan kuota mengonfigurasi jumlah pesan permintaan yang diizinkan untuk dikirimkan oleh aplikasi klien ke API selama satu jam, hari, minggu, atau bulan. Kebijakan kuota menerapkan batas penggunaan pada aplikasi klien dengan mempertahankan penghitung terdistribusi yang mencatat permintaan masuk.

Gunakan kebijakan kuota untuk memberlakukan kontrak bisnis atau SLA dengan developer dan partner, bukan untuk pengelolaan traffic operasional. Misalnya, kuota dapat digunakan untuk membatasi traffic layanan gratis, sekaligus mengizinkan akses penuh bagi pelanggan berbayar.

Gunakan penahanan lonjakan untuk melindungi dari lonjakan traffic API yang tiba-tiba. Biasanya, pembatasan lonjakan digunakan untuk mencegah kemungkinan serangan DDoS atau serangan berbahaya lainnya.