Edge Microgateway 的作業和設定參考資料

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

Edge Microgateway 2.5.x 版

本主題說明如何管理及設定 Edge Microgateway。

在連上網際網路連線的情況下升級 Edge Microgateway

  1. 執行下列 npm 指令，升級至最新版本 Edge Microgateway：
    npm upgrade edgemicro -g

    如要升級至特定版本的 Edge Microgateway，您必須在升級指令中指定版本號碼。如未指定版本號碼，系統會安裝最新版本。舉例來說，如要升級至 2.5.26 版，請使用下列指令：

    npm upgrade edgemicro@2.5.26 -g
  2. 查看版本號碼。舉例來說，如果您安裝的是 2.5.26 版：
    edgemicro --version
current nodejs version is v8.9.0
current edgemicro version is 2.5.26
  3. 最後，請升級至最新版本的 edgemicro-auth Proxy： 
    edgemicro upgradeauth -o org_name -e env_name -u username

變更設定

您需要瞭解的設定檔包括：

  • 預設系統設定檔
  • 新初始化 Edge Microgateway 執行個體的預設設定檔
  • 執行個體的動態設定檔

本節將討論這些檔案，以及變更這些檔案時需要瞭解的事項。

預設系統設定檔

安裝 Edge Microgateway 時，預設系統設定檔會放在以下位置：

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

其中 prefix 是 npm 前置字元目錄。如果找不到這個目錄，請參閱「Edge Microgateway 的安裝位置」。

如果變更系統設定檔，必須重新初始化、重新設定及重新啟動 Edge Microgateway：

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

新初始化 Edge Microgateway 執行個體的預設設定檔

執行 edgemicro init 時，系統設定檔 (如上所述) default.yaml 會放在 ~/.edgemicro 目錄中。

如果您變更 ~/.edgemicro 中的設定檔，則必須重新設定並重新啟動 Edge Microgateway：

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

執行個體的動態設定檔

執行 edgemicro configure [params] 時，系統會在 ~/.edgemicro 中建立動態設定檔。檔案會依據以下模式命名：org-env-config.yaml，其中 org 和 env 是您的 Apigee Edge 組織和環境名稱。您可以使用這個檔案變更設定，然後重新載入設定，完全不會造成停機。舉例來說，如果您新增並設定外掛程式，可以重新載入設定，而不會造成任何停機時間，如下所述。

如果 Edge Microgateway 正在執行 (零停機時間選項)：

  1. 重新載入 Edge Microgateway 設定： 
    edgemicro reload -o org_name -e env_name -k key -s secret

    其中：

    • org_name 是您的 Edge 組織名稱 (您必須是組織管理員)。
    • env_name 是貴組織中的環境 (例如「test」或「prod」)。
    • key 是 configure 指令先前傳回的金鑰。
    • secret 是 configure 指令先前傳回的金鑰。

    例如

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

如果 Edge Microgateway 已停止：

  1. 重新啟動 Edge Microgateway： 
    edgemicro start -o org_name -e env_name -k key -s secret

    其中：

    • org_name 是您的 Edge 組織名稱 (您必須是組織管理員)。
    • env_name 是貴組織中的環境 (例如「測試」或「正式環境」)。
    • key 是 configure 指令先前傳回的金鑰。
    • secret 是 configure 指令先前傳回的金鑰。

    例如：

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

以下是設定檔範例。如要進一步瞭解設定檔設定，請參閱「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

設定環境變數

需要 Edge 組織和環境值的指令列介面指令，以及啟動 Edge Microgateway 所需的金鑰和密鑰，可以儲存在下列環境變數中：

  • EDGEMICRO_ORG
  • EDGEMICRO_ENV
  • EDGEMICRO_KEY
  • EDGEMICRO_SECRET

您可以選擇是否設定這些變數。設定這些變數後，使用指令列介面 (CLI) 設定及啟動 Edge Microgateway 時，就不必指定這些變數的值。

在 Edge Microgateway 伺服器上設定 SSL

您可以將 Microgateway 伺服器設為使用 SSL。舉例來說，設定 SSL 後，您可以使用「https」通訊協定透過 Edge Microgateway 呼叫 API，如下所示：

https://localhost:8000/myapi

如要在 Microgateway 伺服器上設定 SSL，請按照下列步驟操作：

  1. 使用 openssl 公用程式或您偏好的方法，產生或取得 SSL 憑證和金鑰。
  2. 在 Edge Microgateway 設定檔中加入 edgemicro:ssl 屬性。如需完整選項清單，請參閱下表。例如：
    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. 重新啟動 Edge Microgateway。根據您編輯的設定檔 (預設檔案或執行階段設定檔)，按照「變更設定」一節所述的步驟操作。

以下是設定檔中 edgemicro 區段的範例，其中已設定 SSL：

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

以下是所有支援的伺服器選項清單：

選項 說明
key ca.key 檔案的路徑 (PEM 格式)。
cert ca.cert 檔案的路徑 (PEM 格式)。
pfx pfx 檔案的路徑，其中包含 PFX 格式的用戶端私密金鑰、憑證和 CA 憑證。
passphrase 包含私密金鑰或 PFX 通關密語的字串。
ca 檔案路徑，內含 PEM 格式的信任憑證清單。
ciphers 描述要使用的加密編譯字串，以「:」分隔。
rejectUnauthorized 如果設為 true，系統會根據提供的 CA 清單驗證伺服器憑證。如果驗證失敗，系統會傳回錯誤。
secureProtocol 要使用的 SSL 方法。例如 SSLv3_method，強制將 SSL 設為第 3 版。
servername SNI (伺服器名稱指示) TLS 擴充功能的伺服器名稱。
requestCert true 代表雙向 SSL；false 代表單向 SSL

使用用戶端 SSL/TLS 選項

您可以將 Edge Microgateway 設為 TLS 或 SSL 用戶端，以便連線至目標端點。在 Microgateway 設定檔中，使用 targets 元素設定 SSL/TLS 選項。

以下範例提供的設定會套用至所有主機：

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

在這個範例中，設定只會套用至指定的主機：

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

以下是 TLS 的範例：

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

以下是所有支援的用戶端選項清單：

選項 說明
pfx pfx 檔案的路徑，其中包含 PFX 格式的用戶端私密金鑰、憑證和 CA 憑證。
key ca.key 檔案的路徑 (PEM 格式)。
passphrase 包含私密金鑰或 PFX 通關密語的字串。
cert ca.cert 檔案的路徑 (PEM 格式)。
ca 檔案路徑，內含 PEM 格式的信任憑證清單。
ciphers 描述要使用的加密編譯字串，以「:」分隔。
rejectUnauthorized 如果設為 true，系統會根據提供的 CA 清單驗證伺服器憑證。如果驗證失敗，系統會傳回錯誤。
secureProtocol 要使用的 SSL 方法。例如 SSLv3_method，強制將 SSL 設為第 3 版。
servername SNI (伺服器名稱指示) TLS 擴充功能的伺服器名稱。

自訂 edgemicro-auth Proxy

根據預設，Edge Microgateway 會使用部署在 Apigee Edge 上的 Proxy 進行 OAuth2 驗證。初次執行 edgemicro configure 時，系統會部署這個 Proxy。您可以變更這個 Proxy 的預設設定，為 JSON Web Token (JWT) 新增自訂宣告支援、設定權杖到期時間，以及產生更新權杖。詳情請參閱 GitHub 的 edgemicro-auth 頁面。

使用自訂驗證服務

根據預設，Edge Microgateway 會使用部署在 Apigee Edge 上的 Proxy 進行 OAuth2 驗證。初次執行 edgemicro configure 時，系統會部署這個 Proxy。根據預設，這個 Proxy 的網址會在 Edge Microgateway 設定檔中指定，如下所示：

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

如要使用自己的自訂服務處理驗證，請變更設定檔中的 authUri 值，指向您的服務。舉例來說，您可能有一項服務使用 LDAP 驗證身分。

管理記錄檔

Edge Microgateway 會記錄每個要求和回應的相關資訊。記錄檔提供實用的偵錯和疑難排解資訊。

記錄檔的儲存位置

根據預設，記錄檔會儲存在 /var/tmp。

如何變更預設記錄檔目錄

記錄檔的儲存目錄是在 Edge Microgateway 設定檔中指定。另請參閱「變更設定」。

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

變更 dir 值，指定其他記錄檔目錄。

將記錄傳送至控制台

您可以設定記錄功能，將記錄資訊傳送至標準輸出內容，而非記錄檔。將 to_console 旗標設為 true，如下所示：

edgemicro:
  logging:
    to_console: true

這項設定會將記錄傳送至標準輸出。目前無法同時將記錄傳送至 stdout 和記錄檔。

如何設定記錄層級

您可以設定下列記錄層級：info、warn 和 error。建議選用「資訊」等級。記錄所有 API 要求和回應，這是預設選項。

如何變更記錄間隔

您可以在 Edge Microgateway 設定檔中設定這些間隔。另請參閱「變更設定」。

可設定的屬性如下：

  • stats_log_interval：(預設：60) 統計資料記錄寫入 API 記錄檔的時間間隔，以秒為單位。
  • rotate_interval：(預設：24) 記錄檔輪替間隔，以小時為單位。例如：
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

記錄檔維護最佳做法

記錄檔資料會隨著時間累積，因此 Apigee 建議您採取下列做法：

  • 記錄檔可能會變得相當大，因此請務必確保記錄檔目錄有足夠的空間。請參閱「記錄檔儲存位置」和「如何變更預設記錄檔目錄」兩節。
  • 每週至少刪除或移動記錄檔至獨立的封存目錄一次。
  • 如果您的政策是刪除記錄，可以使用 CLI 指令 edgemicro log -c 移除 (清除) 舊記錄。

記錄檔命名慣例

每個 Edge Microgateway 執行個體都會產生三種記錄檔：

  • api：記錄所有通過 Edge Microgateway 的要求和回應。API 計數器 (統計資料) 和錯誤也會記錄到這個檔案。
  • err：記錄傳送至 stderr 的所有內容。
  • out：記錄傳送至 stdout 的所有內容。

命名慣例如下：

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

例如：

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

關於記錄檔內容

新增版本：2.3.3

根據預設，記錄服務會省略下載的 Proxy、產品和 JSON Web Token (JWT) 的 JSON。如要將這些物件輸出至記錄檔，請在啟動 Edge Microgateway 時設定 DEBUG=*。例如：

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

「api」記錄檔的內容

「api」記錄檔包含透過 Edge Microgateway 傳送的要求和回應流程詳細資訊。「api」記錄檔的命名方式如下：

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

對於向 Edge Microgateway 提出的每項要求，「api」記錄檔會擷取四個事件：

  • 來自用戶端的傳入要求
  • 向目標發出傳出要求
  • 來自目標的傳入回應
  • 傳送給用戶端的回應

每個獨立項目都會以簡短標記表示，讓記錄檔更精簡。以下是四個範例項目，分別代表四個事件。在記錄檔中，這些行看起來像這樣 (行號僅供文件內參照用，不會顯示在記錄檔中)。

(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

以下逐一介紹：

1. 用戶端傳入要求範例：

1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
  • 1436403888651 - Unix 日期戳記
  • info：視情境而定。可以是資訊、警告或錯誤，具體取決於記錄層級。可以是統計資料記錄的 stats、警告的 warn 或錯誤的 error。
  • req：用於識別事件。在本例中，是來自用戶端的要求。
  • m：要求中使用的 HTTP 動詞。
  • u：網址中基本路徑後方的部分。
  • h：Edge Microgateway 監聽的主機和通訊埠號碼。
  • r：用戶端要求來源的遠端主機和通訊埠。
  • i：要求 ID。這四個事件項目都會共用這個 ID。每項要求都會指派專屬的要求 ID。依要求 ID 建立記錄檔記錄的關聯，可深入瞭解目標的延遲時間。
  • d：Edge Microgateway 收到要求後經過的時間長度 (以毫秒為單位)。在上述範例中，系統在 7 毫秒後收到目標對要求 0 的回應 (第 3 行)，並在 4 毫秒後將回應傳送給用戶端 (第 4 行)。換句話說，總要求延遲時間為 11 毫秒，其中 7 毫秒由目標耗用，4 毫秒由 Edge Microgateway 本身耗用。

2. 傳送至目標的傳出要求範例：

1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0
  • 1436403888651 - Unix 日期戳記
  • info：視情境而定。可以是資訊、警告或錯誤，具體取決於記錄層級。可以是統計資料記錄的 stats、警告的 warn 或錯誤的 error。
  • treq：用於識別事件。在這個案例中，目標是要求。
  • m：目標要求中使用的 HTTP 動詞。
  • u：網址中基本路徑後方的部分。
  • h：後端目標的主機和通訊埠號碼。
  • i：記錄項目的 ID。這四個事件項目都會共用這個 ID。

3. 來自目標的傳入回應範例

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

1436403888651 - Unix 日期戳記

  • info：視情境而定。可以是資訊、警告或錯誤，具體取決於記錄層級。可以是統計資料記錄的 stats、警告的 warn 或錯誤的 error。
  • tres：識別事件。在這個例子中，目標是回應。
  • s：HTTP 回應狀態。
  • d：時間長度 (以毫秒為單位)。目標呼叫 API 所需的時間。
  • i：記錄項目的 ID。這四個事件項目都會共用這個 ID。

4. 傳送給用戶端的回應範例

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

1436403888651 - Unix 日期戳記

  • info：視情境而定。可以是資訊、警告或錯誤，具體取決於記錄層級。可以是統計資料記錄的 stats、警告的 warn 或錯誤的 error。
  • res：識別事件。在這種情況下，請回應用戶端。
  • s：HTTP 回應狀態。
  • d：時間長度 (以毫秒為單位)。這是 API 呼叫所花費的總時間，包括目標 API 所花費的時間，以及 Edge Microgateway 本身所花費的時間。
  • i：記錄項目的 ID。這四個事件項目都會共用這個 ID。

記錄檔排程

記錄檔會按照 rotate_interval 設定屬性指定的時間間隔輪替。系統會持續將項目新增至同一個記錄檔，直到輪替間隔到期為止。不過，每次重新啟動 Edge Microgateway 時，都會收到新的 UID，並建立一組含有這個 UID 的新記錄檔。另請參閱「記錄檔維護最佳做法」。

錯誤訊息

部分記錄項目會包含錯誤訊息。如要找出錯誤發生的位置和原因，請參閱 Edge Microgateway 錯誤參考資料。

Edge Microgateway 設定參考資料

設定檔的位置

本節說明的設定屬性位於 Edge Microgateway 設定檔中。另請參閱「變更設定」。

edge_config 屬性

這些設定用於設定 Edge Microgateway 執行個體與 Apigee Edge 之間的互動。

  • bootstrap：(預設：無) 指向 Apigee Edge 上執行的 Edge Microgateway 專屬服務的網址。Edge Microgateway 會使用這項服務與 Apigee Edge 通訊。執行指令產生公開/私密金鑰組時，系統會傳回這個網址：edgemicro genkeys。詳情請參閱「設定 Edge Microgateway」。
  • jwt_public_key：(預設：無) 指向部署於 Apigee Edge 的 Edge Microgateway Proxy 的網址。這個 Proxy 是驗證端點，可向用戶端核發已簽署的存取權杖。執行指令部署 Proxy 時，系統會傳回這個網址：edgemicro configure。詳情請參閱「設定 Edge Microgateway」。

edgemicro 屬性

這些設定會設定 Edge Microgateway 程序。

  • port：(預設：8000) Edge Microgateway 程序監聽的通訊埠編號。
  • max_connections：(預設值：-1) 指定 Edge Microgateway 可接收的傳入連線數量上限。如果超過這個數量，系統會傳回下列狀態：

    res.statusCode = 429; // Too many requests
  • max_connections_hard：(預設值：-1) Edge Microgateway 在關閉連線前可接收的並行要求數量上限。這項設定旨在防範阻斷服務攻擊。通常會設為大於 max_connections 的數字。
  • logging：
    • level：(預設：error)
      • info：記錄所有流經 Edge Microgateway 執行個體的要求和回應。
      • warn：僅記錄警告訊息。
      • error：僅記錄錯誤訊息。
    • dir：(預設：/var/tmp) 儲存記錄檔的目錄。
    • stats_log_interval：(預設：60) 統計資料記錄寫入 API 記錄檔的時間間隔，以秒為單位。
    • rotate_interval：(預設：24) 記錄檔輪替間隔，以小時為單位。
  • plugins：外掛程式可為 Edge Microgateway 新增功能。如要進一步瞭解如何開發外掛程式，請參閱「開發自訂外掛程式」。
  • dir：從 ./gateway 目錄到 ./plugins 目錄的相對路徑，或絕對路徑。
  • sequence：要新增至 Edge Microgateway 執行個體的外掛程式模組清單。模組會按照這裡指定的順序執行。
  • debug：在 Edge Microgateway 程序中新增遠端偵錯功能。
    • port：要監聽的通訊埠編號。例如，將 IDE 偵錯工具設為監聽這個通訊埠。
    • args：偵錯程序的引數。例如：args --nolazy
  • config_change_poll_interval: (預設：600 秒) Edge Microgateway 會定期載入新設定，並在有任何變更時執行重新載入。輪詢會擷取 Edge 上的任何變更 (產品、Microgateway 感知 Proxy 等變更)，以及本機設定檔的變更。
  • disable_config_poll_interval: (預設：false) 設為 true 即可關閉自動變更輪詢。
  • request_timeout：設定目標要求的逾時時間。逾時時間以秒為單位。如果發生逾時，Edge Microgateway 會傳回 504 狀態碼。(2.4.x 版新增)

headers 屬性

這些設定可決定特定 HTTP 標頭的處理方式。

  • x-forwarded-for：(預設值：true) 設為 false，防止 x-forwarded-for 標頭傳遞至目標。請注意，如果要求中含有 x-forwarded-for 標頭，其值會設為 Edge Analytics 中的 client-ip 值。
  • x-forwarded-host：(預設：true) 設為 false，防止 x-forwarded-host 標頭傳遞至目標。
  • x-request-id：(預設：true) 設為 false，可防止 x-request-id 標頭傳遞至目標。
  • x-response-time：(預設：true) 設為 false，可防止 x-response-time 標頭傳遞至目標。
  • via：(預設值：true) 設為 false，可防止透過標頭傳遞至目標。

oauth 屬性

這些設定可設定 Edge Microgateway 強制執行用戶端驗證的方式。

  • allowNoAuthorization：(預設：false) 如果設為 true，API 呼叫就能在沒有任何授權標頭的情況下通過 Edge Microgateway。如果設為 false，則必須提供授權標頭 (預設)。
  • allowInvalidAuthorization：(預設值：false) 如果設為 true，即使授權標頭中傳遞的權杖無效或已過期，系統仍會允許 API 呼叫通過。如要要求有效權杖，請將這個值設為 false (預設)。
  • authorization-header：(預設：Authorization: Bearer) 用於將存取權杖傳送至 Edge Microgateway 的標頭。如果目標需要將授權標頭用於其他用途，建議您變更預設值。
  • api-key-header：(預設：x-api-key) 用於將 API 金鑰傳遞至 Edge Microgateway 的標頭或查詢參數名稱。另請參閱「使用 API 金鑰」。
  • keep-authorization-header：(預設值：false) 如果設為 true，要求中傳送的授權標頭會傳遞至目標 (保留)。
  • allowOAuthOnly：如果設為 true，每個 API 都必須包含含有 Bearer 存取權杖的授權標頭。允許您只允許 OAuth 安全性模型 (同時維持回溯相容性)。(2.4.x 版新增)
  • allowAPIKeyOnly：如果設為 true，每個 API 都必須包含 x-api-key 標頭 (或自訂位置) 和 API 金鑰。可讓您僅允許 API 金鑰安全性模型 (同時維持回溯相容性)。(2.4.x 新增)
  • gracePeriod：這個參數有助於避免因系統時鐘與 JWT 授權權杖中指定的「不早於」(nbf) 或「核發時間」(iat) 時間略有差異而導致錯誤。請將這個參數設為允許這類差異的秒數。(2.5.7 版新增)

外掛程式專屬屬性

如要進一步瞭解各外掛程式的可設定屬性，請參閱「使用外掛程式」。

篩選 Proxy

您可以篩選 Edge Microgateway 執行個體要處理哪些支援 Microgateway 的 Proxy。Edge Microgateway 啟動時，會下載相關聯組織中所有可辨識 Microgateway 的 Proxy。請使用下列設定，限制微型閘道會處理哪些 Proxy。舉例來說，這項設定會將 Microgateway 處理的 Proxy 數量限制為三個：edgemicro_proxy-1、edgemicro_proxy-2 和 edgemicro_proxy-3：

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

設定數據分析推送頻率

使用這些設定參數，控制 Edge Microgateway 將數據分析資料傳送至 Apigee 的頻率：

  • bufferSize (選用)：緩衝區可容納的數據分析記錄數量上限，超過上限後，系統會開始捨棄最舊的記錄。預設：10000
  • batchSize (選用)：傳送至 Apigee 的數據分析記錄批次大小上限。預設：500
  • flushInterval (選用)：每次清除傳送至 Apigee 的一批數據分析記錄之間的時間間隔 (以毫秒為單位)。預設：5000

例如：

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

遮蓋數據分析資料

下列設定可防止要求路徑資訊顯示在 Edge 數據分析中。在 Microgateway 設定中新增下列內容，遮蓋要求 URI 和/或要求路徑。請注意，URI 是由要求的主機名稱和路徑部分組成。

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

在 Edge Analytics 中區隔 API 呼叫

您可以設定數據分析外掛程式，區隔特定 API 路徑，使其在 Edge Analytics 資訊主頁中顯示為獨立 Proxy。舉例來說，您可以在資訊主頁中區隔健康狀態檢查 API，以免與實際的 API Proxy 呼叫混淆。在 Analytics 資訊主頁中，隔離的 Proxy 會遵循下列命名模式：

edgemicro_proxyname-health

下圖顯示 Analytics 資訊主頁中的兩個獨立 Proxy：edgemicro_hello-health 和 edgemicro_mock-health：

使用這些參數，在 Analytics 資訊主頁中將相對路徑和絕對路徑區隔為不同的 Proxy：

  • relativePath (選用)：指定要在 Analytics 資訊主頁中區隔的相對路徑。舉例來說，如果您指定 /healthcheck，所有包含路徑 /healthcheck 的 API 呼叫都會在資訊主頁中顯示為 edgemicro_proxyname-health。請注意，這個旗標會忽略 Proxy 基本路徑。 如要根據完整路徑 (包括基本路徑) 區隔，請使用 proxyPath 旗標。
  • proxyPath (選用)：指定完整的 API Proxy 路徑 (包括 Proxy 基本路徑)，以便在數據分析資訊主頁中區隔。舉例來說，如果您指定 /mocktarget/healthcheck (其中 /mocktarget 是 Proxy 基本路徑)，則所有路徑為 /mocktarget/healthcheck 的 API 呼叫都會在資訊主頁中顯示為 edgemicro_proxyname-health。

舉例來說，在下列設定中，任何包含 /healthcheck 的 API 路徑都會由數據分析外掛程式分隔。也就是說，/foo/healthcheck 和 /foo/bar/healthcheck 會在數據分析資訊主頁中，分隔為名為 edgemicro_proxyname-health 的獨立 Proxy。

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

在下列設定中，任何 Proxy 路徑為 /mocktarget/healthcheck 的 API，都會在數據分析資訊主頁中，隔離為名為 edgemicro_proxyname-health 的獨立 Proxy。

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

在公司防火牆後方設定 Edge Microgateway

支援 v2.4.x

如果 Edge Microgateway 安裝在防火牆後方，閘道可能無法與 Apigee Edge 通訊。在這種情況下，您可以考慮兩種做法：

選項 1：

第一個選項是在 microgateway 設定檔中，將 edgemicro: proxy_tunnel 選項設為 true：

edge_config:

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

如果 proxy_tunnel 為 true，Edge Microgateway 會使用 HTTP CONNECT 方法，透過單一 TCP 連線建立 HTTP 要求通道。(如果用於設定 Proxy 的環境變數已啟用 TLS，也適用相同情況)。

選項 2：

第二個選項是在 Microgateway 設定檔中指定 Proxy，並將 proxy_tunnel 設為 false。例如：

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

在這種情況下，您可以設定下列變數，控制要使用的每個 HTTP Proxy 的主機，或不應處理 Edge Microgateway Proxy 的主機：HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY。

您可以將 NO_PROXY 設為以半形逗號分隔的網域清單，Edge Microgateway 不應將這些網域設為 Proxy。例如：

export NO_PROXY='localhost,localhost:8080'

將 HTTP_PROXY 和 HTTPS_PROXY 設為 HTTP Proxy 端點，Edge Microgateway 即可傳送訊息至該端點。例如：

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

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

如要進一步瞭解這些變數，請參閱 https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables

另請參閱

如何在公司防火牆後方設定 Edge Microgateway (Apigee 社群)。

在 Microgateway 感知 Proxy 中使用萬用字元

您可以在 edgemicro_* (Microgateway 感知) Proxy 的基本路徑中，使用一或多個「*」萬用字元。舉例來說，如果基本路徑為 /team/*/members，用戶端就能呼叫 https://[host]/team/blue/members 和 https://[host]/team/green/members，您不必建立新的 API Proxy 來支援新團隊。請注意，不支援 /**/。

重要事項：Apigee 不支援使用萬用字元「*」做為基本路徑的第一個元素。舉例來說，系統不支援 /*/ 搜尋。

輪替 JWT 金鑰

在您初次產生 JWT 後，可能需要變更儲存在 Edge 加密 KVM 中的公開/私密金鑰組。產生新金鑰組的程序稱為金鑰輪替。

Edge Microgateway 如何使用 JWT

JSON Web Token (JWT) 是 RFC7519 中所述的權杖標準。JWT 可用來簽署一組憑證附加資訊，JWT 接收者可以可靠地驗證這些資訊。

Edge Microgateway 使用 JWT 做為 OAuth 安全性的不記名權杖。為 Edge Microgateway 產生 OAuth 權杖時，您會收到 JWT。接著，您可以在 API 呼叫的授權標頭中使用 JWT。例如：

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

產生新的 JWT

您可以使用 edgemicro token 指令或 API，為 Edge Microgateway 產生 JWT。例如：

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

這項指令會要求 Apigee Edge 產生 JWT，以便用於驗證 API 呼叫。-i 和 -s 參數是 Apigee Edge 組織中開發人員應用程式的消費者 ID 和密鑰值。

或者，您也可以使用 Management API 產生 JWT：

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

其中：

  • org 是 Edge 組織名稱 (您必須是組織管理員)。
  • env 是貴組織中的環境 (例如「test」或「prod」)。
  • client_id 是您先前建立的開發人員應用程式中的消費者 ID。
  • client_secret 是您先前建立的開發人員應用程式中的消費者密鑰。

什麼是金鑰輪替？

在您初次產生 JWT 後，可能需要變更儲存在 Edge 加密 KVM 中的公開/私密金鑰組。產生新金鑰組的程序稱為金鑰輪替。輪替金鑰時，系統會產生新的私密/公開金鑰組，並儲存在 Apigee Edge 組織/環境中的「microgateway」KVM。此外，舊的公開金鑰會與原始金鑰 ID 值一併保留。

Edge 會使用儲存在加密 KVM 中的資訊來產生 JWT。在您初次設定 Edge Microgateway 時，系統會建立名為 microgateway 的 KVM，並填入金鑰。KVM 中的金鑰用於簽署及加密 JWT。

KVM 鍵包括：

  • private_key：用於簽署 JWT 的最新 (最近建立) RSA 私密金鑰。

  • public_key：最新 (最近建立) 的憑證，用於驗證以 private_key 簽署的 JWT。

  • private_key_kid：最新 (最近建立) 的私密金鑰 ID。這個金鑰 ID 與 private_key 值相關聯，用於支援金鑰輪替。

  • public_key1_kid：最新 (最近建立) 的公開金鑰 ID。這個金鑰與 public_key1 值相關聯，用於支援金鑰輪替。這個值與私密金鑰 kid 相同。

  • public_key1：最新 (最近建立) 的公開金鑰。

執行金鑰輪替時，對應中的現有金鑰值會遭到替換，並新增金鑰來保留舊的公開金鑰。例如：

  • public_key2_kid：舊公開金鑰 ID。這個金鑰與 public_key2 值相關聯，用於支援金鑰輪替。

  • public_key2：舊的公開金鑰。

系統會使用新的公開金鑰驗證 JWT。如果驗證失敗，系統會使用舊的公開金鑰，直到金鑰過期 (30 分鐘後)。這樣一來，您就能「輪替」金鑰，而不會立即中斷 API 流量。

如何輪替金鑰

本節說明如何執行金鑰輪替。

如果您在 2.5.2 版之前設定 Edge Microgateway 執行個體

如果您在 2.5.2 版之前設定 Edge Microgateway 執行個體，則必須執行下列兩項指令，升級 KVM 和驗證政策：

upgradekvm -o org -e env -u username

如要進一步瞭解這個指令，請參閱「升級 KVM」。

下一個指令會升級 edgemicro-oauth Proxy，該 Proxy 是在您設定 Edge Microgateway 時部署至 Apigee 組織。這個 Proxy 提供產生權杖所需的服務。

upgradeauth -o org -e env -u username

如要進一步瞭解這個指令，請參閱「升級 edgemicro-auth Proxy」。

輪替金鑰

在 ~/.edgemicro/org-env-config.yaml 檔案中新增下列程式碼，並指定您設定微閘道使用的組織和環境：

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

執行金鑰輪替指令，輪替金鑰。(如要進一步瞭解這個指令，請參閱「輪替金鑰」)。

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

例如：

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

-k 參數會指定金鑰 ID (kid)。這個 ID 用於比對特定金鑰。Edge Microgateway 會在金鑰輪替期間，使用這個值從一組金鑰中選擇。詳情請參閱 JSON Web Key 規格的第 4.5 節。

金鑰輪替後，Edge 會將多個金鑰傳回 Edge Microgateway。請注意，在以下範例中，每個金鑰都有專屬的「kid」(金鑰 ID) 值。接著，Microgateway 會使用這些金鑰驗證授權權杖。如果權杖驗證失敗，Microgateway 會查看金鑰組中是否有舊金鑰，並嘗試使用該金鑰。傳回的金鑰格式為 JSON Web Key (JWK)。如要瞭解這種格式，請參閱 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"
    }
  ]
}

篩選下載的 Proxy

根據預設，Edge Microgateway 會下載 Edge 組織中所有名稱開頭為「edgemicro_」的 Proxy。您可以變更這項預設設定，下載名稱符合特定模式的 Proxy。

  1. 開啟 Edge Micro 設定檔：~/.edgemicro/org-env-config.yaml
  2. 在 edge_config 下方新增 proxyPattern 元素。舉例來說，下列模式會下載 edgemicro_foo、edgemicro_fast 和 edgemicro_first 等 Proxy。
    edge_config:
…
proxyPattern: edgemicro_f*

指定不含 API Proxy 的產品

在 Apigee Edge 中，您可以建立不含任何 API Proxy 的 API 產品。這項產品設定可讓與該產品相關聯的 API 金鑰，與貴組織中部署的任何 Proxy 搭配使用。自 2.5.4 版起，Edge Microgateway 支援這項產品設定。

偵錯與疑難排解

連線至偵錯工具

您可以使用偵錯工具 (例如 node-inspector) 執行 Edge Microgateway。這有助於排解及偵錯自訂外掛程式的問題。

  1. 在偵錯模式中重新啟動 Edge Microgateway。方法是在 start 指令開頭加上 DEBUG=*。例如： 
    DEBUG=* edgemicro start -o  myorg -e test -k
      db4e9e8a95aa7fabfdeacbb1169d0a8cbe42bec19c6b98129e02 -s
      6e56af7c1b26dfe93dae78a735c8afc9796b077d105ae5618ce7ed
  2. 啟動偵錯工具，並設定監聽偵錯程序的通訊埠號碼。
  3. 您現在可以逐步執行 Edge Microgateway 程式碼、設定中斷點、監看運算式等。

您可以指定與偵錯模式相關的標準 Node.js 旗標。例如，--nolazy 有助於偵錯非同步程式碼。

檢查記錄檔

如果遇到問題，請務必檢查記錄檔，查看執行詳細資料和錯誤資訊。詳情請參閱「管理記錄檔」。

使用 API 金鑰安全性

API 金鑰提供簡單的機制，可驗證向 Edge Microgateway 提出要求的用戶端。如要取得 API 金鑰，請從包含 Edge Microgateway 驗證 Proxy 的 Apigee Edge 產品，複製用戶端金鑰 (也稱為用戶端 ID) 值。

快取金鑰

API 金鑰會與不記名權杖交換，並快取不記名權杖。如要停用快取功能，請在傳入 Edge Microgateway 的要求中設定 Cache-Control: no-cache 標頭。

使用 API 金鑰

您可以在 API 要求中，以查詢參數或標頭的形式傳遞 API 金鑰。根據預設，標頭和查詢參數名稱都是 x-api-key。

查詢參數範例：

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

標頭範例：

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

設定 API 金鑰名稱

根據預設，API 金鑰標頭和查詢參數都會使用 x-api-key 這個名稱。您可以按照「變更設定」一節的說明，在設定檔中變更這項預設設定。舉例來說，如要將名稱變更為 apiKey：

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

在這個範例中，查詢參數和標頭名稱都會變更為 apiKey。無論是哪種情況，x-api-key 名稱都將無法再使用。另請參閱「變更設定」。

例如：

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

如要進一步瞭解如何搭配 Proxy 要求使用 API 金鑰，請參閱「Secure Edge Microgateway」。

使用 OAuth2 權杖安全性

本節說明如何取得 OAuth2 存取權杖和更新權杖。存取權杖用於透過微閘道發出安全的 API 呼叫。更新權杖可用於取得新的存取權杖。

如何取得存取權杖

本節說明如何使用 edgemicro-auth Proxy 取得存取權杖。

您也可以使用 edgemicro token CLI 指令取得存取權杖。如要進一步瞭解 CLI，請參閱「管理權杖」。

API 1

在網址中替換組織和環境名稱，並將從 Apigee Edge 開發人員應用程式取得的消費者 ID 和消費者密鑰值，替換為 client_id 和 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

(在 2.5.31 版中新增) 將用戶端憑證做為基本驗證標頭傳送，並將 grant_type 做為表單參數傳送。RFC 6749：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"

輸出內容範例

API 會傳回 JSON 回應。請注意，token 和 access_token 屬性之間沒有差異。兩者皆可使用。 
{
"token": "eyJraWQiOiIxIiwidHlwIjoi",
"access_token": "eyJraWQiOiIxIiwid",
"token_type": "bearer",
"expires_in": "108000"
}

如何取得更新權杖

如要取得更新權杖，請對 edgemicro-auth Proxy 的 /token 端點發出 API 呼叫。您「必須」使用 password 授權類型發出這項 API 呼叫。以下步驟將逐步說明整個程序。

  1. 使用 /token API 取得存取權杖和更新權杖。請注意，授權類型為 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 會傳回存取權杖和更新權杖。回應大致如下：

    {
    "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. 現在，您可以呼叫同一 API 的 /refresh 端點，使用更新權杖取得新的存取權杖。例如： 
    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 會傳回新的存取權杖。回應內容大致如下： 

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

永久監控

Forever 是一種 Node.js 工具，可在程序停止或發生錯誤時，自動重新啟動 Node.js 應用程式。Edge Microgateway 具有 forever.json 檔案，您可以設定該檔案，控制 Edge Microgateway 重新啟動的次數和間隔。這個檔案會設定名為 forever-monitor 的 Forever 服務，以程式輔助方式管理 Forever。

您可以在 Edge Microgateway 根安裝目錄中找到 forever.json 檔案。請參閱「Edge Microgateway 的安裝位置」。如要進一步瞭解設定選項，請參閱 forever-monitor 說明文件。

edgemicro forever 指令包含多個旗標，可讓您指定 forever.json 檔案的位置 (-f 旗標)，以及啟動/停止 Forever 監控程序 (-a 旗標)。例如：

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

詳情請參閱 CLI 參考資料中的「永久監控」一節。

指定設定檔端點

如果您執行多個 Edge Microgateway 執行個體，可能會想從單一位置管理其設定。方法是指定 HTTP 端點，讓 Edge Micro 下載設定檔。使用 -u 旗標啟動 Edge Micro 時，可以指定這個端點。

例如：

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

其中 mgconfig 端點會傳回設定檔的內容。根據預設，這個檔案位於 ~/.edgemicro，命名慣例為：org-env-config.yaml。

停用 TCP 連線資料緩衝

您可以使用 nodelay 設定屬性，停用 Edge Microgateway 所用 TCP 連線的資料緩衝功能。

根據預設，TCP 連線會使用 Nagle 演算法緩衝資料，然後再傳送。將 nodelay 設為 true，即可停用這項行為 (每次呼叫 socket.write() 時，資料都會立即觸發資料)。詳情請參閱 Node.js 說明文件。

如要啟用 nodelay，請按照下列方式編輯 Edge Micro 設定檔：

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

以獨立模式執行 Edge Microgateway

您可以執行 Edge Microgateway，完全不與任何 Apigee Edge 依附元件連線。這種情況稱為獨立模式，可讓您在沒有網際網路連線的情況下執行及測試 Edge Microgateway。

在獨立模式下，下列功能需要連線至 Apigee Edge，因此無法運作：

  • OAuth 和 API 金鑰
  • 配額
  • Analytics

另一方面，自訂外掛程式和尖峰停滯功能則會正常運作，因為這些功能不需要連線至 Apigee Edge。此外，您可以使用名為 extauth 的新外掛程式，在獨立模式下使用 JWT 授權對微閘道發出的 API 呼叫。

設定及啟動閘道

如要在獨立模式下執行 Edge Microgateway：

  1. 請確認您已安裝 Edge Microgateway 2.5.25 以上版本。如果不是，請務必執行下列指令，升級至最新版本：
    npm install -g edgemicro

    如需協助，請參閱「安裝 Edge Microgateway」。

  2. 建立設定檔，並命名為：$HOME/.edgemicro/org_name-env_name-config.yaml

    例如：

    vi $HOME/.edgemicro/foo-bar-config.yaml
  3. 將下列程式碼貼入檔案：
    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. 匯出下列環境變數，並將值設為「1」： 
    export EDGEMICRO_LOCAL=1
  5. 執行下列 start 指令，並提供值來例項化本機 Proxy：
    edgemicro start -o org_name -e environment_name -a local_proxy_name \
  -v local_proxy_version -t target_url -b base_path

    其中：

    • your_org 是您在設定檔名稱中使用的「機構」名稱。
    • your_environment 是您在設定檔名稱中使用的「env」名稱。
    • local_proxy_name 是要建立的本機 Proxy 名稱。您可以使用任何名稱。
    • local_proxy_version 是 Proxy 的版本號碼。
    • target_url 是 Proxy 目標的網址。(「目標」是指 Proxy 呼叫的服務)。
    • base_path 是 Proxy 的基本路徑。這個值必須以正斜線開頭。如要指定根基本路徑，請只輸入正斜線，例如「/」。

    例如：

    edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
  6. 測試設定。 
    curl http://localhost:8000/echo  { "error" : "missing_authorization" }

    由於 extauth 外掛程式位於 foo-bar-config.yaml 檔案中，因此您會收到「missing_authorization」錯誤。這個外掛程式會驗證 API 呼叫的授權標頭中必須存在的 JWT。在下一節中，您將取得 JWT，以便順利發出 API 呼叫。

範例：取得授權權杖

以下範例說明如何從 Apigee Edge (edgemicro-auth/jwkPublicKeys) 的 Edge Microgateway JWT 端點取得 JWT。 當您執行 Edge Microgateway 的標準設定和配置時，系統會部署這個端點。 如要從 Apigee 端點取得 JWT，您必須先完成標準 Edge Microgateway 設定，並連線至網際網路。此處僅以 Apigee 端點為例，並非必要。您也可以視需要使用其他 JWT 權杖端點。如果是，您必須使用該端點提供的 API 取得 JWT。

下列步驟說明如何使用 edgemicro-auth/jwkPublicKeys 端點取得權杖：

  1. 您必須執行 Edge Microgateway 的標準設定，才能將 edgemicro-auth Proxy 部署至 Apigee Edge 上的組織/環境。如果您先前已完成這個步驟，就不必重複執行。
  2. 如果您將 Edge Microgateway 部署至 Apigee Cloud，則必須連上網際網路，才能從這個端點取得 JWT。
  3. 停止 Edge Microgateway： 
    edgemicro stop
  4. 在先前建立的設定檔 ($HOME/.edgemicro/org-env-config.yaml) 中，將 extauth:publickey_url 屬性指向 Apigee Edge 組織/環境中的 edgemicro-auth/jwkPublicKeys 端點。例如：
    extauth:
  publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'
  5. 按照先前的做法，使用設定檔名稱中的組織/環境名稱，重新啟動 Edge Microgateway。例如：
    edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
  6. 從授權端點取得 JWT 權杖。由於您使用的是 edgemicro-auth/jwkPublicKeys 端點，因此可以使用下列 CLI 指令：

您可以使用 edgemicro token 指令或 API，為 Edge Microgateway 產生 JWT。例如：

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

其中：

  • your_org 是您先前設定 Edge Microgateway 的 Apigee 組織名稱。
  • your_env 是組織中的環境。
  • i 選項會指定開發人員應用程式的用戶端金鑰，該應用程式的產品包含 edgemicro-auth Proxy。
  • s 選項會指定開發人員應用程式的消費者密鑰，該應用程式的產品包含 edgemicro-auth Proxy。

這項指令會要求 Apigee Edge 產生 JWT，以便用於驗證 API 呼叫。

另請參閱「產生權杖」。

測試獨立設定

如要測試設定，請呼叫 API，並在授權標頭中加入權杖，如下所示：

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

範例：

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

輸出內容範例：

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

使用本機 Proxy 模式

在本機 Proxy 模式下，Edge Microgateway 不需要將支援 Microgateway 的 Proxy 部署至 Apigee Edge。您必須在啟動 Microgateway 時，提供本機 Proxy 名稱、基本路徑和目標網址，藉此設定「本機 Proxy」。接著，對微閘道發出的 API 呼叫會傳送至本機 Proxy 的目標網址。在其他方面，本機 Proxy 模式的運作方式與在一般模式下執行 Edge Microgateway 完全相同。驗證、尖峰防護、配額強制執行、自訂外掛程式等功能的運作方式也相同。

用途和範例

如果只需要將單一 Proxy 與 Edge Microgateway 執行個體建立關聯，本機 Proxy 模式就非常實用。舉例來說，您可以將 Edge Microgateway 做為 Sidecar Proxy 插入 Kubernetes，其中 Microgateway 和服務各自在單一 Pod 中執行，而 Microgateway 則管理與其隨附服務之間的流量。下圖說明此架構，其中 Edge Microgateway 在 Kubernetes 叢集中做為 Sidecar Proxy。每個微閘道執行個體只會與其隨附服務上的單一端點通訊：

Edgemicro 做為邊車容器

這種架構風格的優點是，Edge Microgateway 可為部署至容器環境 (例如 Kubernetes 叢集) 的個別服務提供 API 管理。

設定本機 Proxy 模式

如要將 Edge Microgateway 設為在本機 Proxy 模式下執行，請按照下列步驟操作：

  1. 請確認您已安裝 Edge Microgateway 2.5.25 以上版本。如果不是，請務必執行下列指令，升級至最新版本：
    npm install -g edgemicro

    如需協助，請參閱「安裝 Edge Microgateway」。

  2. 執行 edgemicro init 來設定本機設定環境，就像在一般 Edge Microgateway 設定中一樣。另請參閱「設定 Edge Microgateway」。
  3. 執行 edgemicro configure，就像在一般 Edge Microgateway 設定程序中一樣。例如： 
    edgemicro configure -o your_org -e your_env -u your_apigee_username

    這個指令會將 edgemicro-auth 政策部署至 Edge，並傳回啟動微型閘道所需的金鑰和密鑰。如需協助，請參閱「設定 Edge Microgateway」。

  4. 在 Apigee Edge 上建立 API 產品，並符合下列必要設定需求 (您可以視需要管理所有其他設定)：
    • 您必須將 edgemicro-auth Proxy 新增至產品。執行 edgemicro configure 時，系統會自動部署這個 Proxy。
    • 您必須提供資源路徑。Apigee 建議將這個路徑新增至產品：/**。詳情請參閱「設定資源路徑的行為」。另請參閱 Edge 說明文件中的「建立 API 產品」。

  5. 在 Apigee Edge 上建立開發人員，或視需要使用現有開發人員。如需協助，請參閱「使用 Edge 管理 UI 新增開發人員」。

  6. 在 Apigee Edge 上建立開發人員應用程式。您必須將剛建立的 API 產品新增至應用程式。如需協助，請參閱「在 Edge 管理 UI 中註冊應用程式」。
  7. 在安裝 Edge Microgateway 的機器上，匯出下列環境變數，並將值設為「1」。
    export EDGEMICRO_LOCAL_PROXY=1
  8. 執行下列 start 指令： 
    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

    其中：

    • your_org 是您的 Apigee 組織。
    • your_environment 是貴組織中的環境。
    • your_key 是您執行 edgemicro configure 時傳回的金鑰。
    • your_secret 是執行 edgemicro configure 時傳回的密鑰。
    • local_proxy_name 是要建立的本機 Proxy 名稱。
    • local_proxy_version 是 Proxy 的版本號碼。
    • target_url 是 Proxy 目標 (Proxy 會呼叫的服務) 的網址。
    • base_path 是 Proxy 的基本路徑。這個值必須以正斜線開頭。如要指定根基本路徑，請只輸入正斜線，例如「/」。

    例如：

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

測試設定

您可以呼叫 Proxy 端點，測試本機 Proxy 設定。舉例來說，如果您指定 /echo 的基本路徑，可以按照下列方式呼叫 Proxy：

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

由於您未提供有效的 API 金鑰，因此這項初始 API 呼叫會產生錯誤。您可以在先前建立的開發人員應用程式中找到金鑰。在 Edge UI 中開啟應用程式，複製用戶端金鑰，然後按照下列方式使用該金鑰：

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

例如：

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

輸出內容範例：

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