Tài liệu tham khảo về hoạt động và cấu hình cho Edge Microgateway

Bạn đang xem tài liệu về Apigee Edge.
Truy cập vào tài liệu Apigee X. thông tin

Edge Microgateway phiên bản 3.1.x

Chủ đề này thảo luận về cách quản lý và định cấu hình Edge Microgateway.

Nâng cấp Edge Microgateway nếu bạn có kết nối Internet

Phần này giải thích cách nâng cấp một bản cài đặt Edge Microgateway hiện có. Nếu bạn đang hoạt động mà không có kết nối Internet, hãy xem phần Tôi có thể cài đặt Edge Microgateway mà không cần kết nối Internet không?.

Apigee khuyên bạn nên kiểm thử cấu hình hiện có bằng phiên bản mới trước khi nâng cấp môi trường thực tế.

1. Thực thi lệnh npm sau đây để nâng cấp lên phiên bản mới nhất của Edge Microgateway:

   npm upgrade edgemicro -g

   Để nâng cấp lên một phiên bản cụ thể của Edge Microgateway, bạn cần chỉ định số phiên bản trong lệnh nâng cấp. Nếu bạn không chỉ định số phiên bản, phiên bản mới nhất sẽ được cài đặt. Ví dụ: để nâng cấp lên phiên bản 3.1.0, hãy dùng lệnh sau:

   npm upgrade edgemicro@3.1.0 -g

2. Kiểm tra số phiên bản. Ví dụ: nếu bạn đã cài đặt phiên bản 3.1.0:

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

3. Cuối cùng, hãy nâng cấp lên phiên bản mới nhất của proxy edgemicro-auth:

   edgemicro upgradeauth -o $ORG -e $ENV -u $USERNAME

Thực hiện các thay đổi về cấu hình

Các tệp cấu hình mà bạn cần biết bao gồm:

• Tệp cấu hình hệ thống mặc định
• Tệp cấu hình mặc định cho một phiên bản Edge Microgateway mới được khởi tạo
• Tệp cấu hình động cho các phiên bản đang chạy

Phần này thảo luận về những tệp này và những điều bạn cần biết về việc thay đổi chúng.

Tệp cấu hình hệ thống mặc định

Khi bạn cài đặt Edge Microgateway, một tệp cấu hình hệ thống mặc định sẽ được đặt tại đây:

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

Trong đó prefix là thư mục tiền tố npm. Hãy xem phần Edge Microgateway được cài đặt ở đâu nếu bạn không tìm thấy thư mục này.

Nếu thay đổi tệp cấu hình hệ thống, bạn phải khởi động lại, định cấu hình lại và khởi động lại Edge Microgateway:

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

Tệp cấu hình mặc định cho các thực thể Edge Microgateway mới được khởi động

Khi bạn chạy edgemicro init, tệp cấu hình hệ thống (được mô tả ở trên), default.yaml, sẽ được đặt trong thư mục ~/.edgemicro.

Nếu thay đổi tệp cấu hình trong ~/.edgemicro, bạn phải định cấu hình lại và khởi động lại Edge Microgateway:

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

Tệp cấu hình động cho các phiên bản đang chạy

Khi bạn chạy edgemicro configure [params], một tệp cấu hình động sẽ được tạo trong ~/.edgemicro. Tệp được đặt tên theo mẫu sau: org-env-config.yaml, trong đó org và env là tên tổ chức và môi trường Apigee Edge của bạn. Bạn có thể sử dụng tệp này để thực hiện các thay đổi về cấu hình, sau đó tải lại các thay đổi đó mà không bị gián đoạn. Ví dụ: nếu thêm và định cấu hình một trình bổ trợ, bạn có thể tải lại cấu hình mà không gặp phải thời gian ngừng hoạt động nào, như giải thích dưới đây.

Nếu Edge Microgateway đang chạy (lựa chọn không có thời gian ngừng hoạt động):

1. Tải lại cấu hình Edge Microgateway:

   edgemicro reload -o $ORG -e $ENV -k $KEY -s $SECRET

   Trong trường hợp:

   • $ORG là tên tổ chức Edge của bạn (bạn phải là quản trị viên tổ chức).
   • $ENV là một môi trường trong tổ chức của bạn (chẳng hạn như "test" hoặc "prod").
   • $KEY là khoá mà lệnh định cấu hình đã trả về trước đó.
   • $SECRET là khoá mà lệnh định cấu hình đã trả về trước đó.

   Ví dụ

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

Nếu Edge Microgateway bị dừng:

1. Khởi động lại Edge Microgateway:

   edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET

   Trong trường hợp:

   • $ORG là tên tổ chức Edge của bạn (bạn phải là quản trị viên tổ chức).
   • $ENV là một môi trường trong tổ chức của bạn (chẳng hạn như "kiểm thử" hoặc "phát hành công khai").
   • $KEY là khoá mà lệnh định cấu hình đã trả về trước đó.
   • $SECRET là khoá mà lệnh định cấu hình đã trả về trước đó.

   Ví dụ:

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

Dưới đây là một tệp cấu hình mẫu. Để biết thông tin chi tiết về các chế độ cài đặt tệp cấu hình, hãy xem phần Thông tin tham khảo về cấu hình 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

Thiết lập biến môi trường

Các lệnh giao diện dòng lệnh yêu cầu giá trị cho tổ chức và môi trường Edge của bạn, cũng như khoá và bí mật cần thiết để khởi động Edge Microgateway có thể được lưu trữ trong các biến môi trường sau:

• EDGEMICRO_ORG
• EDGEMICRO_ENV
• EDGEMICRO_KEY
• EDGEMICRO_SECRET

Bạn không bắt buộc phải đặt các biến này. Nếu thiết lập các biến này, bạn không cần chỉ định giá trị của chúng khi sử dụng Giao diện dòng lệnh (CLI) để định cấu hình và khởi động Edge Microgateway.

Định cấu hình SSL trên máy chủ Edge Microgateway

Hãy xem các video sau để tìm hiểu về cách định cấu hình TLS trong Apigee Edge Microgateway:

Bạn có thể định cấu hình máy chủ Microgateway để sử dụng SSL. Ví dụ: khi đã định cấu hình SSL, bạn có thể gọi API thông qua Edge Microgateway bằng giao thức "https", như sau:

https://localhost:8000/myapi

Để định cấu hình SSL trên máy chủ Microgateway, hãy làm theo các bước sau:

1. Tạo hoặc lấy chứng chỉ và khoá SSL bằng tiện ích openssl hoặc bất kỳ phương thức nào bạn muốn.
2. Thêm thuộc tính edgemicro:ssl vào tệp cấu hình Edge Microgateway. Để xem danh sách đầy đủ các lựa chọn, hãy xem bảng bên dưới. Ví dụ:
   

   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. Khởi động lại Edge Microgateway. Làm theo các bước được nêu trong phần Thực hiện các thay đổi về cấu hình, tuỳ thuộc vào tệp cấu hình mà bạn đã chỉnh sửa: tệp mặc định hoặc tệp cấu hình thời gian chạy.

Sau đây là ví dụ về phần edgemicro của tệp cấu hình, có SSL được định cấu hình:

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

Dưới đây là danh sách tất cả các lựa chọn máy chủ được hỗ trợ:

Sử dụng các lựa chọn SSL/TLS của ứng dụng khách

Bạn có thể định cấu hình Edge Microgateway làm ứng dụng TLS hoặc SSL khi kết nối với các điểm cuối mục tiêu. Trong tệp cấu hình Microgateway, hãy dùng phần tử targets để đặt các lựa chọn SSL/TLS.

Ví dụ này cung cấp các chế độ cài đặt sẽ được áp dụng cho tất cả các máy chủ lưu trữ:

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

Trong ví dụ này, các chế độ cài đặt chỉ được áp dụng cho máy chủ lưu trữ được chỉ định:

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

Sau đây là ví dụ về TLS:

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

Sau đây là danh sách tất cả các lựa chọn máy khách được hỗ trợ:

Tuỳ chỉnh proxy edgemicro-auth

Theo mặc định, Edge Microgateway sử dụng một proxy được triển khai trên Apigee Edge để xác thực OAuth2. Proxy này được triển khai khi bạn chạy edgemicro configure lần đầu. Bạn có thể thay đổi cấu hình mặc định của proxy này để thêm hỗ trợ cho các xác nhận quyền sở hữu tuỳ chỉnh vào Mã thông báo web JSON (JWT), định cấu hình thời gian hết hạn của mã thông báo và tạo mã thông báo làm mới. Để biết thông tin chi tiết, hãy xem trang edgemicro-auth trong GitHub.

Sử dụng dịch vụ xác thực tuỳ chỉnh

Theo mặc định, Edge Microgateway sử dụng một proxy được triển khai trên Apigee Edge để xác thực OAuth2. Proxy này được triển khai khi bạn chạy edgemicro configure lần đầu. Theo mặc định, URL của proxy này được chỉ định trong tệp cấu hình Edge Microgateway như sau:

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

Nếu bạn muốn sử dụng dịch vụ tuỳ chỉnh của riêng mình để xử lý quy trình xác thực, hãy thay đổi giá trị authUri trong tệp cấu hình để trỏ đến dịch vụ của bạn. Ví dụ: bạn có thể có một dịch vụ sử dụng LDAP để xác minh danh tính.

Quản lý tệp nhật ký

Edge Microgateway ghi nhật ký thông tin về từng yêu cầu và phản hồi. Tệp nhật ký cung cấp thông tin hữu ích cho việc gỡ lỗi và khắc phục sự cố.

Nơi lưu trữ tệp nhật ký

Theo mặc định, các tệp nhật ký được lưu trữ trong /var/tmp.

Cách thay đổi thư mục tệp nhật ký mặc định

Thư mục lưu trữ tệp nhật ký được chỉ định trong tệp cấu hình Edge Microgateway. Xem thêm phần Thực hiện các thay đổi về cấu hình.

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

Thay đổi giá trị dir để chỉ định một thư mục tệp nhật ký khác.

Gửi nhật ký đến bảng điều khiển

Bạn có thể định cấu hình tính năng ghi nhật ký để thông tin nhật ký được gửi đến đầu ra chuẩn thay vì đến một tệp nhật ký. Đặt cờ to_console thành true như sau:

edgemicro:
  logging:
    to_console: true

Với chế độ cài đặt này, nhật ký sẽ được gửi đến đầu ra tiêu chuẩn. Hiện tại, bạn không thể gửi nhật ký đến cả stdout và tệp nhật ký.

Cách thiết lập cấp độ ghi nhật ký

Bạn có thể đặt các cấp độ nhật ký sau: info, warn và error. Bạn nên sử dụng cấp độ thông tin. Nó ghi lại tất cả các yêu cầu và phản hồi API và là chế độ mặc định.

Cách thay đổi khoảng thời gian ghi nhật ký

Bạn có thể định cấu hình các khoảng thời gian này trong tệp cấu hình Edge Microgateway. Xem thêm phần Thực hiện các thay đổi về cấu hình.

Các thuộc tính có thể định cấu hình là:

• stats_log_interval: (mặc định: 60) Khoảng thời gian (tính bằng giây) khi bản ghi số liệu thống kê được ghi vào tệp nhật ký API.
• rotate_interval: (mặc định: 24) Khoảng thời gian (tính bằng giờ) khi tệp nhật ký được xoay vòng. Ví dụ:

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

Các phương pháp hay để duy trì tệp nhật ký

Khi dữ liệu tệp nhật ký tích luỹ theo thời gian, Apigee khuyên bạn nên áp dụng các phương pháp sau:

• Vì tệp nhật ký có thể trở nên khá lớn, hãy đảm bảo rằng thư mục tệp nhật ký có đủ dung lượng. Hãy xem các phần sau: Nơi lưu trữ tệp nhật ký và Cách thay đổi thư mục tệp nhật ký mặc định.
• Xoá hoặc di chuyển tệp nhật ký sang một thư mục lưu trữ riêng ít nhất một lần mỗi tuần.
• Nếu chính sách của bạn là xoá nhật ký, bạn có thể dùng lệnh CLI edgemicro log -c để xoá (dọn dẹp) nhật ký cũ.

Quy ước đặt tên tệp nhật ký

Mỗi phiên bản Edge Microgateway tạo ra 3 loại tệp nhật ký:

• api – Ghi nhật ký tất cả các yêu cầu và phản hồi truyền qua Edge Microgateway. Các bộ đếm (số liệu thống kê) và lỗi API cũng được ghi vào tệp này.
• err – Ghi nhật ký mọi nội dung được gửi đến stderr.
• out – Ghi nhật ký mọi nội dung được gửi đến stdout.

Đây là quy ước đặt tên:

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

Ví dụ:

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

Giới thiệu về nội dung tệp nhật ký

Được thêm vào trong: phiên bản 2.3.3

Theo mặc định, dịch vụ ghi nhật ký sẽ bỏ qua JSON của các proxy, sản phẩm đã tải xuống và Mã thông báo cho trang web theo chuẩn JSON (JWT). Nếu bạn muốn xuất các đối tượng này vào tệp nhật ký, hãy đặt DEBUG=* khi khởi động Edge Microgateway. Ví dụ:

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

Nội dung của tệp nhật ký "api"

Tệp nhật ký "api" chứa thông tin chi tiết về luồng yêu cầu và phản hồi thông qua Edge Microgateway. Các tệp nhật ký "api" có tên như sau:

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

Đối với mỗi yêu cầu được gửi đến Edge Microgateway, 4 sự kiện sẽ được ghi lại trong tệp nhật ký "api":

• Yêu cầu đến từ ứng dụng khách
• Đã gửi yêu cầu đi đến mục tiêu
• Phản hồi đến từ mục tiêu
• Phản hồi gửi đi cho ứng dụng

Mỗi mục riêng biệt này được biểu thị bằng ký hiệu viết tắt để giúp các tệp nhật ký trở nên nhỏ gọn hơn. Sau đây là 4 mục mẫu đại diện cho mỗi sự kiện trong số 4 sự kiện. Trong tệp nhật ký, các dòng này có dạng như sau (số dòng chỉ để tham khảo trong tài liệu, không xuất hiện trong tệp nhật ký).

(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

Hãy cùng xem xét từng loại:

1. Ví dụ về yêu cầu đến từ ứng dụng:

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

• 1436403888651 – Dấu ngày Unix
• info – Tuỳ thuộc vào ngữ cảnh. Có thể là thông tin, cảnh báo hoặc lỗi, tuỳ thuộc vào cấp độ nhật ký. Có thể là stats cho bản ghi stats, warn cho cảnh báo hoặc error cho lỗi.
• req – Xác định sự kiện. Trong trường hợp này, hãy yêu cầu từ ứng dụng.
• m – Động từ HTTP được dùng trong yêu cầu.
• u – Phần của URL sau đường dẫn cơ sở.
• h – Máy chủ lưu trữ và số cổng mà Edge Microgateway đang theo dõi.
• r – Máy chủ và cổng từ xa nơi bắt nguồn yêu cầu của ứng dụng.
• i – Mã yêu cầu. Cả 4 mục nhập sự kiện sẽ dùng chung mã nhận dạng này. Mỗi yêu cầu được chỉ định một mã yêu cầu duy nhất. Việc tương quan các bản ghi nhật ký theo mã nhận dạng yêu cầu có thể cung cấp thông tin chi tiết có giá trị về độ trễ của mục tiêu.
• d – Thời lượng tính bằng mili giây kể từ khi Edge Microgateway nhận được yêu cầu. Trong ví dụ trên, phản hồi của đích đến cho yêu cầu 0 đã được nhận sau 7 mili giây (dòng 3) và phản hồi được gửi đến ứng dụng sau thêm 4 mili giây (dòng 4). Nói cách khác, tổng độ trễ của yêu cầu là 11 mili giây, trong đó mục tiêu mất 7 mili giây và Edge Microgateway mất 4 mili giây.

2. Mẫu yêu cầu gửi đi được thực hiện cho mục tiêu:

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

• 1436403888651 – Dấu ngày Unix
• info – Tuỳ thuộc vào ngữ cảnh. Có thể là thông tin, cảnh báo hoặc lỗi, tuỳ thuộc vào cấp độ nhật ký. Có thể là stats cho bản ghi stats, warn cho cảnh báo hoặc error cho lỗi.
• treq – Xác định sự kiện. Trong trường hợp này, hãy nhắm đến yêu cầu.
• m – Động từ HTTP được dùng trong yêu cầu mục tiêu.
• u – Phần của URL sau đường dẫn cơ sở.
• h – Số cổng và máy chủ lưu trữ của mục tiêu phụ trợ.
• i – Mã nhận dạng của mục nhập nhật ký. Cả 4 mục nhập sự kiện sẽ dùng chung mã nhận dạng này.

3. Mẫu phản hồi đến từ mục tiêu

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

1436403888651 – Dấu ngày Unix

• info – Tuỳ thuộc vào ngữ cảnh. Có thể là thông tin, cảnh báo hoặc lỗi, tuỳ thuộc vào cấp độ nhật ký. Có thể là stats cho bản ghi stats, warn cho cảnh báo hoặc error cho lỗi.
• tres – Xác định sự kiện. Trong trường hợp này, hãy nhắm đến câu trả lời.
• s – Trạng thái phản hồi HTTP.
• d – Thời lượng tính bằng mili giây. Thời gian mà đích đến thực hiện lệnh gọi API.
• i – Mã nhận dạng của mục nhập nhật ký. Cả 4 mục nhập sự kiện sẽ dùng chung mã nhận dạng này.

4. Mẫu phản hồi gửi đi cho khách hàng

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

1436403888651 – Dấu ngày Unix

• info – Tuỳ thuộc vào ngữ cảnh. Có thể là thông tin, cảnh báo hoặc lỗi, tuỳ thuộc vào cấp độ nhật ký. Có thể là stats cho bản ghi stats, warn cho cảnh báo hoặc error cho lỗi.
• res – Xác định sự kiện. Trong trường hợp này, hãy phản hồi cho máy khách.
• s – Trạng thái phản hồi HTTP.
• d – Thời lượng tính bằng mili giây. Đây là tổng thời gian mà lệnh gọi API sử dụng, bao gồm cả thời gian mà API mục tiêu sử dụng và thời gian mà Edge Microgateway sử dụng.
• i – Mã nhận dạng của mục nhập nhật ký. Cả 4 mục nhập sự kiện sẽ dùng chung mã nhận dạng này.

Lịch biểu tệp nhật ký

Các tệp nhật ký được xoay theo khoảng thời gian do rotate_interval rotate_interval chỉ định. Các mục sẽ tiếp tục được thêm vào cùng một tệp nhật ký cho đến khi hết khoảng thời gian xoay vòng. Tuy nhiên, mỗi khi Edge Microgateway khởi động lại, nó sẽ nhận được một UID mới và tạo một tập hợp tệp nhật ký mới bằng UID này. Xem thêm Các phương pháp hay để duy trì tệp nhật ký.

Thông báo lỗi

Một số mục nhật ký sẽ chứa thông báo lỗi. Để xác định vị trí và lý do xảy ra lỗi, hãy xem tài liệu tham khảo về lỗi Edge Microgateway.

Thông tin tham khảo về cấu hình Edge Microgateway

Vị trí của tệp cấu hình

Các thuộc tính cấu hình được mô tả trong phần này nằm trong tệp cấu hình Edge Microgateway. Xem thêm phần Thực hiện các thay đổi về cấu hình.

Thuộc tính edge_config

Các chế độ cài đặt này được dùng để định cấu hình hoạt động tương tác giữa thực thể Edge Microgateway và Apigee Edge.

• bootstrap: (mặc định: none) Một URL trỏ đến dịch vụ dành riêng cho Edge Microgateway đang chạy trên Apigee Edge. Edge Microgateway sử dụng dịch vụ này để giao tiếp với Apigee Edge. URL này được trả về khi bạn thực thi lệnh để tạo cặp khoá công khai/riêng tư: edgemicro genkeys. Hãy xem phần Thiết lập và định cấu hình Edge Microgateway để biết thông tin chi tiết.
• jwt_public_key: (mặc định: none) Một URL trỏ đến proxy Edge Microgateway được triển khai trên Apigee Edge. Proxy này đóng vai trò là một điểm cuối xác thực để phát hành mã truy cập đã ký cho các ứng dụng. URL này được trả về khi bạn thực thi lệnh triển khai proxy: edgemicro configure. Hãy xem phần Thiết lập và định cấu hình Edge Microgateway để biết thông tin chi tiết.
• quotaUri: Đặt thuộc tính cấu hình này nếu bạn muốn quản lý hạn mức thông qua proxy edgemicro-auth được triển khai cho tổ chức của bạn. Nếu bạn không đặt thuộc tính này, thì điểm cuối hạn mức sẽ mặc định là điểm cuối Edge Microgateway nội bộ.

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

thuộc tính edgemicro

Các chế độ cài đặt này sẽ định cấu hình quy trình Edge Microgateway.

• port: (mặc định: 8000) Số cổng mà quy trình Edge Microgateway theo dõi.
• max_connections: (mặc định: -1) Chỉ định số lượng tối đa các kết nối đồng thời đến mà Edge Microgateway có thể nhận được. Nếu vượt quá số này, trạng thái sau đây sẽ được trả về:
  
  res.statusCode = 429; // Too many requests
  
• max_connections_hard: (mặc định: -1) Số lượng yêu cầu đồng thời tối đa mà Edge Microgateway có thể nhận được trước khi tắt kết nối. Chế độ cài đặt này nhằm mục đích ngăn chặn các cuộc tấn công từ chối dịch vụ. Thông thường, hãy đặt giá trị này thành một số lớn hơn max_connections.
• logging (ghi nhật ký):
  • level: (mặc định: error)
    • info – Ghi nhật ký tất cả các yêu cầu và phản hồi truyền qua một thực thể Edge Microgateway.
    • warn – Chỉ ghi lại thông báo cảnh báo.
    • error – Chỉ ghi thông báo lỗi.
  • dir: (mặc định: /var/tmp) Thư mục lưu trữ tệp nhật ký.
  • stats_log_interval: (mặc định: 60) Khoảng thời gian (tính bằng giây) khi bản ghi số liệu thống kê được ghi vào tệp nhật ký api.
  • rotate_interval: (mặc định: 24) Khoảng thời gian (tính bằng giờ) khi tệp nhật ký được xoay vòng.

• plugin: Các trình bổ trợ thêm chức năng cho Edge Microgateway. Để biết thông tin chi tiết về cách phát triển trình bổ trợ, hãy xem bài viết Phát triển trình bổ trợ tuỳ chỉnh.

• dir: Đường dẫn tương đối từ thư mục ./gateway đến thư mục ./plugins hoặc đường dẫn tuyệt đối.
• sequence: Danh sách các mô-đun trình bổ trợ cần thêm vào phiên bản Edge Microgateway. Các mô-đun sẽ thực thi theo thứ tự được chỉ định ở đây.

• debug: Thêm tính năng gỡ lỗi từ xa vào quy trình Edge Microgateway.
  • port: Số cổng cần theo dõi. Ví dụ: thiết lập trình gỡ lỗi IDE để theo dõi trên cổng này.
  • args: Đối số cho quy trình gỡ lỗi. Ví dụ: args --nolazy
    
• config_change_poll_interval: (mặc định: 600 giây) Edge Microgateway tải định kỳ một cấu hình mới và thực thi một lần tải lại nếu có thay đổi. Hoạt động thăm dò ý kiến sẽ ghi nhận mọi thay đổi được thực hiện trên Edge (thay đổi đối với sản phẩm, các proxy có nhận biết cổng siêu nhỏ, v.v.) cũng như những thay đổi được thực hiện đối với tệp cấu hình cục bộ.
  
• disable_config_poll_interval: (mặc định: false) Đặt thành true để tắt tính năng tự động thăm dò ý kiến về thay đổi.
• request_timeout: Đặt thời gian chờ cho các yêu cầu mục tiêu. Thời gian chờ được đặt tính bằng giây. Nếu xảy ra hết thời gian chờ, Edge Microgateway sẽ phản hồi bằng mã trạng thái 504. (Đã thêm phiên bản 2.4.x)
• keep_alive_timeout: Thuộc tính này cho phép bạn đặt thời gian chờ của Edge Microgateway (tính bằng mili giây). (Mặc định: 5 giây) (Đã thêm trong phiên bản 3.0.6)
• headers_timeout: Thuộc tính này giới hạn khoảng thời gian (tính bằng mili giây) mà trình phân tích cú pháp HTTP sẽ đợi để nhận tiêu đề HTTP hoàn chỉnh.

  Ví dụ:

  edgemicro:
  keep_alive_timeout: 6000
  headers_timeout: 12000

  Về nội bộ, tham số này đặt thuộc tính Server.headersTimeout Node.js cho các yêu cầu. (Mặc định: thêm 5 giây so với thời gian đặt bằng edgemicro.keep_alive_timeout. Chế độ cài đặt mặc định này giúp ngăn bộ cân bằng tải hoặc proxy vô tình làm rớt kết nối.) (Đã thêm trong phiên bản 3.1.1)

thuộc tính tiêu đề

Các chế độ cài đặt này định cấu hình cách xử lý một số tiêu đề HTTP.

• x-forwarded-for: (mặc định: true) Đặt thành false để ngăn tiêu đề x-forwarded-for được truyền đến đích. Xin lưu ý rằng nếu tiêu đề x-forwarded-for nằm trong yêu cầu, thì giá trị của tiêu đề đó sẽ được đặt thành giá trị client-ip trong Edge Analytics.
• x-forwarded-host: (mặc định: true) Đặt thành false để ngăn tiêu đề x-forwarded-host được truyền đến mục tiêu.
• x-request-id: (mặc định: true) Đặt thành false để ngăn tiêu đề x-request-id được truyền đến mục tiêu.
• x-response-time: (mặc định: true) Đặt thành false để ngăn tiêu đề x-response-time được truyền đến mục tiêu.
• via: (mặc định: true) Đặt thành false để ngăn tiêu đề via được truyền đến đích.

thuộc tính oauth

Các chế độ cài đặt này định cấu hình cách Edge Microgateway thực thi việc xác thực máy khách.

• allowNoAuthorization: (mặc định: false) Nếu bạn đặt thành true, các lệnh gọi API sẽ được phép truyền qua Edge Microgateway mà không cần bất kỳ tiêu đề Uỷ quyền nào. Đặt giá trị này thành false để yêu cầu tiêu đề Uỷ quyền (mặc định).
• allowInvalidAuthorization: (mặc định: false) Nếu được đặt thành true, các lệnh gọi API sẽ được phép truyền nếu mã thông báo được truyền trong tiêu đề Uỷ quyền không hợp lệ hoặc đã hết hạn. Đặt giá trị này thành false để yêu cầu mã thông báo hợp lệ (mặc định).
• authorization-header: (mặc định: Authorization: Bearer) Tiêu đề dùng để gửi mã truy cập đến Edge Microgateway. Bạn nên thay đổi giá trị mặc định trong trường hợp đích cần sử dụng tiêu đề Uỷ quyền cho một mục đích khác.
• api-key-header: (mặc định: x-api-key) Tên của tiêu đề hoặc tham số truy vấn dùng để truyền khoá API đến Edge Microgateway. Xem thêm phần Sử dụng khoá API.
• keep-authorization-header: (mặc định: false) Nếu được đặt thành true, tiêu đề Uỷ quyền được gửi trong yêu cầu sẽ được chuyển đến mục tiêu (được giữ nguyên).
• allowOAuthOnly – Nếu được đặt thành true, mọi API đều phải có tiêu đề Uỷ quyền kèm theo Mã thông báo truy cập của người mang. Cho phép bạn chỉ cho phép mô hình bảo mật OAuth (trong khi vẫn duy trì khả năng tương thích ngược). (Được thêm vào phiên bản 2.4.x)
• allowAPIKeyOnly – Nếu được đặt thành true, mọi API phải mang tiêu đề x-api-key (hoặc một vị trí tuỳ chỉnh) có Khoá API.Cho phép bạn chỉ cho phép mô hình bảo mật khoá API (trong khi vẫn duy trì khả năng tương thích ngược). (Đã thêm 2.4.x)
• gracePeriod – Tham số này giúp ngăn chặn lỗi do sự khác biệt nhỏ giữa đồng hồ hệ thống và thời gian Không được phép trước (nbf) hoặc Thời gian phát hành (iat) được chỉ định trong mã thông báo uỷ quyền JWT. Đặt tham số này thành số giây cho phép đối với những điểm khác biệt như vậy. (Thêm vào phiên bản 2.5.7)

Thuộc tính dành riêng cho trình bổ trợ

Hãy xem phần Sử dụng trình bổ trợ để biết thông tin chi tiết về các thuộc tính có thể định cấu hình cho từng trình bổ trợ.

Lọc proxy

Bạn có thể lọc những proxy có nhận biết microgateway mà một thực thể Edge Microgateway sẽ xử lý. Khi Edge Microgateway khởi động, nó sẽ tải xuống tất cả các proxy có nhận biết microgateway trong tổ chức mà nó được liên kết. Sử dụng cấu hình sau để giới hạn những proxy mà microgateway sẽ xử lý. Ví dụ: cấu hình này giới hạn số lượng proxy mà microgateway sẽ xử lý ở mức 3: edgemicro_proxy-1, edgemicro_proxy-2 và edgemicro_proxy-3:

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

Lọc sản phẩm

Sử dụng cấu hình sau để giới hạn số lượng sản phẩm API mà Edge Microgateway tải xuống và xử lý. Để lọc các sản phẩm đã tải xuống, hãy thêm tham số truy vấn productnamefilter vào API /products được liệt kê trong tệp *.config.yaml Edge Microgateway. Ví dụ:

edge_config:
  bootstrap: >-
    https://edgemicroservices.apigee.net/edgemicro/bootstrap/organization/willwitman/environment/test
  jwt_public_key: 'https://myorg-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://myorg-test.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24'

Xin lưu ý rằng bạn phải chỉ định giá trị của tham số truy vấn ở định dạng biểu thức chính quy và được mã hoá URL. Ví dụ: biểu thức chính quy ^[Ee]dgemicro.*$ sẽ bắt các tên như: "edgemicro-test-1", "edgemicro_demo" và "Edgemicro_New_Demo". Giá trị được mã hoá URL, phù hợp để sử dụng trong tham số truy vấn là: %5E%5BEe%5Ddgemicro.%2A%24.

Đầu ra gỡ lỗi sau đây cho thấy chỉ những sản phẩm được lọc mới được tải xuống:

...
2020-05-27T03:13:50.087Z [76060] [microgateway-config network] products download from https://gsc-demo-prod.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24 returned 200 OK
...
....
....
{
   "apiProduct":[
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590549037549,
         "createdBy":"k***@g********m",
         "displayName":"test upper case in name",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590549037549,
         "lastModifiedBy":"k***@g********m",
         "name":"Edgemicro_New_Demo",
         "proxies":[
            "catchall"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590548328998,
         "createdBy":"k***@g********m",
         "displayName":"edgemicro test 1",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590548328998,
         "lastModifiedBy":"k***@g********m",
         "name":"edgemicro-test-1",
         "proxies":[
            "Lets-Encrypt-Validation-DoNotDelete"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[
            "/",
            "/**"
         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1558182193472,
         "createdBy":"m*********@g********m",
         "displayName":"Edge microgateway demo product",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1569077897465,
         "lastModifiedBy":"m*********@g********m",
         "name":"edgemicro_demo",
         "proxies":[
            "edgemicro-auth",
            "edgemicro_hello"
         ],
         "quota":"600",
         "quotaInterval":"1",
         "quotaTimeUnit":"minute",
         "scopes":[

         ]
      }
   ]
}

Định cấu hình tần suất gửi dữ liệu phân tích

Sử dụng các thông số cấu hình này để kiểm soát tần suất mà Edge Microgateway gửi dữ liệu phân tích đến Apigee:

• bufferSize (Không bắt buộc): Số lượng tối đa các bản ghi phân tích mà vùng đệm có thể chứa trước khi bắt đầu loại bỏ các bản ghi cũ nhất. Mặc định: 10000
• batchSize (Không bắt buộc): Kích thước tối đa của một lô bản ghi phân tích được gửi đến Apigee. Mặc định: 500
• flushInterval (Không bắt buộc): Số mili giây giữa mỗi lần xả dữ liệu một lô bản ghi số liệu phân tích được gửi đến Apigee. Mặc định: 5000

Ví dụ:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

Che dữ liệu phân tích

Cấu hình sau đây ngăn thông tin về đường dẫn yêu cầu xuất hiện trong số liệu phân tích của Edge. Thêm nội dung sau vào cấu hình microgateway để che URI yêu cầu và/hoặc đường dẫn yêu cầu. Xin lưu ý rằng URI bao gồm tên máy chủ và các phần đường dẫn của yêu cầu.

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

Phân tách các lệnh gọi API trong Edge Analytics

Bạn có thể định cấu hình trình bổ trợ phân tích để phân tách một đường dẫn API cụ thể để đường dẫn đó xuất hiện dưới dạng một proxy riêng biệt trong trang tổng quan Edge Analytics. Ví dụ: bạn có thể tách biệt một API kiểm tra tình trạng hoạt động trong trang tổng quan để tránh nhầm lẫn với các lệnh gọi proxy API thực tế. Trong trang tổng quan Analytics, các proxy tách biệt tuân theo mẫu đặt tên sau:

edgemicro_proxyname-health

Hình ảnh sau đây cho thấy 2 proxy riêng biệt trong trang tổng quan Analytics: edgemicro_hello-health và edgemicro_mock-health:

Sử dụng các tham số này để phân tách đường dẫn tương đối và đường dẫn tuyệt đối trong trang tổng quan Analytics dưới dạng các proxy riêng biệt:

• relativePath (Không bắt buộc): Chỉ định một đường dẫn tương đối để phân tách trong trang tổng quan Analytics. Ví dụ: nếu bạn chỉ định /healthcheck, tất cả lệnh gọi API chứa đường dẫn /healthcheck sẽ xuất hiện trong trang tổng quan dưới dạng edgemicro_proxyname-health. Xin lưu ý rằng cờ này bỏ qua đường dẫn cơ sở của proxy. Để phân tách dựa trên đường dẫn đầy đủ, bao gồm cả basepath, hãy dùng cờ proxyPath.
• proxyPath (Không bắt buộc): Chỉ định đường dẫn đầy đủ của API proxy, bao gồm cả basepath của proxy, để phân tách trong trang tổng quan phân tích. Ví dụ: nếu bạn chỉ định /mocktarget/healthcheck, trong đó /mocktarget là đường dẫn cơ sở của proxy, thì tất cả các lệnh gọi API có đường dẫn /mocktarget/healthcheck sẽ xuất hiện trong trang tổng quan dưới dạng edgemicro_proxyname-health.

Ví dụ: trong cấu hình sau, mọi đường dẫn API chứa /healthcheck sẽ được phân tách bằng trình bổ trợ phân tích. Điều này có nghĩa là /foo/healthcheck và /foo/bar/healthcheck sẽ được tách biệt dưới dạng một proxy riêng biệt có tên là edgemicro_proxyname-health trong trang tổng quan phân tích.

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

Trong cấu hình sau, mọi API có đường dẫn proxy /mocktarget/healthcheck sẽ được tách biệt dưới dạng một proxy riêng biệt có tên là edgemicro_proxyname-health trong trang tổng quan phân tích.

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

Thiết lập Edge Microgateway phía sau tường lửa của công ty

Sử dụng proxy HTTP để giao tiếp với Apigee Edge

Được thêm vào phiên bản 3.1.2.

Để sử dụng một proxy HTTP cho hoạt động giao tiếp giữa Edge Microgateway và Apigee Edge, hãy làm như sau:

1. Đặt các biến môi trường HTTP_PROXY, HTTPS_PROXY và NO_PROXY. Các biến này kiểm soát máy chủ lưu trữ cho từng proxy HTTP mà bạn muốn dùng để giao tiếp với Apigee Edge, hoặc máy chủ lưu trữ nào không được xử lý giao tiếp với Apigee Edge. Ví dụ:

   export HTTP_PROXY='http://localhost:3786'
   export HTTPS_PROXY='https://localhost:3786'
   export NO_PROXY='localhost,localhost:8080'

   Xin lưu ý rằng NO_PROXY có thể là danh sách các miền được phân tách bằng dấu phẩy mà Edge Microgateway không nên chuyển đến.

   Để biết thêm thông tin về các biến này, hãy xem https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables

2. Khởi động lại Edge Microgateway.

Sử dụng proxy HTTP cho hoạt động giao tiếp với mục tiêu

Được thêm vào phiên bản 3.1.2.

Để sử dụng một proxy HTTP cho hoạt động giao tiếp giữa Edge Microgateway và các mục tiêu phụ trợ, hãy làm như sau:

1. Thêm cấu hình sau vào tệp cấu hình microgateway:

   edgemicro:
     proxy:
       tunnel: true | false
       url: proxy_url
       bypass: target_host # target hosts to bypass the proxy.
       enabled: true | false

   Trong trường hợp:

   • tunnel: (Không bắt buộc) Khi có giá trị true, Edge Microgateway sẽ dùng phương thức HTTP CONNECT để chuyển yêu cầu HTTP qua một kết nối TCP duy nhất. (Điều này cũng đúng nếu các biến môi trường (như đề cập bên dưới) để định cấu hình proxy được bật TLS). Mặc định: false
   • url: URL của proxy HTTP.
   • bypass: (Không bắt buộc) Chỉ định một hoặc nhiều URL máy chủ đích được phân tách bằng dấu phẩy sẽ bỏ qua proxy HTTP. Nếu bạn không đặt thuộc tính này, hãy sử dụng biến môi trường NO_PROXY để chỉ định URL mục tiêu cần bỏ qua.
   • enabled: Nếu đúng và proxy.url được đặt, hãy sử dụng giá trị proxy.url cho proxy HTTP. Nếu đúng và proxy.url chưa được đặt, hãy sử dụng các proxy được chỉ định trong các biến môi trường proxy HTTP HTTP_PROXY và HTTPS_PROXY, như mô tả trong phần Sử dụng proxy HTTP để giao tiếp với Apigee Edge.

   Ví dụ:

   edgemicro:
     proxy:
       tunnel: true
       url: 'http://localhost:3786'
       bypass: 'localhost','localhost:8080' # target hosts to bypass the proxy.
       enabled: true

2. Khởi động lại Edge Microgateway.

Sử dụng ký tự đại diện trong các proxy có nhận biết Microgateway

Bạn có thể sử dụng một hoặc nhiều ký tự đại diện "*" trong đường dẫn cơ sở của một proxy edgemicro_* (có hỗ trợ Microgateway). Ví dụ: đường dẫn cơ sở /team/*/members cho phép các ứng dụng gọi https://[host]/team/blue/members và https://[host]/team/green/members mà bạn không cần tạo các proxy API mới để hỗ trợ các nhóm mới. Xin lưu ý rằng /**/ không được hỗ trợ.

Lưu ý quan trọng: Apigee KHÔNG hỗ trợ việc sử dụng ký tự đại diện "*" làm phần tử đầu tiên của đường dẫn cơ sở. Ví dụ: tính năng tìm kiếm bằng /*/ KHÔNG được hỗ trợ.

Xoay vòng khoá JWT

Vào một thời điểm nào đó sau khi tạo JWT lần đầu, bạn có thể cần thay đổi cặp khoá công khai/riêng tư được lưu trữ trong KVM được mã hoá của Edge. Quá trình tạo cặp khoá mới này được gọi là xoay vòng khoá.

Cách Edge Microgateway sử dụng JWT

Mã thông báo web JSON (JWT) là một tiêu chuẩn mã thông báo được mô tả trong RFC7519. JWT cung cấp một cách để ký một tập hợp các yêu cầu, tập hợp này có thể được người nhận JWT xác minh một cách đáng tin cậy.

Edge Microgateway sử dụng JWT làm mã thông báo của người mang cho tính năng bảo mật OAuth. Khi tạo mã thông báo OAuth cho Edge Microgateway, bạn sẽ nhận được một JWT. Sau đó, bạn có thể sử dụng JWT trong tiêu đề Uỷ quyền của các lệnh gọi API. Ví dụ:

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

Tạo JWT mới

Bạn có thể tạo JWT cho Edge Microgateway bằng lệnh edgemicro token hoặc một API. Ví dụ:

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

Lệnh này yêu cầu Apigee Edge tạo một JWT mà sau đó có thể dùng để xác minh các lệnh gọi API. Các tham số -i và -s là giá trị mã nhận dạng và khoá bí mật của người dùng từ một ứng dụng dành cho nhà phát triển trong tổ chức Apigee Edge của bạn.

Hoặc bạn cũng có thể tạo JWT bằng API quản lý:

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"
  }'

Trong trường hợp:

• $ORG là tên tổ chức Edge của bạn (bạn phải là quản trị viên tổ chức).
• $ENV là một môi trường trong tổ chức của bạn (chẳng hạn như "test" hoặc "prod").
• $CLIENT_ID là mã nhận dạng người tiêu dùng trong Ứng dụng dành cho nhà phát triển mà bạn đã tạo trước đó.
• $CLIENT_SECRET là Consumer Secret (Khoá bí mật của người dùng) trong Ứng dụng nhà phát triển mà bạn đã tạo trước đó.

Xoay vòng khoá là gì?

Vào một thời điểm nào đó sau khi tạo JWT lần đầu, bạn có thể cần thay đổi cặp khoá công khai/riêng tư được lưu trữ trong KVM được mã hoá của Edge. Quá trình tạo cặp khoá mới này được gọi là xoay vòng khoá. Khi bạn xoay khoá, một cặp khoá riêng tư/công khai mới sẽ được tạo và lưu trữ trong KVM "microgateway" trong tổ chức/môi trường Apigee Edge của bạn. Ngoài ra, khoá công khai cũ vẫn được giữ lại cùng với giá trị mã nhận dạng khoá ban đầu.

Để tạo JWT, Edge sử dụng thông tin được lưu trữ trong KVM đã mã hoá. Một KVM có tên là microgatewayđã được tạo và điền sẵn các khoá khi bạn thiết lập (định cấu hình) Edge Microgateway lần đầu. Các khoá trong KVM được dùng để ký và mã hoá JWT.

Các phím KVM bao gồm:

• private_key – Khoá riêng tư RSA mới nhất (mới được tạo gần đây nhất) dùng để ký JWT.

• public_key – Chứng chỉ mới nhất (mới được tạo gần đây nhất) dùng để xác minh JWT được ký bằng khoá riêng tư.

• private_key_kid – Mã khoá riêng tư mới nhất (mã được tạo gần đây nhất). Mã khoá này được liên kết với giá trị private_key và được dùng để hỗ trợ tính năng xoay vòng khoá.

• public_key1_kid – Mã nhận dạng khoá công khai mới nhất (được tạo gần đây nhất). Khoá này được liên kết với giá trị public_key1 và được dùng để hỗ trợ tính năng xoay khoá. Giá trị này giống với khoá riêng tư.

• public_key1 – Khoá công khai mới nhất (được tạo gần đây nhất).

Khi bạn thực hiện xoay khoá, các giá trị khoá hiện có sẽ được thay thế trong bản đồ và các khoá mới sẽ được thêm vào để giữ lại các khoá công khai cũ. Ví dụ:

• public_key2_kid – Mã khoá công khai cũ. Khoá này được liên kết với giá trị public_key2 và được dùng để hỗ trợ tính năng xoay khoá.

• public_key2 – Khoá công khai cũ.

JWT được trình bày để xác minh sẽ được xác minh bằng khoá công khai mới. Nếu quá trình xác minh không thành công, thì khoá công khai cũ sẽ được dùng cho đến khi hết hạn (sau 30 phút). Bằng cách này, bạn có thể "xoay vòng" các khoá mà không làm gián đoạn ngay lưu lượng truy cập API.

Cách xoay vòng khoá

Phần này giải thích cách thực hiện quy trình xoay vòng khoá.

Nếu bạn đã định cấu hình phiên bản Edge Microgateway trước phiên bản 2.5.2

Nếu đã định cấu hình phiên bản Edge Microgateway trước phiên bản 2.5.2, thì bạn phải chạy 2 lệnh sau để nâng cấp KVM và chính sách xác thực:

upgradekvm -o $ORG -e $ENV -u $USERNAME

Để biết thêm thông tin về lệnh này, hãy xem phần Nâng cấp KVM.

Lệnh tiếp theo sẽ nâng cấp proxy edgemicro-oauth đã được triển khai cho tổ chức Apigee của bạn khi bạn định cấu hình Edge Microgateway. Proxy này cung cấp các dịch vụ cần thiết để tạo mã thông báo.

upgradeauth -o $ORG -e $ENV -u $USERNAME

Để biết thêm thông tin về lệnh này, hãy xem phần Nâng cấp proxy edgemicro-auth.

Xoay vòng các khoá

Thêm dòng sau vào tệp ~/.edgemicro/org-env-config.yaml, trong đó bạn phải chỉ định cùng một tổ chức và môi trường mà bạn đã định cấu hình để microgateway sử dụng:

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

Chạy lệnh xoay khoá để xoay các khoá. (Để biết thêm thông tin về lệnh này, hãy xem phần Xoay khoá.)

edgemicro rotatekey -o $ORG -e $ENV -u $USERNAME -k $KID_VALUE

Ví dụ:

edgemicro rotatekey -o jdoe -e test -u jdoe@google.com -k 2
current nodejs version is v12.5.0
current edgemicro version is 3.1.0
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!

Tham số -k chỉ định một mã khoá (kid). Mã nhận dạng này được dùng để so khớp một khoá cụ thể. Edge Microgateway sử dụng giá trị này để chọn trong số một nhóm khoá trong quá trình xoay vòng khoá. Để biết thêm thông tin, hãy xem Phần 4.5 của quy cách Khoá web JSON.

Sau khi xoay khoá, Edge sẽ trả về nhiều khoá cho Edge Microgateway. Lưu ý trong ví dụ sau, mỗi khoá có một giá trị "kid" (Mã khoá) riêng biệt. Sau đó, microgateway sẽ dùng các khoá này để xác thực mã thông báo uỷ quyền. Nếu quá trình xác thực mã thông báo không thành công, microgateway sẽ tìm xem có khoá cũ hơn trong bộ khoá hay không và thử khoá đó. Định dạng của các khoá được trả về là Khoá web JSON (JWK). Bạn có thể đọc về định dạng này trong 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"
    }
  ]
}

Lọc proxy đã tải xuống

Theo mặc định, Edge Microgateway sẽ tải xuống tất cả các proxy trong tổ chức Edge của bạn bắt đầu bằng tiền tố đặt tên "edgemicro_". Bạn có thể thay đổi chế độ mặc định này để tải các proxy có tên khớp với một mẫu.

1. Mở tệp cấu hình Edge Micro: ~/.edgemicro/org-env-config.yaml
2. Thêm phần tử proxyPattern trong edge_config. Ví dụ: mẫu sau đây sẽ tải các proxy xuống, chẳng hạn như edgemicro_foo, edgemicro_fast và edgemicro_first.

   edge_config:
   …
   proxyPattern: edgemicro_f*

Chỉ định sản phẩm không có proxy API

Trong Apigee Edge, bạn có thể tạo một sản phẩm API không chứa bất kỳ proxy API nào. Cấu hình sản phẩm này cho phép một khoá API được liên kết với sản phẩm đó hoạt động với mọi proxy được triển khai trong tổ chức của bạn. Kể từ phiên bản 2.5.4, Edge Microgateway hỗ trợ cấu hình sản phẩm này.

Gỡ lỗi và khắc phục sự cố

Kết nối với trình gỡ lỗi

Bạn có thể chạy Edge Microgateway bằng một trình gỡ lỗi, chẳng hạn như node-inspector. Điều này hữu ích cho việc khắc phục sự cố và gỡ lỗi các trình bổ trợ tuỳ chỉnh.

1. Khởi động lại Edge Microgateway ở chế độ gỡ lỗi. Để thực hiện việc này, hãy thêm DEBUG=* vào đầu lệnh start:

   DEBUG=* edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET

   Để chuyển hướng đầu ra gỡ lỗi đến một tệp, bạn có thể sử dụng lệnh sau:

   export DEBUG=* nohup edgemicro start \
   -o $ORG -e $ENV -k $KEY -s $SECRET 2>&1 | tee /tmp/file.log

2. Khởi động trình gỡ lỗi và đặt trình gỡ lỗi ở chế độ nghe trên số cổng cho quy trình gỡ lỗi.
3. Giờ đây, bạn có thể thực hiện từng bước trong mã Edge Microgateway, đặt điểm ngắt, theo dõi biểu thức, v.v.

Bạn có thể chỉ định các cờ Node.js tiêu chuẩn liên quan đến chế độ gỡ lỗi. Ví dụ: --nolazy giúp gỡ lỗi mã không đồng bộ.

Kiểm tra tệp nhật ký

Nếu bạn gặp vấn đề, hãy nhớ kiểm tra tệp nhật ký để biết thông tin chi tiết về quá trình thực thi và thông tin lỗi. Để biết thông tin chi tiết, hãy xem phần Quản lý tệp nhật ký.

Sử dụng tính năng bảo mật khoá API

Khoá API cung cấp một cơ chế đơn giản để xác thực các ứng dụng gửi yêu cầu đến Edge Microgateway. Bạn có thể lấy khoá API bằng cách sao chép giá trị Khoá người dùng (còn gọi là Mã ứng dụng khách) từ một sản phẩm Apigee Edge có chứa proxy xác thực Edge Microgateway.

Lưu khoá vào bộ nhớ đệm

Khoá API được trao đổi để lấy mã thông báo của người mang và được lưu vào bộ nhớ đệm. Bạn có thể tắt tính năng lưu vào bộ nhớ đệm bằng cách đặt tiêu đề Cache-Control: no-cache cho các yêu cầu đến thành Edge Microgateway.

Sử dụng khoá API

Bạn có thể truyền khoá API trong một yêu cầu API dưới dạng tham số truy vấn hoặc trong tiêu đề. Theo mặc định, tên tham số truy vấn và tiêu đề đều là x-api-key.

Ví dụ về tham số truy vấn:

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

Ví dụ về tiêu đề:

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

Định cấu hình tên khoá API

Theo mặc định, x-api-key là tên được dùng cho cả tiêu đề khoá API và tham số truy vấn. Bạn có thể thay đổi giá trị mặc định này trong tệp cấu hình, như được giải thích trong phần Thực hiện các thay đổi về cấu hình. Ví dụ: để thay đổi tên thành apiKey:

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

Trong ví dụ này, cả tham số truy vấn và tên tiêu đề đều được thay đổi thành apiKey. Tên x-api-key sẽ không hoạt động trong cả hai trường hợp. Xem thêm phần Thực hiện các thay đổi về cấu hình.

Ví dụ:

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

Để biết thêm thông tin về cách sử dụng khoá API với các yêu cầu proxy, hãy xem phần Secure Edge Microgateway.

Bật mã phản hồi nguồn

Theo mặc định, trình bổ trợ oauth chỉ trả về mã trạng thái lỗi 4xx nếu phản hồi không phải là trạng thái 200. Bạn có thể thay đổi hành vi này để luôn trả về chính xác mã 4xx hoặc 5xx, tuỳ thuộc vào lỗi.

Để bật tính năng này, hãy thêm thuộc tính oauth.useUpstreamResponse: true vào cấu hình Edge Microgateway. Ví dụ:

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

Sử dụng tính năng bảo mật mã thông báo OAuth2

Phần này giải thích cách lấy mã truy cập OAuth2 và mã làm mới. Mã truy cập được dùng để thực hiện các lệnh gọi API bảo mật thông qua cổng vi mô. Mã làm mới được dùng để lấy mã truy cập mới.

Cách lấy mã truy cập

Phần này giải thích cách sử dụng proxy edgemicro-auth để lấy mã truy cập.

Bạn cũng có thể lấy mã truy cập bằng lệnh edgemicro token của CLI. Để biết thông tin chi tiết về CLI, hãy xem phần Quản lý mã thông báo.

API 1: Gửi thông tin đăng nhập dưới dạng tham số nội dung

Thay thế tên tổ chức và môi trường của bạn trong URL, đồng thời thay thế các giá trị Mã nhận dạng người dùng và Khoá bí mật người dùng mà bạn nhận được từ một ứng dụng dành cho nhà phát triển trên Apigee Edge cho các tham số client_id và client_secret trong phần nội dung:

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: Gửi thông tin đăng nhập trong tiêu đề Xác thực cơ bản

Gửi thông tin đăng nhập của ứng dụng khách dưới dạng tiêu đề Xác thực cơ bản và grant_type dưới dạng tham số biểu mẫu. Dạng lệnh này cũng được thảo luận trong RFC 6749: Khung uỷ quyền 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"

Đầu ra mẫu

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

Cách lấy mã làm mới

Để nhận mã làm mới, hãy thực hiện một lệnh gọi API đến điểm cuối /token của proxy edgemicro-auth. Bạn PHẢI thực hiện lệnh gọi API này bằng loại hình cấp phép password. Các bước sau đây sẽ hướng dẫn bạn thực hiện quy trình này.

1. Lấy mã truy cập và mã làm mới bằng API /token. Xin lưu ý rằng loại cấp là 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 này trả về một mã truy cập và một mã làm mới. Phản hồi có dạng như sau:

   {
       "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. Giờ đây, bạn có thể sử dụng mã làm mới để lấy mã truy cập mới bằng cách gọi điểm cuối /refresh của cùng một API. Ví dụ:

   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 này trả về một mã truy cập mới. Phản hồi sẽ có dạng như sau:

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

Giám sát vĩnh viễn

Forever là một công cụ Node.js tự động khởi động lại ứng dụng Node.js trong trường hợp quy trình bị lỗi hoặc gặp lỗi. Edge Microgateway có một tệp forever.json mà bạn có thể định cấu hình để kiểm soát số lần và khoảng thời gian Edge Microgateway cần khởi động lại. Tệp này định cấu hình một dịch vụ Forever có tên là forever-monitor, giúp quản lý Forever theo cách có lập trình.

Bạn có thể tìm thấy tệp forever.json trong thư mục cài đặt gốc của Edge Microgateway. Xem phần Edge Microgateway được cài đặt ở đâu. Để biết thông tin chi tiết về các lựa chọn cấu hình, hãy tham khảo tài liệu về forever-monitor.

Lệnh edgemicro forever bao gồm các cờ cho phép bạn chỉ định vị trí của tệp forever.json (cờ -f) và bắt đầu/dừng quy trình giám sát Forever (cờ -a). Ví dụ:

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

Để biết thêm thông tin, hãy xem phần Giám sát vĩnh viễn trong tài liệu tham khảo về CLI.

Chỉ định một điểm cuối của tệp cấu hình

Nếu chạy nhiều phiên bản Edge Microgateway, bạn có thể muốn quản lý cấu hình của các phiên bản đó ở một vị trí duy nhất. Bạn có thể thực hiện việc này bằng cách chỉ định một điểm cuối HTTP mà Edge Micro có thể tải tệp cấu hình xuống. Bạn có thể chỉ định điểm cuối này khi khởi động Edge Micro bằng cờ -u.

Ví dụ:

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

trong đó điểm cuối mgconfig trả về nội dung của tệp cấu hình. Đây là tệp theo mặc định nằm trong ~/.edgemicro và có quy ước đặt tên là org-env-config.yaml.

Tắt tính năng lưu vào bộ nhớ đệm dữ liệu kết nối TCP

Bạn có thể sử dụng thuộc tính cấu hình nodelay để tắt tính năng lưu vào bộ nhớ đệm dữ liệu cho các kết nối TCP mà Edge Microgateway sử dụng.

Theo mặc định, các kết nối TCP sử dụng thuật toán Nagle để lưu vào bộ nhớ đệm dữ liệu trước khi gửi đi. Việc đặt nodelay thành true sẽ tắt hành vi này (dữ liệu sẽ ngay lập tức kích hoạt dữ liệu mỗi khi socket.write() được gọi). Hãy xem thêm tài liệu về Node.js để biết thêm thông tin chi tiết.

Để bật nodelay, hãy chỉnh sửa tệp cấu hình Edge Micro như sau:

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

Chạy Edge Microgateway ở chế độ độc lập

Bạn có thể chạy Edge Microgateway mà không cần bất kỳ thành phần phụ thuộc nào của Apigee Edge. Trường hợp này (được gọi là chế độ độc lập) cho phép bạn chạy và kiểm thử Edge Microgateway mà không cần kết nối Internet.

Ở chế độ độc lập, các tính năng sau không hoạt động vì cần có kết nối với Apigee Edge:

• OAuth và khoá API
• Hạn mức
• Số liệu phân tích

Mặt khác, các trình bổ trợ tuỳ chỉnh và tính năng chống đột biến hoạt động bình thường vì chúng không yêu cầu kết nối với Apigee Edge. Ngoài ra, một trình bổ trợ mới có tên là extauth cho phép bạn uỷ quyền các lệnh gọi API đến cổng siêu nhỏ bằng JWT ở chế độ độc lập.

Định cấu hình và khởi động cổng

Cách chạy Edge Microgateway ở chế độ độc lập:

1. Tạo một tệp cấu hình có tên như sau: $HOME/.edgemicro/$ORG-$ENV-config.yaml

   Ví dụ:

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

2. Dán mã sau đây vào tệp:

   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

3. Xuất biến môi trường sau với giá trị "1":

   export EDGEMICRO_LOCAL=1

4. Thực thi lệnh start sau đây, trong đó bạn cung cấp các giá trị để khởi tạo proxy cục bộ:

   edgemicro start -o $ORG -e $ENV -a $LOCAL_PROXY_NAME \
     -v $LOCAL_PROXY_VERSION -t $TARGET_URL -b $BASE_PATH

   Trong trường hợp:

   • $ORG là tên "org" mà bạn đã dùng trong tên tệp cấu hình.
   • $ENV là tên "env" mà bạn đã dùng trong tên tệp cấu hình.
   • $LOCAL_PROXY_NAME là tên của proxy cục bộ sẽ được tạo. Bạn có thể sử dụng bất kỳ tên nào bạn muốn.
   • $LOCAL_PROXY_VERSION là số phiên bản của proxy.
   • $TARGET_URL là URL cho mục tiêu của proxy. (target là dịch vụ mà proxy gọi.)
   • $BASE_PATH là đường dẫn cơ sở của proxy. Giá trị này phải bắt đầu bằng dấu gạch chéo xuôi. Đối với đường dẫn cơ sở gốc, chỉ cần chỉ định dấu gạch chéo về phía trước; ví dụ: "/".

   Ví dụ:

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

5. Kiểm thử cấu hình.

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

   Vì trình bổ trợ extauth nằm trong tệp foo-bar-config.yaml, nên bạn sẽ gặp lỗi "missing_authorization". Trình bổ trợ này xác thực một JWT phải có trong tiêu đề Uỷ quyền của lệnh gọi API. Trong phần tiếp theo, bạn sẽ nhận được một JWT cho phép các lệnh gọi API diễn ra mà không gặp lỗi.

Ví dụ: Lấy mã uỷ quyền

Ví dụ sau đây cho thấy cách lấy JWT từ điểm cuối JWT của Edge Microgateway trên Apigee Edge (edgemicro-auth/jwkPublicKeys). Điểm cuối này được triển khai khi bạn thực hiện thiết lập và định cấu hình tiêu chuẩn cho Edge Microgateway. Để lấy JWT từ điểm cuối Apigee, trước tiên, bạn phải thiết lập Edge Microgateway tiêu chuẩn và kết nối với Internet. Điểm cuối Apigee chỉ được dùng ở đây cho mục đích minh hoạ và không bắt buộc. Bạn có thể sử dụng một điểm cuối mã thông báo JWT khác nếu muốn. Nếu có, bạn sẽ cần lấy JWT bằng API được cung cấp cho điểm cuối đó.

Các bước sau đây giải thích cách lấy mã thông báo bằng điểm cuối edgemicro-auth/jwkPublicKeys:.

1. Bạn phải thực hiện chế độ thiết lập và định cấu hình tiêu chuẩn của Edge Microgateway để triển khai proxy edgemicro-auth cho tổ chức/môi trường của bạn trên Apigee Edge. Nếu đã thực hiện bước này trước đây, bạn không cần lặp lại.
2. Nếu triển khai Edge Microgateway cho Apigee Cloud, bạn phải kết nối với Internet để có thể lấy JWT từ điểm cuối này.
3. Dừng Edge Microgateway:

   edgemicro stop

4. Trong tệp cấu hình mà bạn đã tạo trước đó ($HOME/.edgemicro/org-env-config.yaml), hãy trỏ thuộc tính extauth:publickey_url đến điểm cuối edgemicro-auth/jwkPublicKeys trong tổ chức/môi trường Apigee Edge của bạn. Ví dụ:

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

5. Khởi động lại Edge Microgateway như bạn đã làm trước đây, bằng cách sử dụng tên tổ chức/môi trường mà bạn đã dùng trong tên tệp cấu hình. Ví dụ:

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

6. Nhận mã thông báo JWT từ điểm cuối uỷ quyền. Vì đang sử dụng điểm cuối edgemicro-auth/jwkPublicKeys, bạn có thể dùng lệnh CLI này:

Bạn có thể tạo JWT cho Edge Microgateway bằng lệnh edgemicro token hoặc một API. Ví dụ:

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

Trong trường hợp:

• your_org là tên của tổ chức Apigee mà bạn đã định cấu hình Edge Microgateway trước đó.
• your_env là một môi trường trong tổ chức.
• Lựa chọn i chỉ định Khoá người dùng từ một ứng dụng của nhà phát triển có một sản phẩm bao gồm cả proxy edgemicro-auth.
• Lựa chọn s chỉ định Khoá bí mật của người dùng từ một ứng dụng nhà phát triển có một sản phẩm bao gồm proxy edgemicro-auth.

Lệnh này yêu cầu Apigee Edge tạo một JWT mà sau đó có thể dùng để xác minh các lệnh gọi API.

Kiểm thử cấu hình độc lập

Để kiểm thử cấu hình, hãy gọi API bằng mã thông báo được thêm vào tiêu đề Uỷ quyền như sau:

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

Ví dụ:

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

Ví dụ về đầu ra:

{
   "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":""
}

Sử dụng chế độ proxy cục bộ

Ở chế độ proxy cục bộ, Edge Microgateway không yêu cầu triển khai proxy có nhận biết microgateway trên Apigee Edge. Thay vào đó, bạn định cấu hình một "proxy cục bộ" bằng cách cung cấp tên proxy cục bộ, đường dẫn cơ sở và URL đích khi khởi động microgateway. Sau đó, các lệnh gọi API đến cổng siêu nhỏ sẽ được gửi đến URL mục tiêu của proxy cục bộ. Về mọi mặt khác, chế độ proxy cục bộ hoạt động giống hệt như khi chạy Edge Microgateway ở chế độ bình thường. Quy trình xác thực cũng tương tự, cũng như quy trình chặn đột biến và thực thi hạn mức, các trình bổ trợ tuỳ chỉnh, v.v.

Trường hợp sử dụng và ví dụ

Chế độ proxy cục bộ sẽ hữu ích khi bạn chỉ cần liên kết một proxy duy nhất với một phiên bản Edge Microgateway. Ví dụ: bạn có thể chèn Edge Microgateway vào Kubernetes dưới dạng một proxy phụ, trong đó mỗi microgateway và dịch vụ chạy trong một nhóm duy nhất, đồng thời microgateway quản lý lưu lượng truy cập đến và đi từ dịch vụ đi kèm. Hình sau đây minh hoạ cấu trúc này, trong đó Edge Microgateway hoạt động như một proxy phụ trong một cụm Kubernetes. Mỗi phiên bản microgateway chỉ giao tiếp với một điểm cuối duy nhất trên dịch vụ đồng hành:

Một lợi ích của kiểu kiến trúc này là Edge Microgateway cung cấp tính năng quản lý API cho từng dịch vụ được triển khai vào một môi trường vùng chứa, chẳng hạn như một cụm Kubernetes.

Định cấu hình chế độ proxy cục bộ

Để định cấu hình Edge Microgateway chạy ở chế độ proxy cục bộ, hãy làm theo các bước sau:

1. Chạy edgemicro init để thiết lập môi trường cấu hình cục bộ, giống hệt như khi bạn thiết lập Edge Microgateway thông thường. Xem thêm phần Định cấu hình Edge Microgateway.
2. Chạy edgemicro configure, như bạn vẫn làm trong quy trình thiết lập Edge Microgateway thông thường. Ví dụ:

   edgemicro configure -o your_org -e your_env -u your_apigee_username

   Lệnh này triển khai chính sách edgemicro-auth cho Edge và trả về một khoá và mã bí mật mà bạn sẽ cần để khởi động cổng siêu nhỏ. Nếu bạn cần trợ giúp, hãy xem phần Định cấu hình Edge Microgateway.

3. Trên Apigee Edge, hãy tạo một sản phẩm API và có các yêu cầu bắt buộc sau đây về cấu hình (bạn có thể quản lý tất cả các cấu hình khác theo ý muốn):
   • Bạn phải thêm proxy edgemicro-auth vào sản phẩm. Proxy này được triển khai tự động khi bạn chạy edgemicro configure.
   • Bạn phải cung cấp một đường dẫn tài nguyên. Apigee đề xuất thêm đường dẫn này vào sản phẩm: /**. Để tìm hiểu thêm, hãy xem phần Định cấu hình hành vi của đường dẫn tài nguyên. Xem thêm phần Tạo sản phẩm API trong tài liệu về Edge.

4. Trên Apigee Edge, hãy tạo một nhà phát triển hoặc bạn có thể sử dụng nhà phát triển hiện có nếu muốn. Để được trợ giúp, hãy xem phần Thêm nhà phát triển bằng giao diện người dùng quản lý Edge.

5. Trên Apigee Edge, hãy tạo một ứng dụng dành cho nhà phát triển. Bạn phải thêm sản phẩm API mà bạn vừa tạo vào ứng dụng. Để được trợ giúp, hãy xem phần Đăng ký ứng dụng trong giao diện người dùng quản lý Edge.
6. Trên máy cài đặt Edge Microgateway, hãy xuất biến môi trường sau đây với giá trị "1".

   export EDGEMICRO_LOCAL_PROXY=1

7. Thực thi lệnh start sau:

   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

   Trong trường hợp:

   • your_org là tổ chức Apigee của bạn.
   • your_environment là một môi trường trong tổ chức của bạn.
   • your_key là khoá được trả về khi bạn chạy edgemicro configure.
   • your_secret là khoá bí mật được trả về khi bạn chạy edgemicro configure.
   • local_proxy_name là tên của proxy cục bộ sẽ được tạo.
   • local_proxy_version là số phiên bản của proxy.
   • target_url là URL cho mục tiêu của proxy (dịch vụ mà proxy sẽ gọi).
   • base_path là đường dẫn cơ sở của proxy. Giá trị này phải bắt đầu bằng dấu gạch chéo xuôi. Đối với đường dẫn cơ sở gốc, chỉ cần chỉ định dấu gạch chéo về phía trước; ví dụ: "/".

   Ví dụ:

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

Kiểm thử cấu hình

Bạn có thể kiểm thử cấu hình proxy cục bộ bằng cách gọi điểm cuối proxy. Ví dụ: nếu chỉ định một basepath là /echo, bạn có thể gọi proxy như sau:

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

Lệnh gọi API ban đầu này đã tạo ra lỗi vì bạn không cung cấp khoá API hợp lệ. Bạn có thể tìm thấy khoá này trong ứng dụng Developer mà bạn đã tạo trước đó. Mở ứng dụng trong giao diện người dùng Edge, sao chép Khoá người dùng và sử dụng khoá đó như sau:

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

Ví dụ:

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

Ví dụ về đầu ra:

{
  "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":""
}

Sử dụng bộ đồng bộ hoá

Phần này giải thích cách sử dụng bộ đồng bộ hoá, một tính năng không bắt buộc giúp cải thiện khả năng phục hồi của Edge Microgateway bằng cách cho phép bộ đồng bộ hoá truy xuất dữ liệu cấu hình từ Apigee Edge và ghi dữ liệu đó vào cơ sở dữ liệu Redis cục bộ. Khi một thực thể bộ đồng bộ hoá đang chạy, các thực thể Edge Microgateway khác đang chạy trên các nút khác nhau có thể truy xuất cấu hình của chúng trực tiếp từ cơ sở dữ liệu này.

Tính năng đồng bộ hoá hiện được hỗ trợ để hoạt động với Redis 5.0.x.

Bộ đồng bộ hoá là gì?

Trình đồng bộ hoá cung cấp một mức độ đàn hồi cho Edge Microgateway. Thao tác này giúp đảm bảo rằng mọi phiên bản của Edge Microgateway đều sử dụng cùng một cấu hình và trong trường hợp xảy ra sự cố về Internet, các phiên bản Edge Microgateway có thể khởi động và chạy đúng cách.

Theo mặc định, các phiên bản Edge Microgateway phải có thể giao tiếp với Apigee Edge để truy xuất và làm mới dữ liệu cấu hình của chúng, chẳng hạn như cấu hình API proxy và API sản phẩm. Nếu kết nối Internet với Edge bị gián đoạn, các phiên bản microgateway vẫn có thể hoạt động vì dữ liệu cấu hình mới nhất được lưu vào bộ nhớ đệm. Tuy nhiên, các phiên bản microgateway mới không thể khởi động nếu không có kết nối rõ ràng. Ngoài ra, sự cố về Internet có thể khiến một hoặc nhiều phiên bản microgateway chạy với thông tin cấu hình không đồng bộ với các phiên bản khác.

Trình đồng bộ hoá Edge Microgateway cung cấp một cơ chế thay thế cho các phiên bản Edge Microgateway để truy xuất dữ liệu cấu hình mà chúng cần để khởi động và xử lý lưu lượng truy cập của API proxy. Trình đồng bộ hoá giúp tất cả các phiên bản Edge Microgateway chạy trên các nút khác nhau khởi động đúng cách và luôn đồng bộ hoá ngay cả khi kết nối Internet giữa Edge Microgateway và Apigee Edge bị gián đoạn.

Trình đồng bộ hoá là một phiên bản được định cấu hình đặc biệt của Edge Microgateway. Mục đích duy nhất của nó là thăm dò Apigee Edge (bạn có thể định cấu hình thời gian), truy xuất dữ liệu cấu hình và ghi dữ liệu đó vào cơ sở dữ liệu Redis cục bộ. Bản thân phiên bản bộ đồng bộ hoá không thể xử lý lưu lượng truy cập của proxy API. Bạn có thể định cấu hình các phiên bản khác của Edge Microgateway đang chạy trên các nút khác nhau để truy xuất dữ liệu cấu hình từ cơ sở dữ liệu Redis thay vì từ Apigee Edge. Vì tất cả các phiên bản microgateway đều lấy dữ liệu cấu hình từ cơ sở dữ liệu cục bộ, nên chúng có thể khởi động và xử lý các yêu cầu API ngay cả khi Internet bị gián đoạn.

Định cấu hình một thực thể bộ đồng bộ hoá

Thêm cấu hình sau vào tệp org-env/config.yaml cho bản cài đặt Edge Microgateway mà bạn muốn dùng làm bộ đồng bộ hoá:

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

Ví dụ:

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

Cuối cùng, hãy lưu tệp cấu hình và khởi động phiên bản Edge Microgateway. Thao tác này sẽ bắt đầu thăm dò Apigee Edge và lưu trữ dữ liệu cấu hình đã tải xuống trong cơ sở dữ liệu Redis.

Định cấu hình các phiên bản Edge Microgateway thông thường

Khi bộ đồng bộ hoá đang chạy, bạn có thể định cấu hình các nút Edge Microgateway bổ sung để chạy các phiên bản microgateway thông thường xử lý lưu lượng truy cập proxy API. Tuy nhiên, bạn định cấu hình các phiên bản này để lấy dữ liệu cấu hình từ cơ sở dữ liệu Redis thay vì từ Apigee Edge.

Thêm cấu hình sau vào tệp org-env/config.yaml của từng nút Edge Microgateway bổ sung. Xin lưu ý rằng thuộc tính synchronizerMode được đặt thành 0. Thuộc tính này đặt thực thể hoạt động như một thực thể Edge Microgateway thông thường xử lý lưu lượng truy cập của API proxy và thực thể sẽ lấy dữ liệu cấu hình từ cơ sở dữ liệu Redis.

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

Ví dụ:

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

Thuộc tính cấu hình

Các thuộc tính cấu hình sau đã được thêm để hỗ trợ việc sử dụng bộ đồng bộ hoá: