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

您正在查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

Edge Microgateway 3.2.x 版

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

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

本節說明如何升級現有的 Edge Microgateway 安裝作業。如果您在沒有網際網路連線的情況下操作，請參閱「我可以在沒有網際網路連線的情況下安裝 Edge Microgateway 嗎？」。

Apigee 建議您先使用新版本測試現有設定，再升級正式環境。

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

    如要安裝特定版本的 Edge Microgateway，請在安裝指令中指定版本號碼。舉例來說，如要安裝至 3.2.3 版，請使用下列指令：

    npm install edgemicro@3.2.3 -g
  2. 查看版本號碼。舉例來說，假設您安裝的是 3.2.3 版： 
    edgemicro --version
current nodejs version is v12.5.0
current edgemicro version is 3.2.3
  3. 最後，請升級至最新版的 edgemicro-auth 代理程式：
    edgemicro upgradeauth -o $ORG -e $ENV -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 -e $ENV -k $KEY -s $SECRET

    在此情況下：

    • $ORG 是 Edge 機構名稱 (您必須是機構管理員)。
    • $ENV 是貴機構中的環境 (例如「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 -e $ENV -k $KEY -s $SECRET

    在此情況下：

    • $ORG 是 Edge 機構名稱 (您必須是機構管理員)。
    • $ENV 是貴機構的環境 (例如「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 所需的金鑰和 Secret 則可儲存在下列環境變數中：

  • EDGEMICRO_ORG
  • EDGEMICRO_ENV
  • EDGEMICRO_KEY
  • EDGEMICRO_SECRET

設定這些變數為選用項目。如果您設定了這些值，使用指令列介面 (CLI) 設定及啟動 Edge Microgateway 時，就不需要指定這些值。

在 Edge Microgateway 伺服器上設定 SSL

請觀看以下影片，瞭解如何在 Apigee Edge Microgateway 中設定 TLS：

影片 說明
設定單向北向傳輸層安全標準 (TLS) 瞭解如何在 Apigee Edge Microgateway 中設定 TLS。 這部影片將概略說明 TLS 及其重要性，介紹 Edge Microgateway 中的 TLS，並示範如何設定 Northbound 單向 TLS。
設定雙向北向傳輸層安全標準 (TLS) 這是第二部關於在 Apigee Edge Microgateway 中設定 TLS 的影片。這部影片說明如何設定北向雙向 TLS。
設定單向和雙向南向傳輸層安全標準 (TLS) 這是第三部關於在 Apigee Edge Microgateway 中設定 TLS 的影片，說明如何設定南向單向和雙向 TLS。

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

https://localhost:8000/myapi

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

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

以下是設定檔中 SSL 已設定的 edgemicro 部分範例：

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 包含用戶端私密金鑰、憑證和 CA 憑證的 pfx 檔案路徑，格式為 PFX。
passphrase 字串，其中包含私密金鑰或 PFX 的通關密碼。
ca 包含 PEM 格式信任憑證清單的檔案路徑。
ciphers 描述要使用的密碼的字串，以「:」分隔。
rejectUnauthorized 如果為 True，系統會根據提供的 CA 清單驗證伺服器憑證。如果驗證失敗，系統會傳回錯誤。
secureProtocol 要使用的 SSL 方法。例如 SSLv3_method，可強制 SSL 為第 3 版。
servername SNI (伺服器名稱指示) TLS 擴充功能的伺服器名稱。
requestCert 2 向 SSL 為 true；1 向 SSL 為 false

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

如果您想將 TLS/SSL 設定套用至多個特定目標，則必須在設定中將第一個主機指定為「空白」，以便啟用通用要求，然後以任意順序指定特定主機。在這個範例中，設定會套用至多個特定主機：

targets:
 - host:   ## Note that this value must be "empty"
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       passphrase: admin123
       rejectUnauthorized: true
 - host: 'myserver1.example.com'
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       rejectUnauthorized: true
 - host: 'myserver2.example.com'
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       rejectUnauthorized: true

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

選項 說明
pfx 包含用戶端私密金鑰、憑證和 CA 憑證的 pfx 檔案路徑，格式為 PFX。
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 代理程式

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

使用自訂驗證服務

根據預設，Edge Microgateway 會使用在 Apigee Edge 上部署的 Proxy，用於 OAuth2 驗證。這個 Proxy 會在您首次執行 edgemicro configure 時部署。根據預設，這個 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 和記錄檔。

如何設定記錄層級

您可以在 edgemicro 設定中指定要使用的記錄層級。如需記錄層級和說明的完整清單，請參閱 edgemicro 屬性。

舉例來說，以下設定會將記錄層級設為 debug：

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

如何變更記錄間隔

您可以在 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

如何放寬嚴格的記錄檔案權限

根據預設，Edge Microgateway 會產生應用程式記錄檔案 (api-log.log)，檔案權限層級設為 0600。這個權限層級不允許外部應用程式或使用者讀取記錄檔。如要放寬此嚴格權限層級，請將 logging:disableStrictLogFile 設為 true。當這項屬性為 true 時，系統會將檔案權限設為 0755，並建立記錄檔。如果未提供 false 或屬性，權限預設為 0600。

已在 3.2.3 版中新增。

舉例來說： 

edgemicro:
 logging:
   disableStrictLogFile: true

良好的記錄檔維護最佳做法

隨著記錄檔資料的累積，Apigee 建議您採用下列做法：

  • 由於記錄檔可能會變得相當大，請確認記錄檔目錄有足夠的空間。請參閱以下各節：「記錄檔儲存的位置」和「如何變更預設記錄檔目錄」。
  • 每週至少刪除或移動一次記錄檔到個別的封存目錄。
  • 如果您的政策是刪除記錄，您可以使用 CLI 指令 edgemicro log -c 移除 (清除) 較舊的記錄。

記錄檔命名慣例

每個 Edge Microgateway 執行個體都會產生副檔名為 .log 的記錄檔。記錄檔的命名慣例如下：

edgemicro-HOST_NAME-INSTANCE_ID-api.log

舉例來說：

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.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：記錄層級。這個值取決於交易的內容，以及在 edgemicro 設定中設定的記錄層級。請參閱「如何設定記錄層級」。 統計資料記錄的層級設為 stats。系統會以 stats_log_interval 設定的定期間隔回報統計資料記錄。另請參閱「如何變更記錄間隔」。
  • 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：記錄層級。這個值取決於交易的內容，以及在 edgemicro 設定中設定的記錄層級。請參閱「如何設定記錄層級」。 統計資料記錄的層級設為 stats。系統會以 stats_log_interval 設定的定期間隔回報統計資料記錄。另請參閱「如何變更記錄間隔」。
  • treq：用於識別事件。在本例中，是指定要求。
  • m：目標要求中使用的 HTTP 動詞。
  • u：網址中 basepath 後面的部分。
  • h：後端目標的主機和通訊埠號碼。
  • i：記錄項目的 ID。所有四個事件項目都會共用這個 ID。

3. 目標傳入回應範例

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

1436403888651 - Unix 日期戳記

  • info：記錄層級。這個值取決於交易的內容，以及在 edgemicro 設定中設定的記錄層級。請參閱「如何設定記錄層級」。 統計資料記錄的層級設為 stats。系統會以 stats_log_interval 設定的定期間隔回報統計資料記錄。另請參閱「如何變更記錄間隔」。
  • tres：用於識別事件。在本例中，是「target response」。
  • s - HTTP 回應狀態。
  • d - 時間長度 (以毫秒為單位)。目標執行 API 呼叫所需的時間。
  • i：記錄項目的 ID。所有四個事件項目都會共用這個 ID。

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

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

1436403888651 - Unix 日期戳記

  • info：記錄層級。這個值取決於交易的內容，以及在 edgemicro 設定中設定的記錄層級。請參閱「如何設定記錄層級」。 統計資料記錄的層級設為 stats。系統會以 stats_log_interval 設定的定期間隔回報統計資料記錄。另請參閱「如何變更記錄間隔」。
  • 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」。
  • quotaUri：如果您想透過部署至貴機構的 edgemicro-auth 代理程式管理配額，請設定這個設定屬性。如果未設定此屬性，配額端點預設為內部 Edge Microgateway 端點。
    edge_config:
  quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth

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：只記錄錯誤訊息。
      • debug：記錄偵錯訊息，以及資訊、警告和錯誤訊息。
      • trace：記錄錯誤的追蹤資訊，以及資訊、警告和錯誤訊息。
      • none：不建立記錄檔。
    • 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 狀態碼。(新增於 v2.4.x)
  • keep_alive_timeout：這個屬性可讓您設定 Edge Microgateway 逾時時間 (以毫秒為單位)。(預設值：5 秒) (新增於 3.0.6 版)
  • headers_timeout：這個屬性會限制 HTTP 剖析器等待接收完整 HTTP 標頭的時間 (以毫秒為單位)。

    例如：

    edgemicro:
  keep_alive_timeout: 6000
  headers_timeout: 12000

    在內部，這個參數會在要求中設定 Node.js Server.headersTimeout 屬性。(預設：比使用 edgemicro.keep_alive_timeout 設定的時間多 5 秒。這項預設設定可避免負載平衡器或 Proxy 誤將連線中斷。)(新增於 3.1.1 版)

  • noRuleMatchAction： (字串) 如果 accesscontrol 外掛程式中指定的相符規則未解析 (不相符)，則要採取的動作 (允許或拒絕存取)。有效值：ALLOW 或 DENY。預設值：ALLOW (新增於 v3.1.7)
  • enableAnalytics：(預設值：true) 將屬性設為 false，即可避免載入 Analytics 外掛程式。在這種情況下，系統不會呼叫 Apigee Edge 數據分析。如果設為 true，或是未提供此屬性，則數據分析外掛程式會照常運作。詳情請參閱edgemicro 屬性。(新增於 3.1.8 版)。

    範例：

    edgemicro
  enableAnalytics=false|true
  • on_target_response_abort：這個屬性可讓您控制 Edge Microgateway 在用戶端 (Edge Microgateway) 與目標伺服器之間的連線提早關閉時的行為。
    值 說明
    預設 如果未指定 on_target_response_abort，則預設行為會截斷回應，但不會顯示錯誤。在記錄檔案中，警告訊息會顯示 targetResponse aborted 和 502 回應代碼。
    appendErrorToClientResponseBody 系統會將自訂錯誤 TargetResponseAborted 傳回用戶端。在記錄檔案中，警告訊息會顯示 targetResponse aborted 和 502 回應代碼。此外，系統會記錄錯誤 TargetResponseAborted，並附上訊息 Target response ended prematurely.
    abortClientRequest Edge Microgateway 會中止要求，並將警告寫入記錄檔：TargetResponseAborted 使用 502 要求狀態碼。

範例：

edgemicro:
 on_target_response_abort: appendErrorToClientResponseBody | abortClientRequest

標頭屬性

這些設定可設定如何處理特定 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 即可要求 Authorization 標頭 (預設值)。
  • allowInvalidAuthorization：(預設值：false) 如果設為 true，如果授權標頭中傳遞的權杖無效或已過期，系統就會允許 API 呼叫通過。將此屬性設為 false 可要求使用有效的符記 (預設值)。
  • authorization-header：(預設值：Authorization: Bearer) 用於將存取權權杖傳送至 Edge Microgateway 的標頭。如果目標需要使用 Authorization 標頭做為其他用途，您可能需要變更預設值。
  • 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 都必須附帶 x-api-key 標頭 (或自訂位置)，並附帶 API 金鑰。您可以只允許 API 金鑰安全性模型 (同時維持向後相容性)。(新增 2.4.x)
  • gracePeriod：這個參數可避免系統時鐘與 JWT 授權權杖中指定的 Not Before (nbf) 或 Issued At (iat) 時間有輕微差異而導致錯誤。將這個參數設為秒數，即可允許此類差異。(新增於 2.5.7 版)

外掛程式專屬屬性

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

篩選 Proxy

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

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

依名稱篩選產品

使用下列設定，限制 Edge Microgateway 下載及處理的 API 產品數量。如要篩選已下載的產品，請將 productnamefilter 查詢參數新增至 Edge Microgateway *.config.yaml 檔案中列出的 /products API。例如：

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'

請注意，查詢參數的值必須以規則運算式格式指定，並經過網址編碼。舉例來說，規則運算式 ^[Ee]dgemicro.*$ 會擷取以下名稱： "edgemicro-test-1"、"edgemicro_demo" 和 "Edgemicro_New_Demo"。適合在查詢參數中使用的網址編碼值為：%5E%5BEe%5Ddgemicro.%2A%24。

下列偵錯輸出結果顯示，系統只下載篩選出的產品：

...
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":[

         ]
      }
   ]
}

依據自訂屬性篩選產品

如要根據自訂屬性篩選產品，請按照下列步驟操作：

  1. 在 Edge 使用者介面中，選取您設定 Edge Microgateway 的機構/環境中的 edgemicro_auth Proxy。
  2. 在「Develop」分頁中，在編輯器中開啟 JavaCallout 政策。
  3. 使用鍵 products.filter.attributes 新增自訂屬性，並以半形逗號分隔屬性名稱清單。只有包含任一自訂屬性名稱的產品才會傳回至 Edge Microgateway。
  4. 您可以選擇停用檢查功能，藉由將自訂屬性 products.filter.env.enable 設為 false，查看產品是否已為目前環境啟用。(預設值為 true)。
  5. (僅限私有雲) 如果您使用的是 Edge for Private Cloud，請將屬性 org.noncps 設為 true，以便為非 CPS 環境提取產品。

    6. 例如：

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
    <DisplayName>JavaCallout</DisplayName>
    <FaultRules/>
    <Properties>
        <Property name="products.filter.attributes">attrib.one, attrib.two</Property>
        <Property name="products.filter.env.enable">false</Property>
        <Property name="org.noncps">true</Property>
    </Properties>
    <ClassName>io.apigee.microgateway.javacallout.Callout</ClassName>
    <ResourceURL>java://micro-gateway-products-javacallout-2.0.0.jar</ResourceURL>
</JavaCallout>

依據撤銷狀態篩選產品

API 產品有三種狀態碼：待處理、已核准和已撤銷。我們已在 edgemicro-auth 代理程式中，為「Set JWT Variables policy」新增名為 allowProductStatus 的新屬性。如要使用這項屬性篩選 JWT 中列出的 API 產品，請按照下列步驟操作：

  1. 在 Apigee 代理編輯器中開啟 edgemicro-auth 代理。
  2. 將 allowProductStatus 屬性新增至 SetJWTVariables 政策的 XML，並指定以逗號分隔的狀態碼清單做為篩選條件。例如，如要篩選「待處理」和「已撤銷」狀態：
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript timeLimit="20000" async="false" continueOnError="false"
    enabled="true" name="Set-JWT-Variables">
    <DisplayName>Set JWT Variables</DisplayName>
    <FaultRules/>
    <Properties>
        <Property name="allowProductStatus">Pending,Revoked</Property>
    </Properties>
    <ResourceURL>jsc://set-jwt-variables.js</ResourceURL>
</Javascript>

    如要只列出「已核准」的產品，請按照下列方式設定屬性：

    <Property name="allowProductStatus">Approved</Property>
  3. 儲存 Proxy。

    如果沒有 Property 標記，則 JWT 中會列出所有狀態碼的產品。

    如要使用這項新屬性，您必須升級 edgemicro-auth 代理程式。

設定 Analytics 推送頻率

使用下列設定參數，控制 Edge Microgateway 傳送數據至 Apigee 的頻率：

  • bufferSize (選用)：緩衝區可容納的 Analytics 記錄數量上限，超過上限後，系統就會開始刪除最舊的記錄。預設值：10000
  • batchSize (選用)：傳送至 Apigee 的大量數據記錄的大小上限。預設值：500
  • flushInterval (選用)：每個傳送至 Apigee 的資料分析記錄清除作業之間的毫秒數。預設值：5000

例如：

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

遮蓋分析資料

下列設定可避免要求路徑資訊顯示在 Edge 分析中。在微型閘道組態中新增以下內容，以遮蓋要求 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 資訊主頁中的相對路徑和絕對路徑區隔為不同的代理伺服器：

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

舉例來說，在下列設定中，Analytics 外掛程式會將包含 /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 Path /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

使用 HTTP Proxy 與 Apigee Edge 通訊

已在 3.1.2 版中新增。

如要使用 HTTP Proxy 進行 Edge Microgateway 和 Apigee Edge 之間的通訊，請按照下列步驟操作：

  1. 設定環境變數 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY。這些變數會控制您要用於與 Apigee Edge 通訊的每個 HTTP Proxy 主機，或哪些主機不應處理與 Apigee Edge 的通訊。例如：
    export HTTP_PROXY='http://localhost:3786'
export HTTPS_PROXY='https://localhost:3786'
export NO_PROXY='localhost,localhost:8080'

    請注意，NO_PROXY 可以是 Edge Microgateway 不應將 Proxy 連線至的網域清單，以半形逗號分隔。

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

  2. 重新啟動 Edge Microgateway。

使用 HTTP Proxy 進行目標通訊

已在 3.1.2 版中新增。

如要使用 HTTP Proxy 進行 Edge Microgateway 和後端目標之間的通訊，請執行下列操作：

  1. 在微型閘道設定檔中新增下列設定：
    edgemicro:
  proxy:
    tunnel: true | false
    url: proxy_url
    bypass: target_host # target hosts to bypass the proxy.
    enabled: true | false

    在此情況下：

    • tunnel：(選用) 設為 true 時，Edge Microgateway 會使用 HTTP CONNECT 方法，透過單一 TCP 連線建立 HTTP 隧道。(如果用於設定 Proxy 的環境變數已啟用 TLS，則同樣適用)。預設值：false
    • url：HTTP 代理網址。
    • bypass：(選用) 指定應略過 HTTP 代理的一或多個以半形逗號分隔的目標主機網址。如果未設定這個屬性，請使用 NO_PROXY 環境變數指定要略過的目標網址。
    • enabled：如果為 true 且已設定 proxy.url，請使用 proxy.url 值做為 HTTP Proxy。如果為 true 且未設定 proxy.url，請使用 HTTP Proxy 環境變數 HTTP_PROXY 和 HTTPS_PROXY 中指定的 Proxy，如使用 HTTP Proxy 與 Apigee Edge 進行通訊所述。

    例如：

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

  2. 重新啟動 Edge Microgateway。

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

您可以在 edgemicro_* (Microgateway 感知) 代理程式的基本路徑中使用一或多個「*」萬用字元。舉例來說，如果 basePath 為 /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 的收件者可靠地驗證。

您可以使用 CLI 產生 JWT，並在 API 呼叫的授權標頭中使用 JWT，而非 API 金鑰。例如：

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

如要瞭解如何使用 CLI 產生 JWT，請參閱「產生權杖」。

什麼是金鑰輪替？

在初次產生 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。如果驗證失敗，系統會使用舊的公開金鑰，直到 JWT 到期為止 (在 token_expiry* 間隔後，預設為 30 分鐘)。這樣一來，您就能「輪替」金鑰，而不會立即中斷 API 流量。

如何輪替金鑰

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

  1. 如要升級 KVM，請使用 edgemicro upgradekvm 指令。如要進一步瞭解如何執行這項指令，請參閱「升級 KVM」。這個步驟只需要執行一次。
  2. 如要升級 edgemicro-oauth Proxy，請使用 edgemicro upgradeauth 指令。 如要進一步瞭解如何執行這項指令，請參閱「 升級 edgemicro-auth 代理伺服器」。這個步驟只需要執行一次。
  3. 在 ~/.edgemicro/org-env-config.yaml 檔案中加入下列程式碼行，其中必須指定您設定微型閘道要使用的相同機構和環境：
    jwk_public_keys: 'https://$ORG-$ENV.apigee.net/edgemicro-auth/jwkPublicKeys'

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

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

    例如：

    edgemicro rotatekey -o docs -e test \
-k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
-s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47

金鑰輪替後，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"
    }
  ]
}

設定「不早於」延遲時間

在 3.1.5 以下版本中，由 rotatekey 指令產生的新私密金鑰會立即生效，而產生的新符記會使用新私密金鑰簽署。不過，根據預設，只有在微網關設定重新整理時，新公開金鑰才會每 10 分鐘提供給 Edge Microgateway 執行個體。由於憑證簽署和微網關執行個體重新整理之間存在這類延遲，因此在所有執行個體都收到最新的公開金鑰之前，系統會拒絕使用最新金鑰簽署的憑證。

如果有多個微型閘道執行個體，公用金鑰延遲可能會導致間歇性執行階段錯誤，並顯示狀態 403，這是因為權杖驗證會在一個執行個體上通過，但在另一個執行個體上失敗，直到所有執行個體都重新整理為止。

自 3.1.6 版起，您可以透過 rotatekey 指令的新標記，指定新私密金鑰生效的延遲時間，讓所有微型閘道執行個體有時間重新整理並接收新公開金鑰。新的標記為 --nbf，代表「not before」。此標記會採用整數值，也就是延遲的時間長度 (分鐘數)。

在以下範例中，延遲時間設為 15 分鐘：

edgemicro rotatekey -o docs -e test \
-k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
-s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47 \
--nbf 15

請注意，建議做法是將延遲時間設為大於 config_change_poll_internal 設定 (預設為 10 分鐘)。另請參閱 edgemicro 屬性。

篩選已下載的 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 $ORG -e $ENV -k $KEY -s $SECRET

    如要將偵錯輸出內容直接輸出至檔案，您可以使用以下指令：

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

  2. 啟動偵錯工具，並將其設為偵聽偵錯程序的通訊埠號碼。
  3. 您現在可以逐步執行 Edge Microgateway 程式碼、設定中斷點、監控運算式等等。

您可以指定與偵錯模式相關的標準 Node.js 標記。舉例來說，--nolazy 可協助偵錯非同步程式碼。

檢查記錄檔

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

使用 API 金鑰安全性

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

快取金鑰

API 金鑰會換成權證權杖，並儲存在快取中。如要停用快取功能，請將 Cache-Control: no-cache 標頭設為 Edge Microgateway 的傳入要求。

使用 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 金鑰名稱

根據預設，x-api-key 是 API 金鑰標頭和查詢參數使用的名稱。您可以在設定檔中變更這個預設值，如「變更設定」一節所述。例如，如要將名稱變更為 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」。

啟用上游回應代碼

根據預設，如果回應不是 200 狀態，oauth 外掛程式只會傳回 4xx 錯誤狀態碼。您可以變更這項行為，讓系統根據錯誤一律傳回確切的 4xx 或 5xx 代碼。

如要啟用這項功能，請將 oauth.useUpstreamResponse: true 屬性新增至 Edge Microgateway 設定。例如： 

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

使用 OAuth2 權杖安全性

本節說明如何取得 OAuth2 存取權杖和重新整理權杖。存取權存取金鑰可用於透過微型閘道進行安全的 API 呼叫。更新權杖用於取得新的存取權杖。

如何取得存取權杖

本節說明如何使用 edgemicro-auth 代理程式取得存取權權杖。

您也可以使用 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：在 Basic Auth 標頭中傳送憑證

將用戶端憑證做為基本驗證標頭傳送，並將 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 屬性沒有差異。您可以使用其中任一選項。請注意，expires_in 是整數值，以秒為單位。
{
"token": "eyJraWQiOiIxIiwidHlwIjoi",
"access_token": "eyJraWQiOiIxIiwid",
"token_type": "bearer",
"expires_in": 1799
}

如何取得更新權杖

如要取得重新整理權杖，請對 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 會傳回存取權杖和更新憑證。回應內容如下所示。請注意，expires_in 值為整數，並以秒為單位。

    {
    "token": "your-access-token",
    "access_token": "your-access-token",
    "token_type": "bearer",
    "expires_in": 108,
    "refresh_token": "your-refresh-token",
    "refresh_token_expires_in": 431,
    "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

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

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

  • OAuth 和 API 金鑰
  • 配額
  • 數據分析

另一方面，自訂外掛程式和尖峰封鎖功能會正常運作，因為它們不需要連線至 Apigee Edge。此外，您還可以使用名為 extauth 的新外掛程式，在獨立模式下授權向微型閘道發出 API 呼叫，並使用 JWT 進行呼叫。

設定及啟動閘道

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

  1. 建立名為 $HOME/.edgemicro/$ORG-$ENV-config.yaml 的設定檔。

    例如：

    vi $HOME/.edgemicro/foo-bar-config.yaml
  2. 將下列程式碼貼到檔案中：
    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. 匯出值為「1」的下列環境變數：
    export EDGEMICRO_LOCAL=1
  4. 執行下列 start 指令，提供值來將本機 Proxy 例項化：
    edgemicro start -o $ORG -e $ENV -a $LOCAL_PROXY_NAME \
  -v $LOCAL_PROXY_VERSION -t $TARGET_URL -b $BASE_PATH

    在此情況下：

    • $ORG 是您在設定檔名稱中使用的「org」名稱。
    • $ENV 是您在設定檔名稱中使用的「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 /
  5. 測試設定。 
    curl http://localhost:8000/echo  { "error" : "missing_authorization" }

    由於 extauth 外掛程式位於 foo-bar-config.yaml 檔案中，因此您會收到「missing_authorization」錯誤。這個外掛程式會驗證 JWT，該 JWT 必須位於 API 呼叫的授權標頭中。在下一節中，您將取得 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 代理程式部署至 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. 請使用設定檔名稱中的 org/env 名稱，按照先前的步驟重新啟動 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 呼叫。

另請參閱「產生權杖」。

測試獨立設定

如要測試設定，請在 Authorization 標頭中加入權杖，然後呼叫 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 不需要在 Apigee Edge 上部署microgateway 感知 Proxy。而是在啟動微型閘道時，提供本機 Proxy 名稱、basepath 和目標網址，藉此設定「本機 Proxy」。接著，系統會將對微型閘道的 API 呼叫傳送至本機 Proxy 的目標網址。在所有其他方面，本機 Proxy 模式的運作方式與在 Edge Microgateway 的正常模式下運作完全相同。驗證機制、尖峰封鎖和配額強制執行、自訂外掛程式等也都會以相同方式運作。

用途和範例

如果您只需要將單一 Proxy 與 Edge Microgateway 執行個體建立關聯，本地 Proxy 模式就很實用。舉例來說，您可以將 Edge Microgateway 做為補充資訊 Proxy 植入 Kubernetes，其中 Microgateway 和服務各自在單一 Pod 中執行，而 Microgateway 則管理與其配對服務的流量。下圖說明此架構，其中 Edge Microgateway 會在 Kubernetes 叢集中做為補充 Proxy 運作。每個微型閘道執行個體只會與其伴隨服務的單一端點通訊：

使用 Edgemicro 做為補充資訊

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

設定本機 Proxy 模式

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

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

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

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

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

  5. 在 Apigee Edge 上建立開發人員應用程式。您必須將剛剛建立的 API 產品新增至應用程式。如需協助，請參閱「在 Edge 管理 UI 中註冊應用程式」。
  6. 在安裝 Edge Microgateway 的機器上，匯出下列環境變數，並將值設為「1」。
    export EDGEMICRO_LOCAL_PROXY=1
  7. 執行下列 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 中開啟應用程式，複製消費者金鑰，然後按照下列方式使用該金鑰：

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

使用同步器

本節說明如何使用同步器。這項選用功能可讓 Edge Microgateway 從 Apigee Edge 擷取設定資料，並將資料寫入本機 Redis 資料庫，進而提升 Edge Microgateway 的復原能力。同步器執行個體運作後，在不同節點上執行的其他 Edge Microgateway 執行個體就能直接從這個資料庫擷取設定。

同步器功能目前支援與 Redis 5.0.x 搭配運作。

什麼是同步器？

同步器可為 Edge Microgateway 提供一定程度的復原能力。這有助於確保每個 Edge Microgateway 例項都使用相同的設定，且在發生網路中斷時，Edge Microgateway 例項可以正常啟動及執行。

根據預設，Edge Microgateway 執行個體必須能夠與 Apigee Edge 通訊，以便擷取及重新整理設定資料，例如 API Proxy 和 API 產品設定。如果 Edge 的網際網路連線中斷，微型閘道執行個體仍可繼續運作，因為最新的設定資料已快取。不過，如果沒有明確的連線，新的微型閘道執行個體就無法啟動。此外，網路中斷可能會導致一或多個微型閘道執行個體的設定資訊與其他執行個體不同步。

Edge Microgateway 同步器為 Edge Microgateway 例項提供替代機制，可擷取啟動和處理 API Proxy 流量所需的設定資料。從對 Apigee Edge 的呼叫擷取的設定資料包括：jwk_public_keys 呼叫、jwt_public_key 呼叫、啟動程序呼叫和 API 產品呼叫。同步器可讓在不同節點上執行的所有 Edge Microgateway 例項都能正確啟動並保持同步，即使 Edge Microgateway 和 Apigee Edge 之間的網路連線中斷也不受影響。

同步器是特別設定的 Edge Microgateway 例項。其唯一目的是輪詢 Apigee Edge (可設定時間)、擷取設定資料，然後將資料寫入本機 Redis 資料庫。同步器例項本身無法處理 API 代理程式流量。您可以將其他在不同節點上執行的 Edge Microgateway 例項設定為從 Redis 資料庫，而非 Apigee Edge 擷取設定資料。由於所有微型閘道執行個體都會從本機資料庫擷取設定資料，因此即使發生網路中斷情形，這些執行個體仍可啟動並處理 API 要求。

設定同步器執行個體

針對要用於同步器的 Edge Microgateway 安裝作業，在 org-env/config.yaml 檔案中新增下列設定：

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

舉例來說： 

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true
選項 說明
redisHost 執行 Redis 執行個體的主機。預設值：127.0.0.1
redisPort Redis 執行個體的通訊埠。預設值：6379
redisDb 要使用的 Redis 資料庫。預設值：0
redisPassword 資料庫密碼。

最後，請儲存設定檔並啟動 Edge Microgateway 執行個體。它會開始輪詢 Apigee Edge，並將下載的設定資料儲存在 Redis 資料庫中。

設定一般 Edge Microgateway 執行個體

同步器執行後，您可以設定其他 Edge Microgateway 節點，以便執行處理 API 代理程式流量的一般 Microgateway 執行個體。不過，您可以設定這些執行個體，讓它們從 Redis 資料庫取得設定資料，而非從 Apigee Edge 取得。

將下列設定新增至每個 Edge Microgateway 節點的 org-env/config.yaml 檔案。請注意，synchronizerMode 屬性已設為 0。這個屬性會將執行個體設為處理 API 代理程式流量的一般 Edge Microgateway 執行個體，而執行個體會從 Redis 資料庫取得其設定資料。

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

舉例來說： 

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

設定屬性

我們已新增下列設定屬性，以支援同步器的使用方式：

屬性 值 說明
edge_config.synchronizerMode 0 或 1

如果為 0 (預設值)，Edge Microgateway 會以標準模式運作。

如果為 1，請啟動 Edge Microgateway 執行個體，以便做為同步器運作。在這個模式下，執行個體會從 Apigee Edge 提取設定資料，並將其儲存在本機 Redis 資料庫中。這個例項無法處理 API Proxy 要求，其唯一目的是輪詢 Apigee Edge 的設定資料，並將其寫入本機資料庫。接著，您必須設定其他微型閘道執行個體，才能從資料庫讀取資料。
edge_config.redisBasedConfigCache true 或 false 如果為 True，Edge Microgateway 執行個體會從 Redis 資料庫擷取設定資料，而非從 Apigee Edge 擷取。Redis 資料庫必須與同步器設定的寫入資料庫相同。如果 Redis 資料庫無法使用或資料庫為空白，微型閘道會尋找現有的 cache-config.yaml 設定檔。

如果為 false (預設值)，Edge Microgateway 例項會照常從 Apigee Edge 擷取設定資料。
edgemicro.config_change_poll_interval 時間間隔 (以秒為單位) 指定同步器從 Apigee Edge 提取資料的輪詢間隔。

設定外掛程式的排除網址

您可以設定微型閘道，讓系統略過處理特定網址的外掛程式。您可以全域設定這些「排除」網址 (適用於所有外掛程式)，也可以針對特定外掛程式設定。

例如：

...
edgemicro:
  ...
  plugins:
    excludeUrls: '/hello,/proxy_one' # global exclude urls
    sequence:
      - oauth
      - json2xml
      - quota
json2xml:
  excludeUrls: '/hello/xml'  # plugin level exclude urls
...

在這個範例中，外掛程式不會處理使用路徑 /hello 或 /proxy_one 的傳入 API Proxy 呼叫。此外，如果 API 路徑中含有 /hello/xml，系統會略過 json2xml 外掛程式。

使用環境變數值設定設定屬性

您可以在設定檔中使用標記指定環境變數。系統會將指定的環境變數標記替換為實際的環境變數值。替換項目只會儲存在記憶體中，不會儲存在原始設定或快取檔案中。

在這個範例中，系統會將屬性 key 替換為 TARGETS_SSL_CLIENT_KEY 環境變數的值，以此類推。

targets:
  - ssl:
      client:
        key: <E>TARGETS_SSL_CLIENT_KEY</E>
        cert: <E>TARGETS_SSL_CLIENT_CERT</E>
        passphrase: <E>TARGETS_SSL_CLIENT_PASSPHRASE</E>

在這個範例中，<n> 標記用於表示整數值。僅支援正整數。

edgemicro:
  port: <E><n>EMG_PORT</n></E>

在這個範例中，<b> 標記用於表示布林值 (也就是 true 或 false)。

quotas:
  useRedis: <E><b>EMG_USE_REDIS</b></E>