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 是先前由設定指令傳回的金鑰。
   • secret 是先前由設定指令傳回的金鑰。

   例如

   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 是貴機構的環境 (例如「test」或「prod」)。
   • key 是先前由設定指令傳回的金鑰。
   • secret 是先前由設定指令傳回的金鑰。

   例如：

   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

以下列出所有支援的伺服器選項：

使用用戶端 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

以下列出所有支援的用戶端選項：

自訂 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 - 視情況而定。視記錄層級而定，可能是資訊、警告或錯誤。可以是統計記錄的統計資料、警告的警告，或錯誤的錯誤。
• req - 識別事件。在本例中，要求來自用戶端。
• m - 要求中使用的 HTTP 動詞。
• u：網址中位於 basepath 後方的部分。
• h - Edge Microgateway 監聽的主機和通訊埠號碼。
• r - 用戶端要求來源的遠端主機和通訊埠。
• i：要求 ID。這四個活動項目都會共用這個 ID。每項要求都會指派專屬要求 ID。根據要求 ID 關聯記錄檔記錄，可深入瞭解目標的延遲時間。
• d - Edge Microgateway 收到要求後經過的時間長度 (以毫秒為單位)。在上述範例中，系統在 7 毫秒後收到要求 0 的目標回應 (第 3 行)，並在額外 4 毫秒後將回應傳送給用戶端 (第 4 行)。換句話說，總要求延遲時間為 11 毫秒，其中目標佔 7 毫秒，Edge Microgateway 本身則佔 4 毫秒。

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

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

• 1436403888651 - Unix 日期戳記
• info - 視情況而定。視記錄層級而定，可能是資訊、警告或錯誤。可以是統計記錄的統計資料、警告的警告，或錯誤的錯誤。
• treq - 識別事件。在本例中，目標要求為：
• m - 目標要求中使用的 HTTP 動詞。
• u：網址中位於 basepath 後方的部分。
• h - 後端目標的主機和連接埠號碼。
• i：記錄項目的 ID。這四個活動項目都會共用這個 ID。

3. 目標傳入的回應範例

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

1436403888651 - Unix 日期戳記

• info - 視情況而定。視記錄層級而定，可能是資訊、警告或錯誤。可以是統計記錄的統計資料、警告的警告，或錯誤的錯誤。
• tres：識別事件。在本例中，目標是回應。
• s - HTTP 回應狀態。
• d - 時間長度 (以毫秒為單位)。目標呼叫 API 所花費的時間。
• i：記錄項目的 ID。這四個活動項目都會共用這個 ID。

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

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

1436403888651 - Unix 日期戳記

• info - 視情況而定。視記錄層級而定，可能是資訊、警告或錯誤。可以是統計記錄的統計資料、警告的警告，或錯誤的錯誤。
• 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 會做為驗證端點，向用戶端核發已簽署的存取權杖。執行 edgemicro configure 指令部署 Proxy 時，系統會傳回這個網址。詳情請參閱「設定及配置 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 的數字。
• 記錄：
  • level：(預設：error)
    • info：記錄流經 Edge Microgateway 執行個體的所有要求和回應。
    • warn - 只記錄警告訊息。
    • error：只記錄錯誤訊息。
  • dir：(預設值：/var/tmp) 記錄檔的儲存目錄。
  • stats_log_interval：(預設值：60) 統計資料記錄寫入 API 記錄檔的時間間隔 (以秒為單位)。
  • rotate_interval：(預設值：24) 記錄檔輪替間隔 (以小時為單位)。

• 外掛程式：外掛程式可為 Edge Microgateway 新增功能。如要進一步瞭解如何開發外掛程式，請參閱「開發自訂外掛程式」。

• dir：從 ./gateway 目錄到 ./plugins 目錄的相對路徑，或絕對路徑。
• sequence：要新增至 Edge Microgateway 執行個體的外掛程式模組清單。模組會按照這裡指定的順序執行。

• debug： 將遠端偵錯功能新增至 Edge Microgateway 程序。
  • port：要監聽的通訊埠編號。舉例來說，您可以將 IDE 偵錯工具設為監聽這個通訊埠。
  • args：偵錯程序的引數。例如：args --nolazy
    
• config_change_poll_interval: (預設值：600 秒) Edge Microgateway 會定期載入新設定，並在有任何變更時執行重新載入。輪詢會擷取在 Edge 上進行的任何變更 (產品、可感知微型閘道的 Proxy 等變更)，以及對本機設定檔所做的變更。
  
• disable_config_poll_interval： (預設值：false) 設為 true 即可關閉自動變更輪詢功能。
• request_timeout：設定目標要求的逾時時間。逾時時間以秒為單位。如果發生逾時，Edge Microgateway 會傳回 504 狀態碼。(新增 2.4.x 版)

標頭屬性

這些設定可設定特定 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 可防止將 via 標頭傳遞至目標。

OAuth 屬性

這些設定會決定 Edge Microgateway 如何強制執行用戶端驗證。

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

外掛程式專屬屬性

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

篩選 Proxy

您可以篩選 Edge Microgateway 例項要處理的微閘道感知 Proxy。 Edge Microgateway 啟動時，會下載與其相關聯機構中的所有微閘道感知 Proxy。使用下列設定，限制微型閘道處理的 Proxy。舉例來說，這項設定會將微閘道處理的 Proxy 數量限制為三個：edgemicro_proxy-1、edgemicro_proxy-2 和 edgemicro_proxy-3：

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

設定 Analytics 推送頻率

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

• bufferSize (選用)：緩衝區可保留的分析記錄數量上限，超過這個數量就會開始捨棄最舊的記錄。預設值：10000
• batchSize (選用)：傳送至 Apigee 的分析記錄批次大小上限。預設值：500
• flushInterval (選填)：每次將一批 Analytics 記錄傳送至 Apigee 的間隔時間 (以毫秒為單位)。預設值：5000

例如：

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

遮蓋 Analytics 資料

下列設定可防止要求路徑資訊顯示在 Edge Analytics 中。在微閘道設定中新增下列項目，遮蓋要求 URI 和/或要求路徑。請注意，URI 包含要求的主機名稱和路徑部分。

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

在 Edge Analytics 中區隔 API 呼叫

您可以設定 Analytics 外掛程式，將特定 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 basepath，以便在 Analytics 資訊主頁中區隔。舉例來說，如果您指定 /mocktarget/healthcheck，其中 /mocktarget 是 Proxy 基本路徑，則路徑為 /mocktarget/healthcheck 的所有 API 呼叫都會在資訊主頁中顯示為 edgemicro_proxyname-health。

舉例來說，在下列設定中，任何包含 /healthcheck 的 API 路徑都會由 Analytics 外掛程式區隔。也就是說，/foo/healthcheck 和 /foo/bar/healthcheck 會在 Analytics 資訊主頁中，以 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，都會在 Analytics 資訊主頁中，區隔為名為 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：

第一個選項是在微型閘道設定檔中，將 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) 代理程式的基礎路徑中使用一或多個「*」萬用字元。舉例來說，如果基本路徑為「/team/*/members」，用戶端就能呼叫「https://[host]/team/blue/members」和「https://[host]/team/green/members」，您不必建立新的 API 代理程式來支援新團隊。請注意，系統不支援 /**/。

重要事項：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 時，系統會建立 KVM microgateway 並填入金鑰。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」。

下一個指令會升級部署至 Apigee 機構的 edgemicro-oauth Proxy (設定 Edge Microgateway 時)。這個 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) 值。微型閘道接著會使用這些金鑰驗證授權權杖。如果權杖驗證失敗，微型閘道會檢查金鑰集是否有較舊的金鑰，並嘗試使用該金鑰。傳回的金鑰格式為 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"

如要進一步瞭解如何搭配使用 API 金鑰與 Proxy 要求，請參閱「 安全 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

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"

輸出內容範例

{
"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 執行個體，可能希望從單一位置管理這些執行個體的設定。方法是指定 Edge Micro 可下載設定檔的 HTTP 端點。使用 -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

您可以完全與任何 Apigee Edge 依附元件中斷連線，然後執行 Edge Microgateway。這種情況稱為獨立模式，可讓您在沒有網路連線的情況下執行及測試 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 是您在設定檔名中使用的「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」錯誤。這個外掛程式會驗證 JWT，該 JWT 必須位於 API 呼叫的 Authorization 標頭中。在下一節中，您將取得 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 選項會指定開發人員應用程式的 Consumer Secret，該應用程式具有包含 edgemicro-auth Proxy 的產品。

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

測試獨立設定

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

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 不需要微閘道感知 Proxy 部署在 Apigee Edge 上。您可以在啟動微型閘道時，提供本機 Proxy 名稱、basepath 和目標網址，藉此設定「本機 Proxy」。接著，傳送至微型閘道的 API 呼叫會傳送至本機 Proxy 的目標網址。在其他所有方面，本機 Proxy 模式的運作方式與在正常模式下執行 Edge Microgateway 完全相同。驗證機制、尖峰流量抑制、配額強制執行和自訂外掛程式等功能，運作方式都相同。

用途和範例

如果您只需要將單一 Proxy 與 Edge Microgateway 執行個體建立關聯，即可使用本機 Proxy 模式。舉例來說，您可以將 Edge Microgateway 植入 Kubernetes 做為補充資訊代理程式，其中微閘道和服務各在單一 Pod 中執行，而微閘道會管理往返其隨附服務的流量。下圖說明這個架構，其中 Edge Microgateway 在 Kubernetes 叢集中做為 Sidecar Proxy。每個微閘道執行個體只會與隨附服務上的單一端點通訊：

這種架構的優點是，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 的 basepath，可以呼叫 Proxy，如下所示：

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

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

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