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

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件
資訊

Edge Microgateway 3.1.x 版

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

如有網際網路連線,請將 Edge Microgateway 升級

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

Apigee 建議您利用 再升級正式環境。

  1. 執行下列 npm 指令,升級至最新版的 Edge Microgateway:
    npm upgrade edgemicro -g

    如要升級至特定版本的 Edge Microgateway,您必須指定 versions. number如果未指定版本號碼, 安裝最新版本。舉例來說,如要升級至 3.1.0 版,請使用 以下指令:

    npm upgrade edgemicro@3.1.0 -g
  2. 查看版本號碼。舉例來說,假設您安裝了 3.1.0 版:
    edgemicro --version
    current nodejs version is v12.5.0
    current edgemicro version is 3.1.0
        
  3. 最後,請升級至最新版的 edgemicro-auth Proxy:
    edgemicro upgradeauth -o $ORG -e $ENV -u $USERNAME

變更設定

您需要知道的設定檔包括:

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

本節將說明這些檔案,以及變更這些檔案的相關須知。

預設系統設定 檔案

安裝 Edge Microgateway 時,預設的系統設定檔位於此處:

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

其中 prefixnpm 前置字串目錄。詳情請參閱 如果找不到這個目錄,請安裝 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,其中 orgenv 是 您的 Apigee Edge 機構和環境名稱。您可以使用這個檔案進行設定 並重新載入分頁,過程中完全不需要停機。舉例來說,如果新增並設定外掛程式 您可以重新載入設定,不會造成任何停機時間,詳情請見下文。

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

  1. 重新載入 Edge Microgateway 設定:
    edgemicro reload -o $ORG -e $ENV -k $KEY -s $SECRET

    在此情況下:

    • $ORG 是您的 Edge 機構名稱 (您必須是機構) 管理員)。
    • $ENV 是貴機構的環境 (例如「測試」或 「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 是貴機構的環境 (例如「測試」或 「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) 及其重要性和傳輸層安全標準 (TLS) ,並示範如何設定北方單向 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 對雙向 SSL 而言為 true;false 代表單向 SSL

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

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

選項 說明
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 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 並連結至記錄檔。

如何設定記錄層級

您可以設定以下記錄層級:資訊warn錯誤。建議提供資訊層級。會記錄所有 API 要求和回應 這是預設值

如何變更記錄檔間隔

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

可設定的屬性如下:

  • stats_log_interval:(預設值:60) 統計資料,以秒為單位 記錄寫入 API 記錄檔。
  • rotate_interval:(預設值:24) 間隔,以小時為單位,當記錄檔變成 模型也會自動旋轉。例如:
edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
敬上

良好的記錄檔維護做法

隨著記錄檔資料逐漸累積,Apigee 建議您採用下列做法: 做法:

  • 由於記錄檔可能會相當龐大,因此請務必確保記錄檔目錄含有 有足夠的空間。請參閱下列章節,瞭解記錄檔的儲存位置如何變更預設記錄檔 目錄
  • 每週至少刪除一次記錄檔,或將記錄檔移至另一個封存檔案。
  • 如要將記錄設為刪除記錄,您可以使用 CLI 指令 edgemicro log -c 移除 (清除) 舊記錄。

記錄檔命名慣例

每個 Edge Microgateway 執行個體都會產生三種類型的記錄檔:

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

命名慣例如下:

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

例如:

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

關於記錄檔內容

已新增:v2.3.3

預設情況下,記錄服務會省略下載的 Proxy、產品和 JSON 中的 JSON Web Token (JWT)。如果您希望將這些物件輸出至記錄檔,請設定 啟動 Edge Microgateway 時,值為 DEBUG=*。例如:

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

「API」的內容記錄檔

「api」記錄檔含有要求與回應流程的詳細資訊 通過 Edge Microgateway「api」記錄檔的命名方式如下:

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

針對每個傳送至 Edge Microgateway 的要求,「api」會擷取四個事件記錄 檔案:

  • 用戶端傳入的要求
  • 對目標提出的傳出要求
  • 目標的傳入回應
  • 傳送給用戶端的傳出回應

這些不同的項目都會以簡寫標記表示,有助於記錄紀錄 檔案會更壓縮以下是四個項目範例,分別代表這四個事件。在記錄中 檔案,號碼看起來像這樣 (行號僅供文件中參照,並不包含 )。

(1) 1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
(2) 1436403888665 info treq m=GET, u=/, h=127.0.0.18080, i=0
(3) 1436403888672 info tres s=200, d=7, i=0
(4) 1436403888676 info res s=200, d=11, i=0

以下將逐一介紹:

1. 用戶端傳入要求的範例:

1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
  • 1436403888651:Unix 日期戳記
  • info - 視上下文而定。可能是資訊、警告或錯誤 則視記錄層級而定可以是統計資料記錄的統計資料、警示警告或 發生錯誤。
  • req:用來識別事件。在此情況下,從 用戶端。
  • m - 要求中使用的 HTTP 動詞。
  • u - 網址中基本路徑後的部分。
  • h - Edge Microgateway 所在的主機和通訊埠編號 。
  • r - 用戶端要求的遠端主機和通訊埠 。
  • i - 要求 ID。四個事件項目均會共用這個 ID。每項 會指派給每個要求的專屬要求 ID依據要求 ID 關聯記錄檔的記錄可提供 提供寶貴的深入分析資訊,讓我們能深入瞭解目標的延遲時間。
  • d - 收到要求後的時間長度 (以毫秒為單位) Edge Microgateway。在上述範例中,收到目標要求 0 的回應 7 毫秒 (第 3 行),然後額外 4 次即可將回應傳送到用戶端 毫秒 (第 4 行)。換句話說,要求總延遲時間為 11 毫秒, 目標花費 7 毫秒,而 Edge Microgateway 則是 4 毫秒 機器學習是向機器提供資料和答案 讓機器自行探索規則的科學

2. 向目標發出的外送要求範例:

1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0
  • 1436403888651:Unix 日期戳記
  • info - 視上下文而定。可能是資訊、警告或錯誤 則視記錄層級而定可以是統計資料記錄的統計資料、警示警告或 發生錯誤。
  • treq - 用於識別事件。本例中的目標要求就是一個例子。
  • m - 目標要求中使用的 HTTP 動詞。
  • u - 網址中基本路徑後的部分。
  • h:後端目標的主機和通訊埠編號。
  • i - 記錄項目的 ID。四個活動項目會分享 編號。

3. 目標傳入回應的範例

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

1436403888651:Unix 日期戳記

  • info - 視上下文而定。可能是資訊、警告或錯誤 則視記錄層級而定可以是統計資料記錄的統計資料、警示警告或 發生錯誤。
  • tres:用來識別事件。在這種情況下,目標回應。
  • s - HTTP 回應狀態。
  • d - 以毫秒為單位的持續時間。API 呼叫花費的時間
  • i - 記錄項目的 ID。四個活動項目會分享 編號。

4. 向用戶端傳出回應的範例

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

1436403888651:Unix 日期戳記

  • info - 視上下文而定。可能是資訊、警告或錯誤 則視記錄層級而定可以是統計資料記錄的統計資料、警示警告或 發生錯誤。
  • res:用於識別事件。在此情況下,回應的 用戶端。
  • s - HTTP 回應狀態。
  • d - 以毫秒為單位的持續時間。這是指花費的總時間 ,包括目標 API 花費的時間以及 Edge 花費的時間 Microgateway 本身。
  • i - 記錄項目的 ID。四個活動項目會分享 編號。

記錄檔排程

記錄檔會以 rotate_interval 指定的間隔時間輪替 設定屬性。項目會繼續新增至 相同的記錄檔,直到輪替間隔到期為止。不過,每次 Edge Microgateway 執行個體重新啟動後會接收新的 UID,並使用這個 UID 建立一組新的記錄檔。其他參考資訊 妥善維護的記錄檔 做法

錯誤訊息

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

Edge Microgateway 設定參考資料

所在位置 設定檔

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

Edge_config 屬性

這些設定用於設定 Edge Microgateway 執行個體與 Apigee Edge。

  • bootstrap:(預設值:無) 指向 Edge 的網址 在 Apigee Edge 上執行的微型閘道專屬服務。Edge Microgateway 使用這項服務 與 Apigee Edge 通訊當您執行指令來產生 公開/私密金鑰組:edgemicro genkeys。如需說明,請參閱設定 並設定 Edge Microgateway
  • jwt_public_key:(預設值:無) 指向 Edge Microgateway 的網址 部署在 Apigee Edge 上的 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) 指定 Pod 網路數量上限 可同時接收 Edge Microgateway 接收的連線。如果此數字 超過的話,系統會傳回下列狀態:

    res.statusCode = 429; // Too many requests
  • max_connections_hard:(預設值:-1) 同時連線數量上限 在關閉連線之前,Edge Microgateway 可以接收的要求。這項設定 目的在於遏阻阻斷服務攻擊。通常應該設為大於 100 的數字 max_connections.
  • logging
    • level:(預設:錯誤)
      • 資訊 - 記錄通過 Edge Microgateway 執行個體。
      • warn - 僅記錄警告訊息。
      • error - 僅記錄錯誤訊息。
    • dir:(預設值:/var/tmp) 記錄檔所在的目錄 儲存。
    • stats_log_interval:(預設值:60) 統計資料,以秒為單位 則會寫入 API 記錄檔
    • rotate_interval:(預設值:24) 間隔,以小時為單位,當記錄檔變成 模型也會自動旋轉。
  • 外掛程式:外掛程式可為 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: (預設值:false) 設為 true關閉自動變更輪詢。
  • request_timeout:設定目標要求的逾時時間。逾時設定的期限為 秒內請求驗證碼。如果逾時,Edge Microgateway 會以 504 狀態碼回應。(已新增 v2.4.x)
  • keep_alive_timeout:這個屬性可讓您設定 Edge Microgateway 逾時 (以毫秒為單位)。(預設值為 5 秒) (已新增 v3.0.6)
  • headers_timeout:這個屬性限制時間 (以毫秒為單位) HTTP 剖析器會等待系統接收 完整的 HTTP 標頭

    例如:

    edgemicro:
    keep_alive_timeout: 6000
    headers_timeout: 12000

    參數會在內部設定 Node.js Server.headersTimeout敬上 屬性。(預設:超過 5 秒 使用 edgemicro.keep_alive_timeout 設定的時間。預設 設定可防止負載平衡器或 Proxy 意外捨棄連線)。(新增 3.1.1 版)

標題屬性

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

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

OAuth 屬性

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

  • allowNoAuthorization:(預設值:false) 如果設為 true,API 呼叫就會 即可在不透過任何 Authorization 標頭的情況下通過 Edge Microgateway。設為 false 代表要求 Authorization 標頭 (預設)。
  • allowInvalidAuthorization:(預設值:false) 如果設為 true,API 呼叫就會 可以在 Authorization 標頭中傳遞的權杖無效或已過期時傳遞。設定此項目 設為 false 時,要求有效的權杖 (預設)。
  • 授權標頭:(預設值:Authorization: Bearer) 用於 將存取權杖傳送至 Edge Microgateway。建議您變更預設設定,以因應以下情形: 有其他用途時,目標必須使用 Authorization 標頭。
  • api-key-header:(預設值:x-api-key) 標頭或查詢的名稱 參數,用來將 API 金鑰傳送至 Edge Microgateway。另請參閱使用 API 金鑰
  • keep-authorization-header:(預設值:false) 如果設為 true,則授權標頭 則會傳遞到目標 (會保留此值)。
  • allowOAuthOnly -- 若設為 True,則每個 API 都必須具有授權 加上不記名存取權杖的標頭。僅允許 OAuth 安全性模型 ( 就能維持回溯相容性)。(新增 2.4.x)
  • allowAPIKeyOnly -- 如果設為「true」,則每個 API 都必須包含一個 x-api-key 標頭 (或自訂位置);允許您允許 僅限 API 金鑰安全性模型 (同時保有回溯相容性)。(新增 2.4.x)
  • gracePeriod:這個參數可防止因輕微錯誤而造成的錯誤 系統時鐘與「之前」(nbf) 或「發行時間」(iat) 時間之間的差異 並在 JWT 授權憑證中指定的資訊。將此參數設為允許的秒數 以便瞭解這些差異(新增 2.5.7)

特定外掛程式 屬性

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

篩選 Proxy

您可以篩選 Edge Microgateway 執行個體將處理的微型閘道 Proxy。 Edge Microgateway 啟動時,會下載 與其他資源建立關聯請使用下列設定限制 可進行處理例如,以下設定可限制微閘道使用 Proxy 會處理至三個:edgemicro_proxy-1edgemicro_proxy-2、 和 edgemicro_proxy-3

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

篩選產品

請使用下列設定限制 Edge Microgateway 的 API 產品數量 下載和程序如要篩選已下載的產品,請新增「productnamefilter」 連至 /products API (列在 Edge Microgateway *.config.yaml 中) 的查詢參數 檔案。例如:

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

         ]
      }
   ]
}

設定數據分析推送頻率

使用下列設定參數控制 Edge Microgateway 傳送頻率 將資料傳送至 Apigee:

  • bufferSize (選用):偵測到的數據分析記錄數量上限 緩衝區可能在開始捨棄最舊的記錄前,預設:10000
  • batchSize (選用):單一批次分析記錄的大小上限 就會傳送到 Apigee預設:500
  • flushInterval (選用):每次隨機清除之間的毫秒數 將一批數據分析記錄傳送到 Apigee預設:5,000

例如:

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 路徑,讓該路徑顯示為 使用獨立的 Proxy 處理 Edge Analytics 資訊主頁舉例來說: 在資訊主頁中區隔健康狀態檢查 API,避免與實際的 API Proxy 呼叫混淆。在 不同 Proxy 的 Analytics 資訊主頁,遵循以下命名模式:

edgemicro_proxyname-health

下圖顯示 Analytics 資訊主頁中兩個不同的 Proxy:edgemicro_hello-healthedgemicro_mock-health:

使用這些 參數,將 Analytics 資訊主頁中的相對和絕對路徑區隔為個別 Proxy:

  • relativePath (選用):指定在 數據分析資訊主頁舉例來說,如果您指定 /healthcheck,那麼包含路徑的所有 API 呼叫都會 「/healthcheck」在資訊主頁中會顯示為「edgemicro_proxyname-health」。請注意,這個標記會忽略 Proxy 基本路徑。 如要根據完整路徑 (包括基本路徑) 隔離,請使用 proxyPath 旗標。
  • proxyPath (選用):指定完整的 API Proxy 路徑,包括 Proxy 基本路徑,在數據分析資訊主頁中區隔。舉例來說,如果您指定 /mocktarget/healthcheck 地點:/mocktarget 是 Proxy 基本路徑,含有路徑 /mocktarget/healthcheck 的所有 API 呼叫都會 在資訊主頁上顯示為 edgemicro_proxyname-health

例如,在下列設定中,凡是包含 /healthcheck 的 API 路徑,都會 由數據分析外掛程式分隔也就是說,/foo/healthcheck/foo/bar/healthcheck 在數據分析資訊主頁中,系統會將其區隔為 edgemicro_proxyname-health 以外的 Proxy。

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

在下列設定中,任何含有 Proxy 路徑 /mocktarget/healthcheck 的 API 都會 會獨立為 edgemicro_proxyname-health 這個獨立 Proxy 數據分析資訊主頁

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

在 公司防火牆

使用 HTTP Proxy 與 Apigee Edge 通訊

已在版本 3.1.2 中新增。

如要使用 HTTP Proxy 進行 Edge Microgateway 和 Apigee Edge 之間的通訊,請 包括:

  1. 設定環境變數 HTTP_PROXYHTTPS_PROXYNO_PROXY。這些 變數可控管您要用來與其通訊的每個 HTTP Proxy 的主機 Apigee Edge,或哪些主機不應處理與 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 方法將 HTTP 連線通道 並透過單一 TCP 連線處理多個要求(如果環境變數則無效, 下文 設定 Proxy 會啟用 TLS)。預設:false
    • url:HTTP Proxy 網址。
    • 略過:(選用) 指定一或多個以半形逗號分隔的目標主機網址, 略過 HTTP Proxy如未設定此屬性,請使用 NO_PROXY 環境變數,指定要略過哪些目標網址。
    • enabled:如果已設定 true 且 proxy.url,請為 HTTP Proxy 使用 proxy.url 值。 如果未設定 true 且 proxy.url 未設定,請使用 HTTP Proxy 中指定的 Proxy 環境變數 HTTP_PROXYHTTPS_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_* (可辨識微型閘道) Proxy。例如,基礎路徑 /team/*/members 能讓客戶呼叫 https://[host]/team/blue/membershttps://[host]/team/green/members,不必建立新的 API Proxy 支持新團隊請注意,我們不支援 /**/

重要事項:Apigee 不支援使用萬用字元「*」作為 計算基礎路徑的第一個元素例如「不」支援:/*/ 搜尋。

輪替 JWT 金鑰

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

Edge Microgateway 如何使用 JWT

JSON Web Token (JWT) 是 RFC7519 中說明的權杖標準。JWT 可讓您簽署一組憑證附加資訊 並可由 JWT 接收者驗證。

Edge Microgateway 使用 JWT 做為不記名權杖,確保 OAuth 安全性。產生模型後 Edge Microgateway 的 OAuth 權杖,則會收到 JWT。接著,您便能在 API 呼叫的授權標頭。例如:

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

產生新的 JWT

您可以使用 edgemicro token 指令或 以及 API例如:

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

這個指令會要求 Apigee Edge 產生可用來驗證 API 的 JWT 呼叫。-i-s 參數是開發人員應用程式中的消費者 ID 和密鑰值 在您的 Apigee Edge 機構中

您也可以使用 Management API 產生 JWT:

curl -i -X POST "http://$ORG-$ENV.apigee.net/edgemicro-auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "$CLIENT_ID": "your consumer key",
    "$CLIENT_SECRET": "your consumer secret",
    "grant_type": "client_credentials"
  }'

在此情況下:

  • $ORG 是您的 Edge 機構名稱 (您必須是機構組織管理員)。
  • $ENV 是貴機構的環境 (例如「test」或「prod」)。
  • $CLIENT_ID 是您先前建立的開發人員應用程式中消費者 ID。
  • $CLIENT_SECRET 是您建立的開發人員應用程式中的用戶端密鑰 像是剛才說過,即便 VM 正在運作 您還是能變更 VM 可用性政策

什麼是金鑰輪替?

初次產生 JWT 後不久,您可能需要將 儲存在 Edge 加密 KVM 中的公開/私密金鑰組。新金鑰的產生程序 稱為金鑰輪替輪替金鑰時,系統會產生新的私密/公開金鑰組合, 儲存在「微型閘道」中Apigee Edge 機構/環境中的 KVM。此外, 舊的公開金鑰及其原始金鑰 ID 值一併保留。

為了產生 JWT,Edge 會使用加密 KVM 中儲存的資訊。A 罩杯 名為 microgateway 的 KVM 已在您初始設定 (設定) 時建立並填入金鑰 Edge Microgateway。KVM 中的金鑰是用來簽署及加密 JWT。

KVM 金鑰包括:

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

  • public_key - 用來驗證 JWT 的最新 (最近建立) 憑證 使用 private_key 簽署即可

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

  • public_key1_kid - 最新 (最近建立) 的公開金鑰 ID。這把鑰匙 與 public_key1 值相關聯,並用於支援金鑰輪替。這個值 與私密金鑰的子項相同

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

執行金鑰輪替時,對應中現有的鍵/值會取代並新的 。例如:

  • public_key2_kid - 舊的公開金鑰 ID。這組金鑰與 public_key2 值,用於支援金鑰輪替。

  • public_key2 - 舊版公開金鑰。

系統會利用新的公開金鑰,驗證您提供給驗證的 JWT。如果 驗證失敗,系統就會使用舊的公開金鑰,直到金鑰過期 (30 分鐘後) 為止。於 即可透過這種方式「旋轉」而不會立即中斷 API 流量。

如何輪替金鑰

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

如果您將 Edge Microgateway 執行個體設為 2.5.2 以下版本

如果您在版本 2.5.2 之前設定 Edge Microgateway 執行個體,則必須執行 以下兩個指令即可升級 KVM 和驗證政策:

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

如要進一步瞭解這個指令,請參閱升級 KVM

下一個指令會升級已部署至 edgemicro-oauth Proxy 您的 Apigee 機構 (亦即設定 Edge Microgateway) 時。這個 Proxy 可以為 產生符記

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

如要進一步瞭解此指令,請參閱升級 Edgemicro-auth Proxy

輪替金鑰

~/.edgemicro/org-env-config.yaml 檔案中新增下列程式碼,您必須 指定您在微閘道設定要使用的機構和環境:

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

執行金鑰輪替指令來輪替金鑰。(如要進一步瞭解此指令,請參閱 輪替金鑰)。

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

例如:

edgemicro rotatekey -o jdoe -e test -u jdoe@google.com -k 2
current nodejs version is v12.5.0
current edgemicro version is 3.1.0
password:
Checking if private key exists in the KVM...
Checking for certificate...
Found Certificate
Generating New key/cert pair...
Extract new public key
Key Rotation successfully completed!

-k 參數會指定金鑰 ID (kid)。這個 ID 是用來比對特定鍵。 Edge Microgateway 會在金鑰輪替時,使用這個值選擇一組金鑰。如要 請參閱第 4.5 節 JSON Web 金鑰規格

金鑰輪替後,Edge 會將多個金鑰傳回 Edge Microgateway。「 下列範例中,每個鍵都有專屬的「kid」(金鑰 ID) 值。微型門接著會使用這些通道 驗證授權權杖。如果權杖驗證失敗,微閘道會尋找 看看該鍵中是否有較舊的金鑰,並嘗試輸入該鍵。 傳回的金鑰為 JSON Web Key (JWK)。如要瞭解這種格式,請參閱 RFC 7517

{
  "keys": [
    {
      "kty": "RSA",
      "n": "nSl7R_0wKLiWi6cO3n8aOJwYGBtinq723Jgg8i7KKWTSTYoszOjgGsJf_MX4JEW1YCScwpE5o4o8ccQN09iHVTlIhk8CNiMZNPipClmRVjaL_8IWvMQp1iN66qy4ldWXzXnHfivUZZogCkBNqCz7VSC5rw2Jf57pdViULVvVDGwTgf46sYveW_6h8CAGaD0KLd3vZffxIkoJubh0yMy0mQP3aDOeIGf_akeZeZ6GzF7ltbKGd954iNTiKmdm8IKhz6Y3gLpC9iwQ-kex_j0CnO_daHl1coYxUSCIdv4ziWIeM3dmjQ5_2dEvUDIGG6_Az9hTpNgPE5J1tvrOHAmunQ",
      "e": "AQAB",
      "kid": "2"
    },
    {
      "kty": "RSA",
      "n": "8BKwzx34BMUcHwTuQtmp8LFRCMxbkKg_zsWD6eOMIUTAsORexTGJsTy7z-4aH0wJ3fT-3luAAUPLBQwGcuHo0P1JnbtPrpuYjaJKSZOeIMOnlryJCspmv-1xG4qAqQ9XaZ9C97oecuj7MMoNwuaZno5MvsY-oi5B_gqED3vIHUjaWCErd4reONyFSWn047dvpE6mwRhZbcOTkAHT8ZyKkHISzopkFg8CD-Mij12unxA3ldcTV7yaviXgxd3eFSD1_Z4L7ZRsDUukCJkJ-8qY2-GWjewzoxl-mAW9D1tLK6qAdc89yFem3JHRW6L1le3YK37-bs6b2a_AqJKsKm5bWw",
      "e": "AQAB",
      "kid": "1"
    }
  ]
}

篩選已下載的 Proxy

根據預設,Edge Microgateway 會下載 Edge 機構中的所有 Proxy 名稱前置字串為「edgemicro_」你可以變更這項預設設定,以便下載 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 金鑰適用於任何 已部署在貴機構中自 2.5.4 版起,Edge Microgateway 支援這項產品 此外還會從 0 自動調整資源配置 您完全不必調整資源調度設定

偵錯與疑難排解

連線至偵錯工具

您可以搭配偵錯工具執行 Edge Microgateway,例如 node-inspector。這對於使用者 排解自訂外掛程式的問題及偵錯

  1. 以偵錯模式重新啟動 Edge Microgateway。做法是將 DEBUG=* 加入 start 指令的開頭:
    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。只要複製用戶端金鑰 (也稱為 Client ID) 值,即可取得 API 金鑰 。

快取金鑰

API 金鑰會交換供快取的不記名權杖。您可以透過 對 Edge 發出的傳入要求上的 Cache-Control: no-cache 標頭 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"

如需進一步瞭解如何搭配使用 API 金鑰與 Proxy 要求,請參閱 Secure Edge Microgateway

啟用上游回應代碼

根據預設,在下列情況下,oauth 外掛程式只會傳回 4xx 錯誤狀態碼。 則表示回應並非 200 狀態。您可以變更此行為 會根據錯誤傳回確切的 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:以主體參數的形式傳送憑證

請在網址中替換您的機構和環境名稱。以及 替換從 Apigee 上開發人員應用程式取得的消費端 ID 和用戶端密鑰值 client_idclient_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:透過基本驗證標頭傳送憑證

以「基本驗證」標頭的形式傳送用戶端憑證, 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 回應。請注意,tokenaccess_token 屬性。您可以擇一使用。
{
"token": "eyJraWQiOiIxIiwidHlwIjoi",
"access_token": "eyJraWQiOiIxIiwid",
"token_type": "bearer",
"expires_in": "108000"
}

如何取得更新權杖

如要取得更新權杖,請向/token edgemicro-auth Proxy。您必須透過 password 發出這個 API 呼叫 授權類型。下列步驟會逐步完成設定程序。

  1. 透過 /token API 取得存取權和更新權杖。請注意, 授權類型為 password
    curl -X POST \
      https://your_organization-your_environment.apigee.net/edgemicro-auth/token \
      -H 'Content-Type: application/json' \
      -d '{
       "client_id":"mpK6l1Bx9oE5zLdifoDbF931TDnDtLq",
       "client_secret":"bUdDcFgv3nXffnU",
       "grant_type":"password",
       "username":"mpK6lBx9RoE5LiffoDbpF931TDnDtLq",
       "password":"bUdD2FvnMsXffnU"
    }'

    API 會傳回存取權杖和更新權杖。回應看起來與 :

    {
        "token": "your-access-token",
        "access_token": "your-access-token",
        "token_type": "bearer",
        "expires_in": "108000",
        "refresh_token": "your-refresh-token",
        "refresh_token_expires_in": "431999",
        "refresh_token_issued_at": "1562087304302",
        "refresh_token_status": "approved"
    }
  2. 您現在可以呼叫 相同 API 的 /refresh 端點。例如:
    curl -X POST \
      https://willwitman-test.apigee.net/edgemicro-auth/refresh \
      -H 'Content-Type: application/json' \
      -d '{
       "client_id":"mpK6l1Bx9RoE5zLifoDbpF931TDnDtLq",
       "client_secret":"bUdDc2Fv3nMXffnU",
       "grant_type":"refresh_token",
       "refresh_token":"your-refresh-token"
    }'

    API 會傳回新的存取權杖。回應看起來會像這樣:

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

永久監控

Forever 是一個 Node.js 工具 如果程序當機或發生錯誤,會自動重新啟動 Node.js 應用程式。邊緣 您可以設定 Microgateway 提供的 forever.json 檔案,藉此控制 以及 Edge Microgateway 應重新啟動的間隔時間。這個檔案會設定 一律稱為「永久監控」的服務,會永久管理 編寫程式

您可以在 Edge Microgateway 根目錄安裝中找到 forever.json 檔案 目錄。詳情請參閱 Edge Microgateway 安裝在哪裡。如要進一步瞭解設定選項,請參閱

edgemicro forever 指令包含旗標,可讓您指定 forever.json 檔案 (-f 旗標),並啟動/停止永久監控 程序 (-a 旗標)。例如:

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

詳情請參閱 CLI 參考資料中的永久監控

指定設定檔端點

如果您同時執行多個 Edge Microgateway 執行個體,您可能會想管理各個執行個體的設定 從單一位置收集資訊方法是指定 Edge Micro 可以存取的 HTTP 端點 下載設定檔您可以在啟動 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

您可以執行完全中斷與任何連線的 Edge Microgateway Apigee Edge 依附元件。這個情境稱為獨立模式,可讓您執行及測試 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 是「org」您使用的設定檔名稱。
    • $ENV 是「env」您在設定檔所使用的 名稱。
    • $LOCAL_PROXY_NAME 是要建立的本機 Proxy 名稱。別擔心!您可以使用 任意名稱
    • $LOCAL_PROXY_VERSION 是 Proxy 的版本編號。
    • $TARGET_URL 是 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 API 呼叫的標頭。在下一節中,您將取得允許 API 呼叫的 JWT 略過錯誤

範例:取得授權權杖

以下範例說明如何在 Apigee Edge (edgemicro-auth/jwkPublicKeys) 上從 Edge Microgateway JWT 端點取得 JWT。 執行 Edge Microgateway 的標準設定和設定時,系統會部署這個端點。 如要從 Apigee 端點取得 JWT,您必須先執行標準 Edge Microgateway 設定,並且 連線至網際網路這裡會使用 Apigee 端點 並非強制規定您可以視需要使用其他 JWT 權杖端點。若輸入 JWT,則必須使用 為該端點提供的 API

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

  1. 您必須執行一個標準 Edge Microgateway 的設定與設定,以便部署 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例如:

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

在此情況下:

  • your_org 是您先前的 Apigee 機構名稱 已設定 Edge Microgateway
  • 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 名稱、basepath 及目標網址 啟動微門接著,向微閘道發出的 API 呼叫會傳送至目標 本機 Proxy 的網址。在所有其他情況下,本機 Proxy 模式的運作方式都與執行中 Edge Microgateway 正常模式中。驗證作業的運作方式與遽增率相同 逮捕和配額限制、自訂外掛程式等

用途和範例

如果只需要將單一 Proxy 連結至 Edge Microgateway,本機 Proxy 模式就相當實用 執行個體。舉例來說,您可以將 Edge Microgateway 插入 Kubernetes 做為補充資訊 Proxy,其中 微型閘道與服務均在單一 Pod 中運作 以及透過隨附服務安裝的容器下圖說明 Edge 的這個架構 Microgateway 功能在 Kubernetes 叢集中可做為補充 Proxy。每個微閘道執行個體 附加至隨附服務上的單一端點:

Edgemicro 做為補充資訊

這種架構的優點之一是 Edge Microgateway 提供 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。這個 Proxy 是在執行 edgemicro configure 時自動部署。
    • 您「必須」提供資源路徑。Apigee 建議將此路徑新增至 產品:/**。詳情請參閱「設定資源路徑的行為」。另請參閱建立 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":""
}

使用同步處理工具

本節說明如何使用同步處理工具 (這項選用功能 提升 Edge Microgteway 的韌性 ,從 Apigee Edge 擷取設定資料,並將其寫入本機 Redis 資料庫。取代為 執行中的同步器執行個體、在不同節點上執行的其他 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 流量所需的設定資料。 這個同步處理器可讓所有 Edge Microgateway 都能 在不同節點上執行的執行個體,可正常啟動並保持保持同步 Edge Microgateway 和 Apigee Edge 之間的網際網路連線中斷。

同步處理器是經過特別設定的 Edge Microgateway 執行個體。只是用途 就是輪詢 Apigee Edge (時間可以設定)、擷取設定資料 寫入本機 Redis 資料庫同步器執行個體本身無法處理 API Proxy 流量在不同節點上運作的其他 Edge Microgateway 執行個體 設為從 Redis 資料庫擷取設定資料,而不是從 Apigee 擷取 邊緣由於所有微型閘道執行個體都會從 因此能啟動及處理 API 要求 服務中斷

設定同步器執行個體

將以下設定新增至 的 org-env/config.yaml 檔案 您要做為同步器使用的 Edge Microgateway 安裝:

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 Proxy 流量的一般微型閘道執行個體。不過,您將 以便從 Redis 資料庫取得設定資料 Apigee Edge。

將以下設定新增至每個其他 Edge Microgateway 節點的 org-env/config.yaml 檔案。請注意,synchronizerMode 屬性設為 0。這項屬性會將執行個體設為正常作業 處理 API Proxy 流量的 Edge Microgateway 執行個體,而執行個體將取得 設定資料

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 執行個體會從 而非 Apigee Edge 中的 Redis 資料庫Redis 資料庫必須相同 設定同步處理器以寫入如果沒有 Redis 資料庫 如果資料庫空白,微閘道會尋找現有的 cache-config.yaml 檔案進行配置

如果為 false (預設值),Edge Microgateway 執行個體會從 Apigee Edge。

edgemicro.config_change_poll_interval 時間間隔 (以秒為單位) 指定同步處理器從 Apigee Edge 中提取資料的輪詢時間間隔。