Referensi operasi dan konfigurasi untuk Edge Microgateway

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

Edge Microgateway v. 3.0.x

Topik ini membahas cara mengelola dan mengonfigurasi Edge Microgateway.

Mengupgrade Edge Microgateway jika Anda memiliki koneksi internet

Bagian ini menjelaskan cara mengupgrade penginstalan Edge Microgateway yang sudah ada. Jika Anda beroperasi tanpa koneksi internet, lihat Dapatkah saya menginstal Edge Microgateway tanpa koneksi internet?.

Apigee merekomendasikan agar Anda menguji konfigurasi yang ada dengan ke versi yang baru sebelum meningkatkan lingkungan produksi Anda.

1. Jalankan perintah npm berikut untuk mengupgrade ke Edge versi terbaru Microgateway:

   npm upgrade edgemicro -g

   Untuk mengupgrade ke versi Edge Microgateway tertentu, Anda harus menentukan versinya number di perintah upgrade. Jika Anda tidak menentukan nomor versinya, versi terbaru akan diinstal. Misalnya, untuk mengupgrade ke versi 3.0.2, gunakan perintah berikut:

   npm upgrade edgemicro@3.0.2 -g

2. Lihat nomor versi aplikasi. Misalnya, jika Anda menginstal versi 3.0.2:

   edgemicro --version
   current nodejs version is v12.5.0
   current edgemicro version is 3.0.2
       

3. Terakhir, upgrade ke proxy edgemicro-auth versi terbaru:

   edgemicro upgradeauth -o org_name -e env_name -u username

Membuat perubahan konfigurasi

File konfigurasi yang perlu Anda ketahui meliputi:

• File konfigurasi sistem default
• File konfigurasi default untuk instance Edge Microgateway yang baru diinisialisasi
• File konfigurasi dinamis untuk menjalankan instance

Bagian ini membahas file ini dan hal yang perlu Anda ketahui tentang cara mengubahnya.

Konfigurasi sistem default file

Saat Anda menginstal Edge Microgateway, file konfigurasi sistem default ditempatkan di sini:

prefix/lib/node_modules/edgemicro/config/default.yaml

Dengan prefix adalah direktori awalan npm. Lihat Lokasi Edge Microgateway terinstal jika Anda tidak dapat menemukan direktori ini.

Jika Anda mengubah file konfigurasi sistem, Anda harus menginisialisasi ulang, mengonfigurasi ulang, dan memulai ulang Edge Microgateway:

edgemicro init
edgemicro configure [params]
edgemicro start [params]

File konfigurasi default untuk instance Edge Microgateway yang baru diinisialisasi

Saat Anda menjalankan edgemicro init, file konfigurasi sistem (dijelaskan atas), default.yaml, ditempatkan di direktori ~/.edgemicro.

Jika file konfigurasi di ~/.edgemicro diubah, Anda harus mengonfigurasi ulang dan memulai ulang Microgateway Edge:

edgemicro stop
edgemicro configure [params]
edgemicro start [params]

Dinamis file konfigurasi untuk menjalankan instance

Saat Anda menjalankan edgemicro configure [params], parameter file konfigurasi dibuat di ~/.edgemicro. File tersebut diberi nama sesuai dengan pola: org-env-config.yaml, dengan org dan env adalah nama organisasi dan lingkungan Apigee Edge Anda. Anda dapat menggunakan file ini untuk membuat konfigurasi perubahan, dan kemudian memuat ulang tanpa periode nonaktif. Misalnya, jika Anda menambahkan dan mengkonfigurasi plugin, Anda dapat memuat ulang konfigurasi tanpa menimbulkan periode nonaktif, seperti yang dijelaskan di bawah.

Jika Edge Microgateway berjalan (opsi tanpa periode nonaktif):

1. Muat ulang konfigurasi Edge Microgateway:

   edgemicro reload -o org_name -e env_name -k key -s secret

   Dengan keterangan:

   • org_name adalah nama organisasi Edge Anda (Anda harus merupakan organisasi administrator).
   • env_name adalah lingkungan di organisasi Anda (seperti "test" atau "prod").
   • key adalah kunci yang ditampilkan sebelumnya oleh perintah konfigurasi.
   • secret adalah kunci yang ditampilkan sebelumnya oleh perintah konfigurasi.

   Contoh:

   edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \
     -s 05c14356e42ed1...4e34ab0cc824

Jika Edge Microgateway dihentikan:

1. Mulai ulang Edge Microgateway:

   edgemicro start -o org_name -e env_name -k key -s secret

   Dengan keterangan:

   • org_name adalah nama organisasi Edge Anda (Anda harus merupakan organisasi administrator).
   • env_name adalah lingkungan di organisasi Anda (seperti "test" atau "prod").
   • key adalah kunci yang ditampilkan sebelumnya oleh perintah konfigurasi.
   • secret adalah kunci yang ditampilkan sebelumnya oleh perintah konfigurasi.

   Contoh:

   edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \
     -s 05c1435...e34ab0cc824

Berikut adalah contoh file konfigurasi. Untuk mengetahui detail tentang setelan file konfigurasi, lihat Referensi konfigurasi Edge Microgateway.

edge_config:
  bootstrap: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test
  jwt_public_key: 'https://docs-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://docs-test.apigee.net/edgemicro-auth/products'
edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
headers:
  x-forwarded-for: true
  x-forwarded-host: true
  x-request-id: true
  x-response-time: true
  via: true
oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  verify_api_key_url: 'https://docs-test.apigee.net/edgemicro-auth/verifyApiKey'
analytics:
  uri: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/axpublisher/organization/docs/environment/test

Menyetel variabel lingkungan

Perintah antarmuka command line yang memerlukan nilai untuk organisasi Edge Anda dan serta kunci dan rahasia yang diperlukan untuk memulai Edge Microgateway dapat disimpan di variabel lingkungan:

• EDGEMICRO_ORG
• EDGEMICRO_ENV
• EDGEMICRO_KEY
• EDGEMICRO_SECRET

Menetapkan variabel ini bersifat opsional. Jika telah menetapkannya, Anda tidak perlu menentukan nilainya saat Anda menggunakan Antarmuka Command-Line (CLI) untuk mengonfigurasi dan memulai Edge Microgateway.

Mengonfigurasi SSL di Edge Microgateway server

Tonton video berikut untuk mempelajari tentang mengonfigurasi TLS di Apigee Edge Microgateway:

Anda dapat mengonfigurasi server Microgateway agar menggunakan SSL. Misalnya, dengan SSL yang dikonfigurasi, Anda dapat memanggil API melalui Edge Microgateway dengan "https" , seperti ini:

https://localhost:8000/myapi

Untuk mengkonfigurasi SSL di server Microgateway, ikuti langkah-langkah berikut:

1. Buat atau dapatkan kunci dan sertifikat SSL menggunakan utilitas openssl atau metode apa pun yang Anda sukai.
2. Tambahkan atribut edgemicro:ssl ke file konfigurasi Edge Microgateway. Untuk daftar opsinya, lihat tabel di bawah ini. Contoh:
   

   edgemicro:
     ssl:
      key: <absolute path to the SSL key file>
      cert: <absolute path to the SSL cert file>
      passphrase: admin123 #option added in v2.2.2
      rejectUnauthorized: true #option added in v2.2.2
      requestCert: true

3. Mulai ulang Edge Microgateway. Ikuti langkah-langkah yang diuraikan dalam Membuat perubahan konfigurasi bergantung pada file konfigurasi yang Anda edit: file default atau file konfigurasi runtime.

Berikut adalah contoh bagian edgemicro file konfigurasi, dengan SSL dikonfigurasi:

edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
  ssl:
    key: /MyHome/SSL/em-ssl-keys/server.key
    cert: /MyHome/SSL/em-ssl-keys/server.crt
    passphrase: admin123 #option added in v2.2.2
    rejectUnauthorized: true #option added in v2.2.2

Berikut adalah daftar semua opsi server yang didukung:

Menggunakan opsi SSL/TLS klien

Anda dapat mengonfigurasi Edge Microgateway menjadi klien TLS atau SSL saat terhubung ke target endpoint. Di file konfigurasi Microgateway, gunakan elemen target untuk menetapkan SSL/TLS lainnya.

Contoh ini memberikan setelan yang akan diterapkan ke semua host:

edgemicro:
...
targets:
  ssl:
    client:
      key: /Users/jdoe/nodecellar/twowayssl/ssl/client.key
      cert: /Users/jdoe/nodecellar/twowayssl/ssl/ca.crt
      passphrase: admin123
      rejectUnauthorized: true

Dalam contoh ini, setelan hanya diterapkan ke host yang ditentukan:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    ssl:
      client:
        key: /Users/myname/twowayssl/ssl/client.key
        cert: /Users/myname/twowayssl/ssl/ca.crt
        passphrase: admin123
        rejectUnauthorized: true

Berikut adalah contoh untuk TLS:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    tls:
      client:
        pfx: /Users/myname/twowayssl/ssl/client.pfx
        passphrase: admin123
        rejectUnauthorized: true

Berikut adalah daftar semua opsi klien yang didukung:

Menyesuaikan proxy edgemicro-auth

Secara default, Edge Microgateway menggunakan proxy yang di-deploy di Apigee Edge untuk autentikasi OAuth2. Proxy ini di-deploy saat Anda pertama kali menjalankan edgemicro configure. Anda dapat mengubah konfigurasi default proxy ini untuk menambahkan dukungan klaim kustom ke Token Web JSON (JWT), mengonfigurasi akhir masa berlaku token, dan membuat token refresh. Untuk mengetahui detailnya, lihat halaman edgemicro-auth di GitHub.

Menggunakan layanan autentikasi kustom

Secara default, Edge Microgateway menggunakan proxy yang di-deploy di Apigee Edge untuk autentikasi OAuth2. Proxy ini di-deploy saat Anda pertama kali menjalankan edgemicro configure. Secara {i>default<i}, URL proxy ditentukan dalam file konfigurasi Edge Microgateway sebagai berikut:

authUri: https://myorg-myenv.apigee.net/edgemicro-auth

Jika Anda ingin menggunakan layanan khusus Anda sendiri untuk menangani autentikasi, ubah Nilai authUri di file konfigurasi untuk mengarah ke layanan Anda. Misalnya, Anda mungkin memiliki layanan yang menggunakan LDAP untuk memverifikasi identitas.

Mengelola {i>file<i} log

Edge Microgateway mencatat informasi tentang setiap permintaan dan respons ke dalam log. File log memberikan manfaat informasi untuk proses debug dan pemecahan masalah.

Tempat file log disimpan

Secara default, file log disimpan di /var/tmp.

Cara mengubah log default direktori file

Direktori tempat file log disimpan ditentukan dalam konfigurasi Edge Microgateway . Lihat juga Membuat konfigurasi perubahan.

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Ubah nilai dir untuk menentukan direktori file log yang berbeda.

Mengirim log ke konsol

Anda dapat mengkonfigurasi log sehingga informasi log dikirim ke {i>output<i} standar, bukan ke file log. Tetapkan tanda to_console ke benar (true) sebagai berikut:

edgemicro:
  logging:
    to_console: true

Dengan setelan ini, log akan dikirim ke standard out. Saat ini, Anda tidak dapat mengirim log ke keduanya {i>stdout<i} dan ke file log.

Cara menetapkan level logging

Anda dapat menetapkan level log berikut: info, warning, dan . Sebaiknya gunakan tingkat info. Alat ini mencatat semua permintaan dan respons API, dan ini adalah defaultnya.

Cara mengubah interval log

Anda dapat mengonfigurasi interval ini di file konfigurasi Edge Microgateway. Lihat juga Membuat perubahan konfigurasi.

Atribut yang dapat dikonfigurasi adalah:

• stats_log_interval: (default: 60) Interval, dalam detik, saat statistik yang ditulis ke file log API.
• rotate_interval: (default: 24) Interval, dalam jam, saat file log dirotasi. Contoh:

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Praktik pemeliharaan file log yang baik

Karena data file log terakumulasi dari waktu ke waktu, Apigee merekomendasikan agar Anda mengadopsi praktik:

• Karena file log bisa menjadi sangat besar, pastikan bahwa direktori file log telah cukup ruang. Lihat bagian berikut Tempat file log disimpan dan Cara mengubah file log default direktori.
• Hapus atau pindahkan file log ke direktori arsip terpisah minimal seminggu sekali.
• Jika kebijakan Anda adalah menghapus log, Anda dapat menggunakan perintah CLI edgemicro log -c untuk menghapus (membersihkan) log yang lebih lama.

Konvensi penamaan file log

Setiap instance Edge Microgateway menghasilkan tiga jenis file log:

• api - Mencatat semua permintaan dan respons yang mengalir melalui Edge Microgateway. Penghitung (statistik) dan error API juga dicatat ke file ini.
• err - Mencatat apa pun yang dikirim ke stderr.
• out - Mencatat apa pun yang dikirim ke stdout.

Berikut ini adalah konvensi penamaan:

edgemicro-<Host Name>-<Instance ID>-<Log Type>.log

Contoh:

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log
edgemicro-mymachine-local-MTQzNTg1NDMODAyMQ-err.log
edgemicro-mymachine-local-mtqzntgndmxodaymq-out.log

Tentang konten file log

Ditambahkan di: v2.3.3

Secara default, layanan logging menghilangkan JSON untuk proxy, produk, dan JSON yang didownload Token Web (JWT). Jika Anda ingin menampilkan objek ini ke file log, setel atribut DEBUG=* saat Anda memulai Edge Microgateway. Contoh:

DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456

Konten "api" file log

"api" file log berisi informasi detail tentang alur permintaan dan respons melalui Edge Microgateway. "api" file log diberi nama seperti ini:

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

Untuk setiap permintaan yang dibuat ke Edge Microgateway, empat peristiwa diambil di "api" catatan file:

• Permintaan masuk dari klien
• Permintaan keluar yang dibuat ke target
• Respons masuk dari target
• Respons keluar ke klien

Masing-masing entri terpisah ini direpresentasikan dalam notasi singkat untuk membantu membuat log file menjadi lebih ringkas. Berikut adalah empat entri contoh yang mewakili masing-masing dari keempat peristiwa tersebut. Di log , baris akan terlihat seperti ini (nomor baris hanya sebagai referensi dalam dokumen, mereka tidak muncul dalam file log).

(1) 1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
(2) 1436403888665 info treq m=GET, u=/, h=127.0.0.18080, i=0
(3) 1436403888672 info tres s=200, d=7, i=0
(4) 1436403888676 info res s=200, d=11, i=0

Mari kita bahas satu per satu:

1. Contoh permintaan masuk dari klien:

1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0

• 1436403888651 - Stempel tanggal Unix
• info - Tergantung pada konteks. Dapat berupa info, peringatkan, atau kesalahan, bergantung pada level log. Dapat berupa statistik untuk catatan statistik, peringatan untuk peringatan, atau {i>error<i} untuk {i>error<i}.
• req - Mengidentifikasi peristiwa. Dalam hal ini, permintaan dari dengan klien besar.
• m - Kata kerja HTTP yang digunakan dalam permintaan.
• u - Bagian URL yang mengikuti jalur basis.
• h - Host dan nomor port tempat Edge Microgateway berada mendengarkan.
• r - Host dan port jarak jauh tempat klien meminta berasal.
• i - ID permintaan. Keempat entri peristiwa akan membagikan ID ini. Masing-masing diberi ID permintaan unik. Mengkorelasi catatan log berdasarkan ID permintaan dapat memberikan insight berharga tentang latensi target.
• d - Durasi dalam milidetik sejak permintaan diterima oleh Edge Microgateway. Pada contoh di atas, respons target untuk permintaan 0 diterima setelah 7 milidetik (baris 3), dan respons dikirim ke klien setelah 4 tambahan milidetik (baris 4). Dengan kata lain, total latensi permintaan adalah 11 milidetik, dari yang 7 milidetik diambil oleh target dan 4 milidetik oleh Edge Microgateway itu sendiri.

2. Contoh permintaan keluar yang dikirim ke target:

1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0

• 1436403888651 - Stempel tanggal Unix
• info - Tergantung pada konteks. Dapat berupa info, peringatkan, atau kesalahan, bergantung pada level log. Dapat berupa statistik untuk catatan statistik, peringatan untuk peringatan, atau {i>error<i} untuk {i>error<i}.
• treq - Mengidentifikasi peristiwa. Dalam hal ini, permintaan target.
• m - Kata kerja HTTP yang digunakan dalam permintaan target.
• u - Bagian URL yang mengikuti jalur basis.
• h - Host dan nomor port target backend.
• i - ID entri log. Keempat entri peristiwa akan membagikan ini ke ID.

3. Contoh respons masuk dari target

1436403888672 info tres s=200, d=7, i=0

1436403888651 - Stempel tanggal Unix

• info - Tergantung pada konteks. Dapat berupa info, peringatkan, atau kesalahan, bergantung pada level log. Dapat berupa statistik untuk catatan statistik, peringatan untuk peringatan, atau {i>error<i} untuk {i>error<i}.
• tres - Mengidentifikasi peristiwa. Dalam hal ini, target respons.
• s - Status respons HTTP.
• d - Durasi dalam milidetik. Waktu yang dibutuhkan untuk panggilan API oleh targetnya.
• i - ID entri log. Keempat entri peristiwa akan membagikan ini ke ID.

4. Contoh respons keluar ke klien

1436403888676 info res s=200, d=11, i=0

1436403888651 - Stempel tanggal Unix

• info - Tergantung pada konteks. Dapat berupa info, peringatkan, atau kesalahan, bergantung pada level log. Dapat berupa statistik untuk catatan statistik, peringatan untuk peringatan, atau {i>error<i} untuk {i>error<i}.
• res - Mengidentifikasi peristiwa. Dalam hal ini, respons terhadap dengan klien besar.
• s - Status respons HTTP.
• d - Durasi dalam milidetik. Ini adalah total waktu yang dibutuhkan oleh panggilan API, termasuk waktu yang dibutuhkan oleh API target dan waktu yang dibutuhkan Edge Microgateway itu sendiri.
• i - ID entri log. Keempat entri peristiwa akan membagikan ini ke ID.

Jadwal file log

File log diputar pada interval yang ditentukan oleh rotate_interval atribut konfigurasi. Entri akan terus ditambahkan ke file log yang sama sampai interval rotasi kedaluwarsa. Namun, setiap kali Edge Microgateway {i>restart<i}, menerima UID baru dan membuat set file log baru dengan UID ini. Lihat juga Pemeliharaan file log yang baik praktik terbaik.

Pesan error

Beberapa entri log akan berisi pesan error. Untuk membantu mengidentifikasi di mana dan mengapa kesalahan terjadi, lihat kesalahan Edge Microgateway .

Referensi konfigurasi Edge Microgateway

Lokasi file konfigurasi

Atribut konfigurasi yang dijelaskan di bagian ini terletak di Edge Microgateway file konfigurasi Anda. Lihat juga Membuat konfigurasi perubahan.

atribut edge_config

Setelan ini digunakan untuk mengonfigurasi interaksi antara instance Edge Microgateway dan Apigee Edge.

• bootstrap: (default: tidak ada) URL yang mengarah ke Edge Layanan khusus Microgateway yang berjalan di Apigee Edge. Edge Microgateway menggunakan layanan ini untuk berkomunikasi dengan Apigee Edge. URL ini ditampilkan saat Anda menjalankan perintah untuk menghasilkan pasangan kunci publik/pribadi: edgemicro genkeys. Lihat tautan Menyiapkan dan mengonfigurasi Edge Microgateway untuk mengetahui detailnya.
• jwt_public_key: (default: none) URL yang mengarah ke Edge Microgateway yang di-deploy di Apigee Edge. {i>Proxy<i} ini berfungsi sebagai titik akhir otentikasi untuk menerbitkan token akses yang ditandatangani ke klien. URL ini ditampilkan ketika Anda menjalankan perintah untuk men-deploy proxy: konfigurasi edgemicro. Lihat tautan Menyiapkan dan mengonfigurasi Edge Microgateway untuk mengetahui detailnya.
• quotaUri: Menetapkan konfigurasi ini jika Anda ingin mengelola kuota melalui proxy edgemicro-auth yang yang di-deploy ke organisasi Anda. Jika properti ini tidak disetel, endpoint kuota ditetapkan secara default ke endpoint Edge Microgateway internal.

  edge_config:
    quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth
  

  Untuk menggunakan fitur ini, Anda harus terlebih dahulu men-deploy versi 3.0.5 atau yang lebih baru Proxy edgemicro-auth ke organisasi Anda. Untuk mengetahui detailnya, lihat Mengupgrade proxy edgemicro-auth.

atribut edgemicro

Setelan ini mengonfigurasi proses Edge Microgateway.

• port: (default: 8000) Nomor port tempat Edge Microgateway proses mendengarkan.
• max_connections: (default: -1) Menentukan jumlah maksimum koneksi masuk simultan yang dapat diterima Edge Microgateway. Jika nomor ini terlampaui, status berikut ditampilkan:
  
  res.statusCode = 429; // Too many requests
  
• max_connections_hard: (default: -1) Jumlah maksimum koneksi yang dapat diterima Edge Microgateway sebelum mematikan koneksi. Setelan ini dimaksudkan untuk menggagalkan serangan penolakan layanan. Biasanya, atur itu ke angka yang lebih besar dari max_connections.
• logging:
  • level: (default: error)
    • info - Mencatat semua permintaan dan respons yang mengalir melalui Instance Edge Microgateway.
    • peringatan - Hanya mencatat pesan peringatan.
    • error - Hanya mencatat pesan error ke dalam log.
  • dir: (default: /var/tmp) Direktori tempat file log berada disimpan.
  • stats_log_interval: (default: 60) Interval, dalam detik, saat statistik record ditulis ke file log api.
  • rotate_interval: (default: 24) Interval, dalam jam, saat file log dirotasi.

• plugin: Plugin menambahkan fungsi ke Edge Microgateway. Untuk detailnya tentang mengembangkan plugin, lihat Mengembangkan plugin kustom.

• dir: Jalur relatif dari direktori ./gateway ke direktori {i>./plugins<i}, atau jalur absolut.
• Urutan: Daftar modul plugin yang akan ditambahkan ke Edge Microgateway Anda di instance Compute Engine. Modul akan dijalankan sesuai urutan yang ditentukan di sini.

• debug: Menambahkan proses debug jarak jauh ke proses Edge Microgateway.
  • port: Nomor port yang akan diproses. Misalnya, setel debugger IDE Anda untuk diproses di port ini.
  • args: Argumen untuk proses debug. Contoh: args --nolazy
    
• config_change_poll_interval: (default: 600 detik) Edge Microgateway memuat konfigurasi baru secara berkala dan menjalankan muat ulang jika ada yang berubah. Jajak pendapat mengambil setiap perubahan yang dibuat di Edge (perubahan pada produk, proxy berbasis microgateway, dll.) serta perubahan yang dibuat pada file konfigurasi lokal.
  
• disable_config_poll_interval: (default: false) Tetapkan ke true untuk menonaktifkan polling perubahan otomatis.
• request_timeout: Menetapkan waktu tunggu untuk permintaan target. Waktu tunggu disetel dalam detik. Jika waktu tunggu habis, Edge Microgateway merespons dengan kode status 504. (Ditambahkan v2.4.x)

atribut header

Setelan ini mengonfigurasi cara header HTTP tertentu diperlakukan.

• x-forwarded-for: (default: true) Tetapkan ke false untuk mencegah diteruskan ke header x untuk diteruskan ke target. Perhatikan bahwa jika {i>header <i}x-forwarded-for ada dalam permintaan, nilainya akan ditetapkan ke nilai IP klien di Analisis Edge.
• x-forwarded-host: (default: true) Tetapkan ke false untuk mencegah header x-forwarded-host untuk diteruskan ke target.
• x-request-id: (default: true) Tetapkan ke false untuk mencegah x-request-id untuk diteruskan ke target.
• x-response-time: (default: true) Tetapkan ke false untuk mencegah header x-response-time yang akan diteruskan ke target.
• via: (default: true) Tetapkan ke false untuk mencegah melalui header yang diteruskan ke target.

atribut oauth

Setelan ini mengonfigurasi cara autentikasi klien diberlakukan oleh Edge Microgateway.

• allowNoAuthorization: (default: false) Jika ditetapkan ke true, panggilan API akan diizinkan untuk melewati Edge Microgateway tanpa {i>header <i}Otorisasi sama sekali. Tetapkan ini ke false untuk mewajibkan header Otorisasi (default).
• allowInvalidAuthorization: (default: false) Jika ditetapkan ke true, panggilan API akan diteruskan jika token yang diteruskan di header Otorisasi tidak valid atau sudah tidak berlaku. Setel ini ke false untuk memerlukan token yang valid (default).
• Authorization-header: (default: Authorization: Bearer) Header yang digunakan untuk kirim token akses ke Edge Microgateway. Anda mungkin ingin mengubah {i>default<i} jika target perlu menggunakan {i>header<i} Otorisasi untuk tujuan lain.
• api-key-header: (default: x-api-key) Nama header atau kueri yang digunakan untuk meneruskan kunci API ke Edge Microgateway. Lihat juga Menggunakan kunci API.
• keep-authorization-header: (default: false) Jika ditetapkan ke true, header Otorisasi dikirim dalam permintaan diteruskan ke target (ini dipertahankan).
• allowOAuthOnly -- Jika ditetapkan ke true, setiap API harus memiliki Otorisasi dengan Token Akses Pembawa. Memungkinkan Anda hanya mengizinkan model keamanan OAuth (sekaligus mempertahankan kompatibilitas mundur). (Ditambahkan 2.4.x)
• allowAPIKeyOnly -- Jika ditetapkan ke true, setiap API harus memiliki Header x-api-key (atau lokasi kustom) dengan Kunci API.Memungkinkan Anda mengizinkan model keamanan kunci API saja (sambil mempertahankan kompatibilitas mundur). (Ditambahkan 2.4.x)
• gracePeriod -- Parameter ini membantu mencegah error yang disebabkan oleh sedikit perbedaan antara jam sistem Anda dan waktu Tidak Sebelum (nbf) atau Diterbitkan Pada (iat) yang ditentukan dalam token otorisasi JWT. Setel parameter ini ke jumlah detik yang diizinkan untuk melihat perbedaan tersebut. (Ditambahkan 2.5.7)

Khusus plugin atribut

Lihat Menggunakan plugin untuk detail tentang atribut yang dapat dikonfigurasi untuk setiap plugin.

Memfilter proxy

Anda dapat memfilter proxy berbasis microgateway mana yang akan diproses oleh instance Edge Microgateway. Saat Edge Microgateway dimulai, semua proxy berbasis microgateway akan didownload organisasi yang terkait dengannya. Gunakan konfigurasi berikut untuk membatasi {i>proxy<i} mana akan diproses oleh microgateway. Misalnya, konfigurasi ini membatasi {i>proxy<i} {i>microgateway<i} akan memproses ke tiga: edgemicro_proxy-1, edgemicro_proxy-2, dan edgemicro_proxy-3:

proxies:
  - edgemicro_proxy-1
  - edgemicro_proxy-2
  - edgemicro_proxy-3

Mengonfigurasi frekuensi push analisis

Gunakan parameter konfigurasi ini untuk mengontrol frekuensi pengiriman Edge Microgateway data analisis ke Apigee:

• bufferSize (Opsional): Jumlah maksimum catatan analisis yang yang dapat disimpan sebelum memulai untuk menghapus {i>record<i} terlama. Default: 10.000
• batchSize (Opsional): Ukuran maksimum batch data analisis dikirimkan ke Apigee. Default: 500
• flushInterval (Opsional): Jumlah milidetik antara setiap flush sekumpulan data analisis yang dikirim ke Apigee. Default: 5.000

Contoh:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

Menyamarkan data analisis

Konfigurasi berikut mencegah informasi jalur permintaan muncul di Edge Analytics. Tambahkan kode berikut ke konfigurasi microgateway untuk menyamarkan URI permintaan dan/atau jalur permintaan. Perhatikan bahwa URI terdiri dari nama host dan bagian jalur yang diminta.

analytics:
  mask_request_uri: 'string_to_mask'
  mask_request_path: 'string_to_mask'

Memisahkan panggilan API di Analisis Edge

Anda dapat mengonfigurasi plugin analisis untuk memisahkan jalur API tertentu sehingga muncul sebagai {i>proxy<i} terpisah di dasbor Edge Analytics. Sebagai contoh, Anda dapat memisahkan API health check di dasbor untuk menghindari kebingungan dengan panggilan proxy API yang sebenarnya. Di kolom Dasbor Analytics, proxy terpisah mengikuti pola penamaan ini:

edgemicro_proxyname-health

Gambar berikut menunjukkan dua proxy terpisah di dasbor Analytics: edgemicro_hello-health dan edgemicro_mock-health:

Gunakan ini untuk memisahkan jalur relatif dan absolut di dasbor Analytics sebagai proxy terpisah:

• relativePath (Opsional): Menentukan jalur relatif yang akan dipisahkan dalam Dasbor Analytics. Misalnya, jika Anda menentukan /healthcheck, semua panggilan API yang berisi jalur tersebut /healthcheck akan muncul di dasbor sebagai edgemicro_proxyname-health. Perhatikan bahwa tanda ini mengabaikan jalur dasar proxy. Untuk memisahkan berdasarkan jalur lengkap, termasuk jalur dasar, gunakan tanda proxyPath.
• proxyPath (Opsional): Menentukan jalur proxy API lengkap, termasuk proxy basepath, untuk dipisahkan di dasbor analisis. Misalnya, jika Anda menentukan /mocktarget/healthcheck, dengan /mocktarget adalah jalur basis proxy, semua panggilan API dengan jalur /mocktarget/healthcheck akan muncul di dasbor sebagai edgemicro_proxyname-health.

Misalnya, dalam konfigurasi berikut, semua jalur API yang berisi /healthcheck akan dipisahkan oleh plugin analisis. Artinya, /foo/healthcheck dan /foo/bar/healthcheck akan dipisahkan sebagai proxy terpisah yang disebut edgemicro_proxyname-health di dasbor Analytics.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  relativePath: /healthcheck

Dalam konfigurasi berikut, API apa pun dengan jalur proxy /mocktarget/healthcheck akan akan dipisahkan sebagai proxy terpisah yang disebut edgemicro_proxyname-health di dasbor analitik.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  proxyPath: /mocktarget/healthcheck

Menyiapkan Edge Microgateway di belakang firewall perusahaan

V2.4.x yang didukung

Jika Edge Microgateway diinstal di belakang firewall, gateway mungkin tidak dapat berkomunikasi dengan Apigee Edge. Dalam hal ini, ada dua opsi yang dapat Anda pertimbangkan:

Opsi 1:

Opsi pertama adalah menetapkan opsi edgemicro: proxy_tunnel ke true di file konfigurasi microgateway:

edge_config:

    proxy: http://10.224.16.85:3128
    proxy_tunnel: true

Jika proxy_tunnel bernilai true, Edge Microgateway menggunakan metode CONNECT HTTP untuk tunnel permintaan HTTP melalui koneksi TCP tunggal. (Hal yang sama berlaku jika variabel lingkungan untuk mengonfigurasi proxy mengaktifkan TLS).

Opsi 2:

Opsi kedua adalah menentukan proxy dan mengatur proxy_tunnel ke false di file konfigurasi microgateway. Contoh:

edge_config:
     proxy: http://10.224.16.85:3128
     proxy_tunnel: false

Dalam kasus ini, Anda dapat menetapkan variabel berikut untuk mengontrol host untuk setiap yang ingin Anda gunakan, atau host mana yang tidak boleh menangani proxy Edge Microgateway: HTTP_PROXY, HTTPS_PROXY, dan NO_PROXY.

Anda dapat menetapkan NO_PROXY sebagai daftar domain yang dipisahkan koma yang Microgateway tidak boleh melakukan proxy. Contoh:

export NO_PROXY='localhost,localhost:8080'

Menetapkan HTTP_PROXY dan HTTPS_PROXY ke proxy HTTP endpoint Edge Microgateway dapat mengirim pesan ke sana. Contoh:

export HTTP_PROXY='http://localhost:3786'

export HTTPS_PROXY='https://localhost:3786'

Untuk informasi selengkapnya tentang variabel ini, lihat https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables

Lihat juga

Cara menyiapkan Edge Microgateway di balik firewall perusahaan di Komunitas Apigee.

Menggunakan karakter pengganti di berbasis Microgateway {i>proxy<i}

Anda dapat menggunakan satu atau beberapa "*" {i>wildcard <i}di jalur dasar suatu Proxy edgemicro_* (berbasis Microgateway). Misalnya, jalur dasar dari /team/*/members memungkinkan klien untuk menelepon https://[host]/team/blue/members dan https://[host]/team/green/members tanpa perlu membuat proxy API baru untuk mendukung tim baru. Perlu diketahui bahwa /**/ tidak didukung.

Penting: Apigee TIDAK mendukung penggunaan karakter pengganti "*" sebagai elemen pertama dari jalur dasar. Misalnya, ini TIDAK didukung: penelusuran /*/.

Memutar kunci JWT

Pada saat tertentu setelah pertama kali membuat JWT, Anda mungkin perlu mengubah pasangan kunci publik/pribadi yang disimpan di KVM yang dienkripsi Edge. Proses pembuatan kunci baru ini pasangannya disebut rotasi kunci.

Cara Edge Microgateway menggunakan JWT

JSON Web Token (JWT) adalah standar token yang dijelaskan dalam RFC7519. JWT menyediakan cara untuk menandatangani serangkaian klaim, yang dapat diverifikasi dengan andal oleh penerima JWT.

Edge Microgateway menggunakan JWT sebagai token pemilik untuk keamanan OAuth. Saat Anda membuat token OAuth untuk Edge Microgateway, Anda akan menerima kembali JWT. Anda kemudian dapat menggunakan JWT di Header otorisasi panggilan API. Contoh:

curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"

Membuat JWT baru

Anda dapat membuat JWT untuk Edge Microgateway menggunakan perintah edgemicro token atau API. Contoh:

edgemicro token get -o docs -e test -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

Perintah ini meminta Apigee Edge untuk menghasilkan JWT yang kemudian dapat digunakan untuk memverifikasi API panggilan telepon. Parameter -i dan -s adalah ID konsumen dan nilai rahasia dari aplikasi developer di organisasi Apigee Edge Anda.

Atau, Anda juga dapat membuat JWT menggunakan API pengelolaan:

curl -i -X POST "http://org-env.apigee.net/edgemicro-auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your consumer key",
    "client_secret": "your consumer secret",
    "grant_type": "client_credentials"
  }'

Dengan keterangan:

• org adalah nama organisasi Edge Anda (Anda harus menjadi administrator org).
• env adalah lingkungan di organisasi Anda (seperti "test" atau "prod").
• client_id adalah ID Konsumen di Aplikasi Developer yang Anda buat sebelumnya.
• client_secret adalah Rahasia Konsumen di Aplikasi Developer yang Anda buat seperti yang telah dibahas sebelumnya.

Apa itu rotasi kunci?

Pada saat tertentu setelah pertama kali membuat JWT, Anda mungkin perlu mengubah pasangan kunci publik/pribadi yang disimpan di KVM yang dienkripsi Edge. Proses pembuatan kunci baru ini pasangannya disebut rotasi kunci. Saat Anda merotasi kunci, pasangan kunci privat/publik baru dihasilkan dan disimpan di {i>microgateway<i} di organisasi/lingkungan Apigee Edge Anda. Selain itu, kunci publik lama dipertahankan beserta nilai ID kunci aslinya.

Untuk menghasilkan JWT, Edge menggunakan informasi yang disimpan dalam KVM terenkripsi. J KVM bernama microgateway telah dibuat dan diisi dengan kunci saat Anda pertama kali menyiapkannya (dikonfigurasi) Edge Microgateway. Kunci dalam KVM digunakan untuk menandatangani dan mengenkripsi JWT.

Kunci KVM meliputi:

• private_key - Kunci pribadi RSA terbaru (yang terakhir dibuat) yang digunakan untuk menandatangani JWT.

• public_key - Sertifikat terbaru (yang paling baru dibuat) yang digunakan untuk memverifikasi JWT ditandatangani dengan {i>private_key<i}.

• private_key_kid - ID kunci pribadi terbaru (yang paling baru dibuat). ID kunci ini dikaitkan dengan nilai private_key dan digunakan untuk mendukung rotasi kunci.

• public_key1_kid - ID kunci publik terbaru (yang paling baru dibuat). Kunci ini yang dikaitkan dengan nilai public_key1 dan digunakan untuk mendukung rotasi kunci. Nilai ini sama dengan kunci pribadi anak.

• public_key1 - Kunci publik terbaru (yang paling baru dibuat).

Saat Anda melakukan rotasi kunci, nilai kunci yang ada akan diganti di peta dan kunci ditambahkan untuk mempertahankan kunci publik yang lama. Contoh:

• public_key2_kid - ID kunci publik lama. Kunci ini terkait dengan nilai public_key2 dan digunakan untuk mendukung rotasi kunci.

• public_key2 - Kunci publik lama.

JWT yang ditampilkan untuk verifikasi akan diverifikasi menggunakan kunci publik baru. Jika verifikasi gagal, maka kunci publik lama akan digunakan, sampai masa berlakunya habis (setelah 30 menit). Di beberapa dengan cara ini, Anda dapat "memutar" kunci tanpa langsung mengganggu traffic API.

Cara melakukan rotasi kunci

Bagian ini menjelaskan cara melakukan rotasi kunci.

Jika Anda mengonfigurasi instance Edge Microgateway sebelum versi 2.5.2

Jika Anda mengonfigurasi instance Edge Microgateway sebelum versi 2.5.2, maka Anda harus menjalankan dua perintah berikut untuk mengupgrade KVM dan kebijakan autentikasi:

upgradekvm -o org -e env -u username

Untuk informasi selengkapnya tentang perintah ini, lihat Meningkatkan di KVM.

Perintah berikutnya mengupgrade proxy edgemicro-oauth yang telah di-deploy ke organisasi Apigee Anda saat mengonfigurasi Edge Microgateway. {i>Proxy<i} ini menyediakan layanan yang diperlukan untuk menghasilkan token.

upgradeauth -o org -e env -u username

Untuk informasi selengkapnya tentang perintah ini, lihat Meningkatkan proxy edgemicro-auth Anda.

Memutar tombol

Tambahkan baris berikut ke file ~/.edgemicro/org-env-config.yaml Anda, tempat Anda harus menentukan organisasi dan lingkungan yang sama dengan yang Anda konfigurasikan di microgateway:

jwk_public_keys: 'https://org-env.apigee.net/edgemicro-auth/jwkPublicKeys'

Jalankan perintah rotasi kunci untuk merotasi kunci. (Untuk informasi selengkapnya tentang perintah ini, lihat Tombol berputar.)

edgemicro rotatekey -o org -e env -u username -k kid_value

Contoh:

edgemicro rotatekey -o jdoe -e test -u jdoe@google.com -k 2
current nodejs version is v12.5.0
current edgemicro version is 3.0.2
password:
Checking if private key exists in the KVM...
Checking for certificate...
Found Certificate
Generating New key/cert pair...
Extract new public key
Key Rotation successfully completed!

Parameter -k menentukan Key ID (anak). ID ini digunakan untuk mencocokkan kunci tertentu. Edge Microgateway menggunakan nilai ini untuk memilih di antara serangkaian kunci selama rotasi kunci. Untuk selengkapnya informasi tambahan, lihat Pasal 4.5 dalam Spesifikasi Kunci Web JSON.

Setelah rotasi kunci, Edge menampilkan beberapa kunci ke Edge Microgateway. Catatan di contoh berikut, setiap kunci memiliki "anak" unik (ID Kunci). Microgateway lalu menggunakan kunci untuk memvalidasi token otorisasi. Jika validasi token gagal, microgateway akan mencari memeriksa apakah ada kunci yang lebih lama di kumpulan kunci dan mencoba kunci itu. Format kunci yang ditampilkan adalah JSON Web Key (JWK). Anda dapat membaca tentang format ini di RFC 7517.

{
  "keys": [
    {
      "kty": "RSA",
      "n": "nSl7R_0wKLiWi6cO3n8aOJwYGBtinq723Jgg8i7KKWTSTYoszOjgGsJf_MX4JEW1YCScwpE5o4o8ccQN09iHVTlIhk8CNiMZNPipClmRVjaL_8IWvMQp1iN66qy4ldWXzXnHfivUZZogCkBNqCz7VSC5rw2Jf57pdViULVvVDGwTgf46sYveW_6h8CAGaD0KLd3vZffxIkoJubh0yMy0mQP3aDOeIGf_akeZeZ6GzF7ltbKGd954iNTiKmdm8IKhz6Y3gLpC9iwQ-kex_j0CnO_daHl1coYxUSCIdv4ziWIeM3dmjQ5_2dEvUDIGG6_Az9hTpNgPE5J1tvrOHAmunQ",
      "e": "AQAB",
      "kid": "2"
    },
    {
      "kty": "RSA",
      "n": "8BKwzx34BMUcHwTuQtmp8LFRCMxbkKg_zsWD6eOMIUTAsORexTGJsTy7z-4aH0wJ3fT-3luAAUPLBQwGcuHo0P1JnbtPrpuYjaJKSZOeIMOnlryJCspmv-1xG4qAqQ9XaZ9C97oecuj7MMoNwuaZno5MvsY-oi5B_gqED3vIHUjaWCErd4reONyFSWn047dvpE6mwRhZbcOTkAHT8ZyKkHISzopkFg8CD-Mij12unxA3ldcTV7yaviXgxd3eFSD1_Z4L7ZRsDUukCJkJ-8qY2-GWjewzoxl-mAW9D1tLK6qAdc89yFem3JHRW6L1le3YK37-bs6b2a_AqJKsKm5bWw",
      "e": "AQAB",
      "kid": "1"
    }
  ]
}

Memfilter proxy yang didownload

Secara default, Edge Microgateway mendownload semua proxy di organisasi Edge Anda yang diawali dengan awalan nama "edgemicro_". Anda dapat mengubah setelan default ini untuk mendownload proxy yang namanya memiliki pola yang sama.

1. Buka file konfigurasi Edge Micro Anda: ~/.edgemicro/org-env-config.yaml
2. Tambahkan elemen proxyPattern di bagian edge_config. Misalnya, pola berikut akan untuk mendownload proxy seperti edgemicro_foo, edgemicro_fast, dan edgemicro_first.

   edge_config:
   …
   proxyPattern: edgemicro_f*

Menentukan produk tanpa proxy API

Di Apigee Edge, Anda dapat membuat produk API yang tidak berisi proxy API apa pun. Konfigurasi produk ini memungkinkan kunci API yang terkait dengan produk tersebut untuk berfungsi dengan yang di-deploy di organisasi Anda. Mulai versi 2.5.4, Edge Microgateway mendukung produk ini konfigurasi Anda.

Proses debug dan pemecahan masalah

Menghubungkan ke debugger

Anda dapat menjalankan Edge Microgateway dengan debugger, seperti node-inspector. Hal ini berguna untuk memecahkan masalah dan melakukan {i>debugging<i} plugin khusus.

1. Mulai ulang Edge Microgateway dalam mode debug. Untuk melakukannya, tambahkan DEBUG=* ke awal perintah start. Contoh:

   DEBUG=* edgemicro start -o  myorg -e test -k
         db4e9e8a95aa7fabfdeacbb1169d0a8cbe42bec19c6b98129e02 -s
         6e56af7c1b26dfe93dae78a735c8afc9796b077d105ae5618ce7ed

2. Mulai debugger dan setel agar memproses nomor port untuk proses debug.
3. Anda sekarang dapat melangkah melalui kode Edge Microgateway, mengatur titik henti sementara, mengamati ekspresi, dan seterusnya.

Anda dapat menentukan flag Node.js standar yang terkait dengan mode debug. Misalnya, --nolazy membantu Anda dalam men-debug kode asinkron.

Memeriksa file log

Jika Anda mengalami masalah, pastikan untuk memeriksa file log untuk mengetahui detail eksekusi dan {i>error<i} tidak akurat atau tidak sesuai. Untuk mengetahui detailnya, lihat Mengelola file log.

Menggunakan keamanan kunci API

Kunci API menyediakan mekanisme sederhana untuk mengautentikasi klien yang membuat permintaan ke Edge Microgateway. Anda dapat memperoleh kunci API dengan menyalin nilai Kunci Konsumen (juga disebut Client-ID) dari produk Apigee Edge yang menyertakan proxy autentikasi Edge Microgateway.

Menyimpan ke cache kunci

Kunci API dipertukarkan dengan token pemilik, yang di-cache. Anda dapat menonaktifkan penyimpanan dalam cache dengan menyetel header Cache-Control: no-cache pada permintaan yang masuk ke Edge Microgateway.

Menggunakan kunci API

Anda dapat meneruskan kunci API dalam permintaan API sebagai parameter kueri atau di header. Secara {i>default<i}, header dan nama parameter kueri keduanya x-api-key.

Contoh parameter kueri:

curl http://localhost:8000/foobar?x-api-key=JG616Gjz7xs4t0dvpvVsGdI49G34xGsz

Contoh header:

curl http://localhost:8000/foobar -H "x-api-key:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

Mengonfigurasi nama kunci API

Secara default, x-api-key adalah nama yang digunakan untuk header kunci API dan parameter kueri. Anda dapat mengubah setelan default ini di file konfigurasi, seperti yang dijelaskan dalam Membuat perubahan konfigurasi. Misalnya, untuk mengubah menjadi apiKey:

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  api-key-header: apiKey

Dalam contoh ini, parameter kueri dan nama header diubah menjadi apiKey. Tujuan nama x-api-key tidak akan berfungsi lagi. Lihat juga Membuat perubahan konfigurasi.

Contoh:

curl http://localhost:8000/foobar -H "apiKey:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

Untuk informasi selengkapnya tentang penggunaan kunci API bersama permintaan proxy, lihat Microgateway Secure Edge.

Mengaktifkan kode respons upstream

Secara default, plugin oauth hanya menampilkan kode status error 4xx jika responsnya bukanlah status 200. Anda dapat mengubah perilaku ini agar selalu mengembalikan kode 4xx atau 5xx yang tepat, tergantung pada kesalahannya. (Dirilis dalam versi 3.0.7)

Untuk mengaktifkan fitur ini, tambahkan oauth.useUpstreamResponse: true ke konfigurasi Edge Microgateway Anda. Contoh:

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  gracePeriod: 10
  useUpstreamResponse: true

Menggunakan keamanan token OAuth2

Bagian ini menjelaskan cara mendapatkan token akses OAuth2 dan token refresh. Token akses digunakan untuk membuat panggilan API yang aman melalui microgateway. Token refresh digunakan untuk memperoleh token akses baru.

Cara mendapatkan token akses

Bagian ini menjelaskan cara menggunakan proxy edgemicro-auth untuk mendapatkan token akses.

Anda juga bisa mendapatkan token akses menggunakan perintah CLI edgemicro token. Untuk mengetahui detail tentang CLI, lihat Mengelola token.

API 1: Mengirim kredensial sebagai parameter isi

Ganti nama organisasi dan lingkungan Anda di URL, dan menggantikan nilai ID Konsumen dan Rahasia Konsumen yang diperoleh dari aplikasi developer di Apigee Edge untuk parameter isi client_id dan client_secret:

curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \
-d '{"grant_type": "client_credentials", "client_id": "your_client_id", \
"client_secret": "your_client_secret"}' -H "Content-Type: application/json"

API 2: Mengirim kredensial di header Basic Auth

Kirim kredensial klien sebagai header Autentikasi Dasar dan grant_type sebagai parameter formulir. Formulir perintah ini juga dibahas di RFC 6749: Framework Otorisasi OAuth 2.0.

http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \
-d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"

Contoh output

{
"token": "eyJraWQiOiIxIiwidHlwIjoi",
"access_token": "eyJraWQiOiIxIiwid",
"token_type": "bearer",
"expires_in": "108000"
}

Cara mendapatkan token refresh

Untuk mendapatkan token refresh, lakukan panggilan API ke endpoint /token dari Proxy edgemicro-auth. Anda HARUS melakukan panggilan API ini dengan password jenis pemberian izin. Langkah-langkah berikut akan memandu Anda melalui proses tersebut.

1. Dapatkan token akses dan refresh dengan /token API. Perlu diketahui bahwa jenis pemberian izin adalah password:

   curl -X POST \
     https://your_organization-your_environment.apigee.net/edgemicro-auth/token \
     -H 'Content-Type: application/json' \
     -d '{
      "client_id":"mpK6l1Bx9oE5zLdifoDbF931TDnDtLq",
      "client_secret":"bUdDcFgv3nXffnU",
      "grant_type":"password",
      "username":"mpK6lBx9RoE5LiffoDbpF931TDnDtLq",
      "password":"bUdD2FvnMsXffnU"
   }'

   API menampilkan token akses dan token refresh. Responsnya terlihat mirip dengan ini:

   {
       "token": "your-access-token",
       "access_token": "your-access-token",
       "token_type": "bearer",
       "expires_in": "108000",
       "refresh_token": "your-refresh-token",
       "refresh_token_expires_in": "431999",
       "refresh_token_issued_at": "1562087304302",
       "refresh_token_status": "approved"
   }

2. Sekarang Anda dapat menggunakan token refresh untuk mendapatkan token akses baru dengan memanggil endpoint /refresh dari API yang sama. Contoh:

   curl -X POST \
     https://willwitman-test.apigee.net/edgemicro-auth/refresh \
     -H 'Content-Type: application/json' \
     -d '{
      "client_id":"mpK6l1Bx9RoE5zLifoDbpF931TDnDtLq",
      "client_secret":"bUdDc2Fv3nMXffnU",
      "grant_type":"refresh_token",
      "refresh_token":"your-refresh-token"
   }'

   API menampilkan token akses baru. Responsnya terlihat mirip dengan ini:

   {
       "token": "your-new-access-token"
       }

Pemantauan selamanya

Forever adalah alat Node.js yang memulai ulang aplikasi Node.js secara otomatis jika prosesnya terhenti atau mengalami error. Tepi Microgateway memiliki file forever.json yang dapat Anda konfigurasi untuk mengontrol berapa banyak dan dengan interval berapa Edge Microgateway harus dimulai ulang. File ini mengonfigurasi Layanan Forever yang disebut forever-monitor, yang mengelola Selamanya secara terprogram.

Anda dapat menemukan file forever.json di root install Edge Microgateway saat ini. Lihat Lokasi Edge Microgateway terinstal. Untuk detail tentang opsi konfigurasi, lihat dokumentasi forever-monitor.

Perintah edgemicro forever menyertakan flag yang memungkinkan Anda menentukan lokasi file forever.json (flag -f), dan memulai/menghentikan pemantauan Forever proses (flag -a). Contoh:

edgemicro forever -f ~/mydir/forever.json -a start

Untuk informasi selengkapnya, lihat Pemantauan selamanya dalam referensi CLI.

Menentukan endpoint file konfigurasi

Jika menjalankan beberapa instance Edge Microgateway, Anda mungkin ingin mengelola konfigurasinya dari satu lokasi. Anda dapat melakukannya dengan menentukan endpoint HTTP yang dapat digunakan Edge Micro mengunduh file konfigurasinya. Anda dapat menentukan endpoint ini saat memulai Edge Micro menggunakan flag -u.

Contoh:

edgemicro start -o jdoe -e test -u http://mylocalserver/mgconfig -k public_key -s secret_key

tempat endpoint {i>mgconfig<i} menampilkan isi file konfigurasi Anda. Ini adalah file yang, secara default, terletak di ~/.edgemicro dan memiliki konvensi penamaan: org-env-config.yaml.

Menonaktifkan buffering data koneksi TCP

Anda dapat menggunakan atribut konfigurasi nodelay guna menonaktifkan buffering data untuk Koneksi TCP yang digunakan oleh Edge Microgateway.

Secara default koneksi TCP menggunakan Nagle algoritme untuk mem-buffer data sebelum mengirimnya. Menyetel nodelay ke true, menonaktifkan perilaku ini (data akan langsung mematikan data setiap kali socket.write() dipanggil). Lihat juga Node.js untuk detail selengkapnya.

Untuk mengaktifkan nodelay, edit file konfigurasi Edge Micro sebagai berikut:

edgemicro:
  nodelay: true
  port: 8000
  max_connections: 1000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Menjalankan Edge Microgateway dalam mode mandiri

Anda dapat menjalankan Edge Microgateway yang terputus sepenuhnya dari Dependensi Apigee Edge. Skenario ini, disebut mode mandiri, memungkinkan Anda menjalankan dan menguji Edge Microgateway tanpa koneksi Internet.

Dalam mode mandiri, fitur berikut tidak akan berfungsi karena memerlukan koneksi ke Apigee Edge:

• OAuth dan kunci API
• Kuota
• Analytics

Di sisi lain, plugin khusus dan {i>sprint arrest<i} berfungsi secara normal, karena tidak memerlukan koneksi ke Apigee Edge. Selain itu, plugin baru bernama extauth memungkinkan Anda mengizinkan panggilan API ke microgateway dengan JWT saat dalam mode mandiri.

Mengonfigurasi dan memulai gateway

Untuk menjalankan Edge Microgateway dalam mode mandiri:

1. Pastikan Anda telah menginstal Edge Microgateway versi 3.0.1 atau yang lebih baru. Jika tidak, Anda harus jalankan perintah berikut untuk mengupgrade ke versi terbaru:

   npm install -g edgemicro

   Jika Anda membutuhkan bantuan, lihat Menginstal Edge Microgateway.

2. Buat file konfigurasi dengan nama berikut: $HOME/.edgemicro/org_name-env_name-config.yaml

   Contoh:

   vi $HOME/.edgemicro/foo-bar-config.yaml

3. Tempelkan kode berikut ke dalam file:

   edgemicro:
     port: 8000
     max_connections: 1000
     config_change_poll_interval: 600
     logging:
       level: error
       dir: /var/tmp
       stats_log_interval: 60
       rotate_interval: 24
     plugins:
       sequence:
         - extauth
         - spikearrest
   headers:
     x-forwarded-for: true
     x-forwarded-host: true
     x-request-id: true
     x-response-time: true
     via: true
   extauth:
     publickey_url: https://www.googleapis.com/oauth2/v1/certs
   spikearrest:
     timeUnit: second
     allow: 10
     buffersize: 0

4. Ekspor variabel lingkungan berikut dengan nilai "1":

   export EDGEMICRO_LOCAL=1

5. Jalankan perintah start berikut, di mana Anda memberikan nilai untuk membuat instance {i>proxy<i} lokal:

   edgemicro start -o org_name -e environment_name -a local_proxy_name \
     -v local_proxy_version -t target_url -b base_path

   Dengan keterangan:

   • your_org adalah "org" yang Anda gunakan di nama file konfigurasi.
   • your_environment adalah "env" nama yang Anda gunakan di file konfigurasi nama.
   • local_proxy_name adalah nama proxy lokal yang akan dibuat. Anda dapat menggunakan nama apa pun yang Anda inginkan.
   • local_proxy_version adalah nomor versi proxy.
   • target_url adalah URL untuk target proxy. (Target adalah yang dipanggil oleh proxy.)
   • base_path adalah jalur dasar proxy. Nilai ini harus diawali dengan penerusan garis miring. Untuk jalur dasar root, tentukan hanya garis miring ke depan; misalnya, "/".

   Contoh:

   edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /

6. Uji konfigurasi.

   curl http://localhost:8000/echo  { "error" : "missing_authorization" }

   Karena plugin extauth ada dalam file foo-bar-config.yaml, Anda minta "izin_tidak ada" {i>error<i}. Plugin ini memvalidasi JWT yang harus ada di Otorisasi header panggilan API. Di bagian berikutnya, Anda akan mendapatkan JWT yang akan mengizinkan panggilan API diselesaikan tanpa kesalahan.

Contoh: Memperoleh token otorisasi

Contoh berikut menunjukkan cara mendapatkan JWT dari endpoint JWT Edge Microgateway di Apigee Edge (edgemicro-auth/jwkPublicKeys). Endpoint ini di-deploy saat Anda melakukan penyiapan dan konfigurasi standar Edge Microgateway. Untuk mendapatkan JWT dari endpoint Apigee, pertama-tama Anda harus melakukan penyiapan Edge Microgateway standar, lalu terhubung ke Internet. Endpoint Apigee digunakan di sini untuk contoh tujuan saja dan tidak diperlukan. Anda dapat menggunakan endpoint token JWT lain jika diinginkan. Jika ya, Anda harus mendapatkan JWT menggunakan API yang disediakan untuk endpoint tersebut.

Langkah-langkah berikut menjelaskan cara mendapatkan token menggunakan endpoint edgemicro-auth/jwkPublicKeys:

1. Anda harus menjalankan standar penyiapan dan konfigurasi Edge Microgateway untuk men-deploy proxy edgemicro-auth dengan organisasi/lingkungan Anda di Apigee Edge. Jika sudah melakukan langkah ini sebelumnya, Anda tidak perlu mengulanginya.
2. Jika men-deploy Edge Microgateway ke Apigee Cloud, Anda harus terhubung ke Internet agar dapat memperoleh JWT dari endpoint ini.
3. Hentikan Microgateway Edge:

   edgemicro stop

4. Di file konfigurasi yang Anda buat sebelumnya ($HOME/.edgemicro/org-env-config.yaml), arahkan extauth:publickey_url ke endpoint edgemicro-auth/jwkPublicKeys di organisasi/lingkungan Apigee Edge Anda. Contoh:

   extauth:
     publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'

5. Mulai ulang Edge Microgateway seperti yang Anda lakukan sebelumnya, menggunakan nama org/env yang Anda gunakan dalam nama file konfigurasi. Contoh:

   edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /

6. Dapatkan token JWT dari endpoint otorisasi. Karena Anda menggunakan edgemicro-auth/jwkPublicKeys Anda dapat menggunakan perintah CLI ini:

Anda dapat membuat JWT untuk Edge Microgateway menggunakan perintah edgemicro token atau API. Contoh:

edgemicro token get -o your_org -e your_env \
  -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

Dengan keterangan:

• your_org adalah nama organisasi Apigee Anda yang sebelumnya Anda yakni Edge Microgateway yang dikonfigurasi.
• your_env adalah lingkungan dalam organisasi.
• Opsi i menentukan Kunci Konsumen dari aplikasi developer yang memiliki produk yang menyertakan proxy edgemicro-auth.
• Opsi s menentukan Rahasia Konsumen dari aplikasi developer yang memiliki produk yang menyertakan proxy edgemicro-auth.

Perintah ini meminta Apigee Edge untuk menghasilkan JWT yang kemudian dapat digunakan untuk memverifikasi API panggilan telepon.

Menguji konfigurasi mandiri

Untuk menguji konfigurasi, panggil API dengan token yang ditambahkan di header Authorization seperti berikut:

curl http://localhost:8000/echo -H "Authorization: Bearer your_token

Contoh:

curl http://localhost:8000/echo -H "Authorization: Bearer eyJraWQiOiIxIiwidHlwIjo...iryF3kwcDWNv7OQ"

Contoh output:

{
   "headers":{
      "user-agent":"curl/7.54.0",
      "accept":"*/*",
      "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
      "client_received_start_timestamp":"1535134472699",
      "x-authorization-claims":"eyJhdDbiO...M1OTE5MTA1NDkifQ==",
      "target_sent_start_timestamp":"1535134472702",
      "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
      "x-forwarded-proto":"http",
      "x-forwarded-host":"localhost:8000",
      "host":"mocktarget.apigee.net",
      "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
      "via":"1.1 localhost, 1.1 google",
      "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
      "connection":"Keep-Alive"
   },
   "method":"GET",
   "url":"/",
   "body":""
}

Menggunakan mode proxy lokal

Dalam mode proxy lokal, Edge Microgateway tidak memerlukan Proxy microgateway-aware yang akan di-deploy di Apigee Edge. Sebagai gantinya, Anda mengonfigurasi "proxy lokal" dengan menyediakan nama {i>proxy<i}, {i>basepath<i}, dan URL target lokal ketika Anda memulai {i>microgateway<i}. Panggilan API ke microgateway lalu dikirim ke target URL proxy lokal. Selain itu, mode {i>proxy<i} lokal bekerja sama persis seperti menjalankan Edge Microgateway dalam mode normal. Autentikasi berfungsi sama, begitu juga dengan lonjakan pembatasan dan penegakan kuota, plugin kustom, dan sebagainya.

Kasus penggunaan dan contoh

Mode proxy lokal berguna jika Anda hanya perlu mengaitkan satu proxy dengan Edge Microgateway di instance Compute Engine. Misalnya, Anda dapat menginjeksikan Edge Microgateway ke Kubernetes sebagai proxy file bantuan, dengan {i>microgateway<i} dan sebuah layanan masing-masing berjalan dalam satu pod, dan di mana {i>microgateway<i} mengelola lalu lintas dan dari layanan pendampingnya. Gambar berikut mengilustrasikan arsitektur ini di mana Edge Microgateway berfungsi sebagai proxy file bantuan di cluster Kubernetes. Tiap instance microgateway berkomunikasi hanya ke satu endpoint di layanan pendampingnya:

Keuntungan dari gaya arsitektur ini adalah bahwa Edge Microgateway menyediakan API untuk setiap layanan yang di-deploy ke lingkungan container, seperti cluster Kubernetes.

Mengonfigurasi mode proxy lokal

Untuk mengonfigurasi Edge Microgateway agar berjalan dalam mode proxy lokal, ikuti langkah-langkah berikut:

1. Pastikan Anda telah menginstal Edge Microgateway versi 3.0.1 atau yang lebih baru. Jika tidak, Anda harus jalankan perintah berikut untuk mengupgrade ke versi terbaru:

   npm install -g edgemicro

   Jika Anda membutuhkan bantuan, lihat Menginstal Edge Microgateway.

2. Jalankan edgemicro init untuk menyiapkan lingkungan konfigurasi lokal Anda, secara tepat seperti yang Anda lakukan pada pengaturan Edge Microgateway pada umumnya. Lihat juga Mengonfigurasi Edge Microgateway.
3. Jalankan edgemicro configure, seperti yang Anda lakukan dalam penyiapan Edge Microgateway pada umumnya prosedur standar. Contoh:

   edgemicro configure -o your_org -e your_env -u your_apigee_username

   Perintah ini men-deploy kebijakan edgemicro-auth ke Edge dan menampilkan kunci rahasia yang Anda perlukan untuk memulai {i>microgateway<i}. Jika Anda membutuhkan bantuan, lihat Mengonfigurasi Edge Microgateway.

4. Di Apigee Edge, buat produk API dan dengan konfigurasi wajib berikut persyaratan (Anda dapat mengelola semua konfigurasi lainnya sesuai keinginan):
   • Anda harus menambahkan proxy edgemicro-auth ke produk. Proxy ini di-deploy secara otomatis saat Anda menjalankan edgemicro configure.
   • Anda harus memberikan jalur resource. Apigee merekomendasikan penambahan jalur ini ke produk: /**. Untuk mempelajari lebih lanjut, lihat Mengonfigurasi perilaku jalur resource. Lihat juga Create API produk Google dalam dokumentasi Edge.

5. Di Apigee Edge, buat developer, atau Anda dapat menggunakan developer yang sudah ada jika Anda keinginan. Untuk mendapatkan bantuan, lihat Menambahkan developer menggunakan UI pengelolaan Edge.

6. Di Apigee Edge, buat aplikasi developer. Anda harus menambahkan produk API yang yang baru saja dibuat ke aplikasi. Untuk mendapatkan bantuan, lihat Mendaftarkan aplikasi di Edge UI pengelolaan layanan.
7. Di komputer tempat Edge Microgateway diinstal, ekspor hal berikut {i>variabel lingkungan<i} dengan nilai "1".

   export EDGEMICRO_LOCAL_PROXY=1

8. Jalankan perintah start berikut:

   edgemicro start -o your_org -e your_environment -k your_key -s your_secret \
       -a local_proxy_name -v local_proxy_version -t target_url -b base_path

   Dengan keterangan:

   • your_org adalah organisasi Apigee Anda.
   • your_environment adalah lingkungan di organisasi Anda.
   • your_key adalah kunci yang ditampilkan saat Anda menjalankan edgemicro configure.
   • your_secret adalah rahasia yang ditampilkan saat Anda menjalankan edgemicro configure.
   • local_proxy_name adalah nama proxy lokal yang akan dibuat.
   • local_proxy_version adalah nomor versi proxy.
   • target_url adalah URL untuk target proxy (layanan yang akan panggilan).
   • base_path adalah jalur dasar proxy. Nilai ini harus diawali dengan penerusan garis miring. Untuk jalur dasar root, tentukan hanya garis miring ke depan; misalnya, "/".

   Contoh:

   edgemicro start -o your_org -e test -k 7eb6aae644cbc09035a...d2eae46a6c095f \
     -s e16e7b1f5d5e24df...ec29d409a2df853163a -a proxy1 -v 1 \
     -t http://mocktarget.apigee.net -b /echo

Menguji konfigurasi

Anda dapat menguji konfigurasi proxy lokal dengan memanggil endpoint proxy. Misalnya, jika menentukan jalur dasar /echo, Anda dapat memanggil proxy sebagai berikut:

curl  http://localhost:8000/echo
{
  "error" : "missing_authorization",
  "error_description" : "Missing Authorization header"
}

Panggilan API awal ini menghasilkan error karena Anda tidak memberikan kunci API yang valid. Anda dapat menemukan kunci di aplikasi Developer yang Anda buat sebelumnya. Buka aplikasi di UI Edge, salin Kunci Konsumen, dan gunakan kunci tersebut sebagai berikut:

curl  http://localhost:8000/echo -H 'x-api-key:your_api_key'

Contoh:

curl  http://localhost:8000/echo -H "x-api-key:DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP"

Contoh output:

{
  "headers":{
    "user-agent":"curl/7.54.0",
    "accept":"*/*",
    "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
    "client_received_start_timestamp":"1535134472699",
    "x-authorization-claims":"eyJhdWQiOi...TQ0YmUtOWNlOS05YzM1OTE5MTA1NDkifQ==",
    "target_sent_start_timestamp":"1535134472702",
    "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
    "x-forwarded-proto":"http",
    "x-forwarded-host":"localhost:8000",
    "host":"mocktarget.apigee.net",
    "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
    "via":"1.1 localhost, 1.1 google",
    "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
    "connection":"Keep-Alive"
  },
  "method":"GET",
  "url":"/",
  "body":""
}