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

您正在查看 Apigee Edge 說明文件。
參閱 Apigee X 說明文件。 資訊

Edge Microgateway 3.3.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 Proxy： 
    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 所需的金鑰和密鑰可以儲存在以下環境變數中：

  • 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 One-Way TLS。
設定雙向傳輸層安全標準 (TLS) 這是第二部影片，說明如何在 Apigee Edge Microgateway 中設定傳輸層安全標準 (TLS)。這部影片說明如何設定北邊界雙向 TLS。
設定單向和雙向方向傳輸層安全標準 (TLS) 這部第三部影片說明如何在 Apigee Edge Microgateway 中設定 TLS，並說明如何設定南界的單向與雙向 TLS。

您可以將 Microgateway 伺服器設定為使用 SSL。舉例來說，在設定 SSL 後，您可以使用「https」通訊協定，透過 Edge Microgateway 呼叫 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

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

Option 鍵 說明
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 是雙向 SSL 為 true，單向安全資料傳輸層 (SSL) 為 false

使用用戶端 SSL/TLS 選項

您可以在連線至目標端點時，將 Edge Microgateway 設定為 TLS 或 SSL 用戶端。在 Microgateway 設定檔中，使用目標元素來設定 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

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

Option 鍵 說明
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-驗證 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 和記錄檔。

如何設定記錄層級

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

關於記錄檔內容

已新增：v2.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 - 網址在基本路徑之後的部分。
  • h - Edge Microgateway 正在監聽的主機和通訊埠編號。
  • r：用戶端要求的來源遠端主機和通訊埠。
  • i - 要求 ID。這四個活動項目都會共用這個 ID。每項要求都會獲派專屬的要求 ID。按照要求 ID 將記錄檔記錄相互關聯，可讓您深入瞭解目標的延遲時間。
  • d：Edge Microgateway 收到要求後所經過的時間長度 (以毫秒為單位)。在上例中，7 毫秒 (第 3 行) 後收到目標要求 0 的回應，回應則在經過額外的 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 - 網址在基本路徑之後的部分。
  • h - 後端目標的主機和通訊埠編號。
  • i - 記錄項目的 ID。這四個活動項目都會共用這個 ID。

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

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

1436403888651 - Unix 日期戳記

  • info - 記錄層級。這個值取決於交易結構定義和 edgemicro 設定中設定的記錄層級。請參閱「如何設定記錄層級」一節。 統計資料記錄的等級會設為 stats。系統會按照使用 stats_log_interval 設定的固定間隔來回報統計資料記錄。另請參閱如何變更記錄檔間隔。
  • tres - 用於識別事件。在這種情況下，目標回應。
  • 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 configuration。詳情請參閱「設定及設定 Edge Microgateway」。
  • quotaUri：如要透過已部署至貴機構的 edgemicro-auth Proxy 管理配額，請設定這項設定屬性。如未設定這項屬性，配額端點會預設為內部 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 的數字。
  • logging：
    • level：(預設：錯誤)
      • info - (建議) 記錄通過 Edge Microgateway 執行個體的所有要求與回應。
      • warn - 僅記錄警告訊息。
      • error - 僅記錄錯誤訊息。
      • 偵錯 - 記錄偵錯訊息以及資訊、警告和錯誤訊息。
      • trace：記錄錯誤的追蹤資訊，以及資訊、警告和錯誤訊息。
      • none：不要建立記錄檔。
    • dir：(預設: /var/tmp) 儲存記錄檔的目錄。
    • stats_log_interval：(預設值：60) 統計資料記錄寫入 API 記錄檔時，以秒為單位。
    • rotate_interval：(預設值：24) 輪替記錄檔的間隔，以小時為單位。
  • plugins：外掛程式可為 Edge Microgateway 新增功能。如要進一步瞭解如何開發外掛程式，請參閱「開發自訂外掛程式」。
  • dir：從 ./gateway 目錄到 ./plugins 目錄的相對路徑，或是絕對路徑。
  • sequence：要新增至 Edge Microgateway 執行個體的外掛程式模組清單。模組將按照此處指定的順序執行。
  • 偵錯： 將遠端偵錯功能新增至 Edge Microgateway 程序。
    • port：要監聽的通訊埠編號。舉例來說，您可以設定 IDE 偵錯工具，監聽這個通訊埠。
    • args：偵錯程序的引數。例如：args --nolazy
  • config_change_poll_interval: (預設值：600 秒) Edge Microgateway 會定期載入新設定，如果有任何變更，就會重新載入。輪詢作業會擷取您在 Edge 上進行的任何變更 (產品變更、微閘道感知 Proxy 等)，以及對本機設定檔所做的變更。
  • disable_config_poll_interval: (default: false) 設為 true 即可關閉自動變更輪詢功能。
  • request_timeout：設定目標要求的逾時。逾時設定以秒為單位。如果發生逾時，Edge Microgateway 會回應 504 狀態碼。(新增 2.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: (default: true) 將屬性設為 false，禁止載入分析外掛程式。這種情況下，系統不會呼叫 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 會取消要求，並在記錄檔中寫入警告：含有 502 要求狀態碼的 TargetResponseAborted。

範例：

edgemicro:
 on_target_response_abort: appendErrorToClientResponseBody | abortClientRequest

標題屬性

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

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

OAuth 屬性

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

  • allowNoAuthorization：(預設值：false) 如果設為 true，API 呼叫便可在完全不需要任何 Authorization 標頭的情況下透過 Edge Microgateway 傳遞。如需要求授權標頭，請將這個值設為 false。
  • allowInvalidAuthorization：(預設值：false) 如果設為 true，如果 Authorization 標頭中傳遞的權杖無效或過期，API 呼叫即可傳遞。請將這個值設為 false，藉此要求有效的權杖 (預設值)。
  • License-header：(預設：Authorization: Bearer) 用來將存取權杖傳送至 Edge Microgateway 的標頭。如果目標需要將 Authorization 標頭用於其他用途，建議您變更預設值。
  • api-key-header：(預設：x-api-key) 用來將 API 金鑰傳送至 Edge Microgateway 的標頭或查詢參數名稱。另請參閱「使用 API 金鑰」一節。
  • keep-Authorization-header：(default: false) 如果設為 true，要求中傳送的 Authorization 標頭會傳送至目標 (保留)。
  • allowOAuthOnly -- 如果設為 true，每個 API 都必須帶有包含不記名存取權杖的 Authorization 標頭。您可以僅允許 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：

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 UI 中，選取已設定 Edge Microgateway 的機構/環境下的 edgemicro_auth Proxy。
  2. 在「開發輕觸」中，開啟編輯器中的 Java 呼叫政策。
  3. 新增索引鍵為 products.filter.attributes 的自訂屬性，其中包含以半形逗號分隔的屬性名稱清單。只有包含任一自訂屬性名稱的產品才會退還至 Edge Microgateway。
  4. 您可以選擇將自訂屬性 products.filter.env.enable 設為 false，藉此停用檢查功能，看看該產品是否為目前環境啟用。 (預設值為 true)。
  5. (僅限私人 Cloud) 如果您使用 Private Cloud 邊緣，請將 org.noncps 屬性設為 true，藉此提取非 CCP 環境適用的產品。

    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>

設定數據分析推送頻率

使用下列設定參數來控管 Edge Microgateway 將數據分析資料傳送至 Apigee 的頻率：

  • bufferSize (選用)：緩衝區在開始捨棄最舊記錄前可保留的數據分析記錄數量上限。預設：10000
  • batchSize (選用)：傳送至 Apigee 的分析記錄批次大小上限。預設：500
  • flushInterval (選填)：每次清除一批次分析記錄並傳送至 Apigee 之間的毫秒數。預設：5000

例如：

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

遮蓋分析資料

下列設定會禁止要求路徑資訊顯示在 Edge Analytics 中。將下列內容新增至微閘道設定，以遮蓋要求 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 都會在數據分析資訊主頁中分割為獨立 Proxy，稱為 edgemicro_proxyname-health。

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. 將下列設定新增至 microgateway 設定檔：
    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 Proxy 網址。
    • bypass：(選用) 指定一或多個應略過 HTTP Proxy 的目標主機網址 (以半形逗號分隔)。如未設定這項屬性，請使用 NO_PROXY 環境變數來指定要略過的目標網址。
    • enabled：如果設定為 true 且已設定 proxy.url，則使用 HTTP Proxy 的 proxy.url 值。如未設定 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-aware) Proxy 的基本路徑中使用一或多個「*」萬用字元。舉例來說，/team/*/members 的基礎路徑可讓用戶端呼叫 https://[host]/team/blue/members 和 https://[host]/team/green/members，不必建立新的 API Proxy 來支援新團隊。請注意，系統不支援 /**/。

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

輪替 JWT 金鑰

初始產生 JWT 後，有時可能需要變更儲存在邊緣加密 KVM 中的公開/私密金鑰組。新金鑰組產生程序稱為「金鑰輪替」。

Edge Microgateway 如何使用 JWT

JSON Web Token (JWT) 是 RFC7519 中所述的權杖標準。JWT 是一種簽署一組憑證附加資訊的方式，可供 JWT 接收者根據這些憑證資訊進行驗證。

您可以使用 CLI 產生 JWT，然後將其用於 API 呼叫的授權標頭，而非 API 金鑰。例如：

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

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

什麼是金鑰輪替？

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

產生 JWT 時，Edge 會使用加密 KVM 中儲存的資訊。您一開始設定 (已設定) 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 值相關聯，並用於支援金鑰輪替。這個值與私密金鑰子項相同。

  • 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 Proxy」。這個步驟只需要執行一次。
  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。請注意，在以下範例中，每個鍵都有專屬的「兒童」(金鑰 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 傳送要求的用戶端。如要取得 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 金鑰名稱

根據預設，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"

如要進一步瞭解如何搭配使用 API 金鑰與 Proxy 要求，請參閱「 安全邊緣微閘道」一文。

啟用上游回應代碼

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

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

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

使用 OAuth2 權杖安全性

本節說明如何取得 OAuth2 存取權杖及更新權杖。存取權杖可透過微閘道安全地發出 API 呼叫。重新整理權杖可用來取得新的存取權杖。

如何取得存取權杖

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

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

API 1：傳送憑證做為主體參數

在網址中替換貴機構的名稱和環境名稱，並將 client_id 和 client_secret 主體參數替換成從 Apigee Edge 開發人員應用程式取得的「消費者 ID」和「用戶端密鑰」值：

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：透過基本驗證標頭傳送憑證

以「基本驗證」標頭的形式傳送用戶端憑證，並將 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"
    }

永久監控

指定設定檔端點

如果您執行多個 Edge Microgateway 執行個體，建議您透過單一位置管理其設定。如要這麼做，請指定 HTTP 端點，讓 Edge Micro 下載設定檔。您可以在啟動 Edge Micro 時使用 -u 標記指定此端點。

例如：

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 金鑰
  • 配額
  • 數據分析

另一方面，自訂外掛程式和峰值逮捕器則正常運作，因為這類外掛程式不需要連線至 Apigee Edge。此外，新的外掛程式 extauth 可讓您在獨立模式下，授權透過 JWT 對微閘道進行 API 呼叫的權限。

設定及啟動閘道

如何在獨立模式下執行 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 是您在設定檔名稱中使用的「機構」名稱。
    • $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_license」錯誤。這個外掛程式會驗證必須出現在 API 呼叫授權標頭中的 JWT。在下一節中，您會取得一個 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 的標準設定和設定，才能在 Apigee Edge 中將 edgemicro-auth Proxy 部署至您的機構/環境。如果您先前已經執行過這個步驟，則無需重複操作。
  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 選項會指定開發人員應用程式中的用戶端密鑰，如果開發人員應用程式含有含有 edgemicro-auth Proxy 的產品，便可以使用該密鑰。

這個指令會要求 Apigee Edge 產生可用於驗證 API 呼叫的 JWT。

另請參閱產生權杖。

測試獨立設定

如要測試設定，請使用 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 不需要具備微閘道感知的 Proxy 即可在 Apigee Edge 上部署。而是在啟動微閘道時提供本機 Proxy 名稱、基本路徑和目標網址來設定「本機 Proxy」。然後對微閘道的 API 呼叫傳送至本機 Proxy 的目標網址。在所有其他方面，本機 Proxy 模式的運作方式與在一般模式下執行 Edge Microgateway 完全相同。驗證的運作方式與尖峰流量遭到逮捕、強制執行配額、自訂外掛程式等相同。

用途和範例

您只需要將單一 Proxy 與 Edge Microgateway 執行個體建立關聯，本機 Proxy 模式就非常實用。舉例來說，您可以將 Edge Microgateway 插入 Kubernetes 做為補充 Proxy，其中微閘道和服務會在單一 Pod 中執行，而微閘道會管理與伴生服務之間的往來流量。下圖說明 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，並傳回您必須啟動微閘道所需的金鑰與密鑰。如需相關說明，請參閱「設定 Edge Microgateway」一文。

  3. 您可以透過 Apigee Edge 建立 API 產品，並設定下列強制性設定規定 (您可以視需要管理所有其他設定)：
    • 您必須將 edgemicro-auth Proxy 新增至產品。當您執行 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 的基本路徑，則可按照下列方式呼叫 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":""
}

使用同步處理器

本節說明如何使用同步處理器這項選用功能，從 Apigee Edge 擷取設定資料並寫入本機 Redis 資料庫，藉此提高 Edge Microgteway 的彈性。同步處理器執行個體在運作後，在不同節點上執行的其他 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 Proxy 流量。在其他節點上執行的 Edge Microgateway 執行個體，則可設定為從 Redis 資料庫 (而非 Apigee 邊緣) 擷取設定資料。由於所有微閘道執行個體都會從本機資料庫提取設定資料，因此即使發生網際網路中斷，執行個體也能啟動及處理 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
Option 鍵 說明
redisHost 執行 Redis 執行個體的主機。預設值：127.0.0.1
redisPort Redis 執行個體的通訊埠。預設：6379
redisDb 要使用的 Redis 資料庫。預設：0
redisPassword 您的資料庫密碼。

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

設定一般 Edge Microgateway 執行個體

同步處理器開始執行後，您可以設定額外的 Edge Microgateway 節點，以執行處理 API Proxy 流量的一般微閘道執行個體。不過，您可以設定這些執行個體，以便從 Redis 資料庫取得相關設定資料，而非從 Apigee Edge。

將以下設定新增至各個其他 Edge Microgateway 節點的 org-env/config.yaml 檔案。請注意，synchronizerMode 屬性已設為 0。這項屬性會將執行個體設為處理 API Proxy 流量的一般 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>