Menggunakan plugin

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

Edge Microgateway v. 3.2.x

Audiens

Topik ini ditujukan untuk operator Edge Microgateway yang ingin menggunakan plugin yang ada diinstal dengan microgateway. Artikel ini juga membahas tentang lonjakan penghentian dan kuota di (keduanya disertakan dengan instalasi). Jika Anda seorang developer yang ingin mengembangkan plugin, lihat Mengembangkan plugin kustom.

Apa itu plugin Edge Microgateway?

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

Plugin yang ada yang dipaketkan dengan Edge Microgateway

Beberapa plugin yang ada disediakan dengan Edge Microgateway saat penginstalan. Ini termasuk:

{i>Plugin<i} 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 Setelan 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.
sandang spikear Tidak Melindungi dari lonjakan lalu lintas dan serangan DoS. Lihat Menggunakan plugin penghentian lonjakan.
header-huruf besar Tidak Proxy contoh yang diberi komentar yang dimaksudkan sebagai panduan untuk membantu developer menulis plugin kustom. Lihat Plugin contoh Edge Microgateway.
accumulate-request Tidak Mengumpulkan data permintaan ke dalam satu objek sebelum meneruskan data ke objek berikutnya dalam rantai plugin. Berguna untuk menulis plugin transformasi yang perlu beroperasi pada objek konten permintaan tunggal yang terakumulasi.
accumulate-response Tidak Mengumpulkan data respons ke dalam satu objek sebelum meneruskan data ke objek berikutnya dalam rantai plugin. Berguna untuk menulis plugin transformasi yang perlu beroperasi pada satu objek konten respons terakumulasi.
transformasi huruf kapital Tidak Mentransformasi data permintaan atau respons. Plugin ini mewakili praktik terbaik implementasi plugin transformasi. Plugin contoh melakukan transformasi trivial (mengonversi data permintaan atau respons menjadi huruf besar); Namun, data ini dapat dengan mudah disesuaikan dengan melakukan jenis transformasi lain, seperti XML ke JSON.
json2xm Tidak Mentransformasi data permintaan atau respons berdasarkan header jenis konten atau terima. Sebagai detail, lihat plugin dokumentasi di GitHub.
kuota-memori Tidak Menerapkan kuota pada permintaan ke Edge Microgateway. Menyimpan dan mengelola kuota di penyimpanan lokal memori.
pemeriksaan kesehatan Tidak Menampilkan informasi tentang proses Edge Microgateway -- penggunaan memori, penggunaan cpu, dll. Untuk menggunakan plugin, panggil URL /healthcheck di Edge Anda di instance Microgateway. Plugin ini dimaksudkan sebagai contoh yang dapat Anda gunakan untuk mengimplementasikan plugin health check Anda sendiri.

Tempat menemukan plugin yang ada

Plugin yang sudah ada yang dipaketkan dengan Edge Microgateway berada di sini, tempat [prefix] adalah direktori awalan npm. Lihat Lokasi Edge Microgateway terinstal 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 detailnya, lihat Membuat 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
  1. Konfigurasikan plugin. Beberapa plugin memiliki parameter opsional yang dapat Anda konfigurasi di file konfigurasi. Misalnya, Anda dapat menambahkan stanza berikut untuk mengonfigurasi penghentian lonjakan plugin. Lihat Menggunakan plugin penghentian 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.
  2. 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 Lokasi Edge Microgateway terinstal jika Anda tidak dapat menemukan direktori ini.

plugins/<plugin_name>/config/default.yaml. Misalnya, Anda bisa menempatkan diblokir di plugins/spikearrest/config/default.yaml, dan akan menggantikan pengaturan konfigurasi.

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

Menggunakan plugin penghentian lonjakan

Plugin penangkapan lonjakan melindungi dari lonjakan traffic. Membatasi jumlah permintaan diproses oleh instance Edge Microgateway.

Menambahkan plugin penangkapan 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 penghentian lonjakan direset. Nilai valid adalah detik atau menit.
  • allow: Jumlah permintaan maksimum yang diizinkan selama timeUnit. Lihat Jika Anda menjalankan beberapa Edge Micro proses ini.
  • bufferSize: (opsional, default = 0) jika bufferSize > 0, penangkapan lonjakan menyimpan jumlah permintaan ini dalam {i>buffer.<i} Segera setelah "jendela" eksekusi berikutnya muncul, permintaan yang di-buffer akan diproses terlebih dahulu. Lihat juga Menambahkan {i>buffer<i}.

Bagaimana cara kerja penghentian lonjakan?

Bayangkan lonjakan traffic sebagai cara untuk melindungi secara umum dari lonjakan traffic, bukan sebagai membatasi traffic ke jumlah permintaan tertentu. API dan backend Anda dapat menangani jumlah lalu lintas, dan kebijakan penghentian lonjakan membantu Anda memperlancar lalu lintas ke jumlah umum yang diinginkan.

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

Misalnya, Anda menetapkan tarif 30 permintaan per menit, seperti ini:

spikearrest:
   timeUnit: minute
   allow: 30

Dalam pengujian, Anda mungkin berpikir bisa mengirim 30 permintaan dalam 1 detik, selama permintaan itu dalam satu menit. Tapi itu bukanlah cara kebijakan menerapkan pengaturan itu. Jika Anda memikirkannya, 30 permintaan di dalam periode 1 detik dapat dianggap sebagai lonjakan mini di beberapa lingkungan.

Apa yang sebenarnya terjadi? Untuk mencegah perilaku seperti lonjakan, penghentian lonjakan akan traffic dengan membagi setelan Anda menjadi interval yang lebih kecil, sebagai berikut:

Tarif per menit

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

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

Tarif per detik

Laju per detik akan 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 md . Permintaan kedua dalam waktu 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, penghentian lonjakan mengembalikan pesan error ini dengan status HTTP 503:

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

Menambahkan buffer

Anda memiliki opsi untuk menambahkan buffer ke kebijakan. Katakanlah Anda menetapkan {i>buffer<i} ke 10. Anda akan melihat bahwa API tidak langsung menampilkan error saat Anda melampaui hambatan lonjakan batas tersebut. Sebagai gantinya, permintaan di-buffer (hingga jumlah yang ditentukan), dan permintaan yang di-buffer diproses segera setelah jendela eksekusi berikutnya yang sesuai tersedia. Default bufferSize adalah 0.

Jika Anda menjalankan beberapa Edge Micro proses

Jumlah permintaan yang diizinkan bergantung pada jumlah proses pekerja Edge Micro yang sedang berjalan. Lonjakan hambatan menghitung jumlah permintaan yang diizinkan per proses pekerja. Secara {i>default<i}, jumlah proses Edge Micro sama dengan jumlah CPU di mesin yang memiliki Edge Micro terinstal. Namun, Anda dapat mengonfigurasi jumlah proses pekerja saat memulai Edge Micro menggunakan opsi --processes pada perintah start. Misalnya, jika Anda ingin memicu penghentian lonjakan pada 100 permintaan dalam jangka waktu tertentu, dan jika Anda memulai Edge Microgateway dengan opsi --processes 4, lalu setel allow: 25 di konfigurasi penahanan lonjakan. Singkatnya, aturan praktisnya adalah menetapkan konfigurasi allow parameter ke nilai "jumlah pemrosesan lonjakan yang diinginkan / jumlah proses".

Menggunakan plugin kuota

Kuota menentukan jumlah pesan permintaan yang boleh dikirimkan oleh aplikasi ke API selama satu jam, hari, minggu, atau bulan. Ketika aplikasi mencapai batas kuota, Panggilan API ditolak. Lihat juga Apa perbedaan antara penahanan dan kuota lonjakan?

Menambahkan plugin kuota

Lihat Menambahkan dan mengonfigurasi plugin.

Konfigurasi produk di Apigee Tepi

Anda mengonfigurasi kuota di UI Apigee Edge tempat Anda mengonfigurasi produk API. Anda perlu mengetahui produk mana berisi {i>microgateway-aware proxy<i} yang ingin Anda batasi dengan kuota. Ini harus ditambahkan ke aplikasi pengembang. Saat Anda melakukan panggilan API yang diautentikasi menggunakan 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 microgateway-aware proxy yang 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 Quota, 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 membutuhkan kunci dari aplikasi ini untuk membuat 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
...
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 mengatakan bahwa jika interval kuota disetel di produk API untuk "menit", 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 informasi selengkapnya, lihat Memahami cara penghitungan kuota.

Waktu yang diizinkan unit mencakup: minute, hour, day, week, month, dan default.

failOpen Saat fitur ini diaktifkan, jika terjadi error pemrosesan kuota atau jika "kuota berlaku" permintaan ke Edge gagal memperbarui penghitung kuota jarak jauh, kuota akan diproses berdasarkan jumlah lokal hanya hingga kuota jarak jauh berikutnya berhasil sinkronisasi akan terjadi. Dalam kedua kasus ini, flag quota-failed-open disetel di objek permintaan.

Untuk mengaktifkan kuota "gagal dibuka" , setel konfigurasi berikut:

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

Untuk menggunakan fitur ini, Anda harus menyetel konfigurasi berikut:

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

Jika useDebugMpId disetel, respons kuota dari Edge akan berisi ID MP dan akan dicatat 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 pendukung kuota. Untuk mengetahui detailnya, lihat Menggunakan backing store Redis untuk mendapatkan 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 tingkat yang lebih tinggi dari "menit", seperti "minggu" atau "bulan", periode pembaruan default adalah 1 menit.

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

YAML plugin quota Microgateway Edge konfigurasi tidak menetapkan kuota interval; melainkan menyediakan cara untuk menyesuaikan frekuensi di mana Edge Microgateway lokal instance menyinkronkan kuotanya dengan Apigee Edge.

Sebagai contoh, asumsikan ada tiga produk API yang ditentukan di Apigee Edge dengan interval kuota 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 plugin quota Edge Microgateway dikonfigurasi? 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 menetapkan interval sinkronisasi berikut untuk produk API yang dijelaskan sebelumnya:

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

Setiap kali {i>instance<i} microgateway disinkronkan dengan Edge, antarmuka jumlah kuota ditetapkan ke jumlah kuota yang diambil.

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

Memahami cakupan kuota

Jumlah kuota dibatasi berdasarkan lingkungan di organisasi. Untuk mencapai ruang lingkup ini, Edge Microgateway membuat ID kuota yang merupakan kombinasi dari "org + env + appName + productName".

Menggunakan penyimpanan pendukung Redis untuk mendapatkan kuota

Agar dapat menggunakan penyimpanan cadangan Redis untuk kuota, gunakan konfigurasi yang sama dengan yang digunakan untuk Fitur sinkronisasi. Berikut adalah konfigurasi dasar yang diperlukan untuk menggunakan Redis untuk kuota penyimpanan:

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

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

Menguji plugin kuota

Ketika kuota terlampaui, status HTTP 403 dikembalikan ke klien, bersama dengan pesan berikut:

{"error": "exceeded quota"}

Apa perbedaannya antara penahanan lonjakan dan kuota?

Penting untuk memilih alat yang tepat untuk pekerjaan yang sedang Anda lakukan. Kebijakan kuota dikonfigurasi jumlah pesan permintaan yang diizinkan untuk dikirimkan oleh aplikasi klien ke API selama kursus dalam satu jam, hari, minggu, atau bulan. Kebijakan kuota memberlakukan batas konsumsi pada aplikasi klien dengan dan mempertahankan penghitung terdistribusi yang menghitung permintaan masuk.

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

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