您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
Edge Microgateway 2.5.x 版
本主題將說明如何管理及設定 Edge Microgateway。
如果你連上網際網路,正在升級 Edge Microgateway
- 執行下列
npm
指令,升級至最新版 Edge Microgateway:npm upgrade edgemicro -g
如要升級至特定版本的 Edge Microgateway,您必須在升級指令中指定「版本號碼」。如果未指定版本號碼,系統會安裝最新版本。舉例來說,如要升級至 2.5.26 版,請使用下列指令:
npm upgrade edgemicro@2.5.26 -g
- 查看版本號碼。舉例來說,如果安裝的版本是 2.5.26:
edgemicro --version current nodejs version is v8.9.0 current edgemicro version is 2.5.26
- 最後,請升級至最新版 edgemicro-auth Proxy:
edgemicro upgradeauth -o org_name -e env_name -u username
變更設定
需要瞭解的設定檔包括:
- 預設系統設定檔
- 新初始化 Edge Microgateway 執行個體的預設設定檔
- 運作中執行個體的動態設定檔
本節將探討這些檔案,以及變更這些檔案的須知。
預設系統設定檔
安裝 Edge Microgateway 後,預設的系統設定檔會放在這裡:
prefix/lib/node_modules/edgemicro/config/default.yaml
其中 prefix 是 npm
前置字串目錄。如果找不到這個目錄,請參閱「
Edge Microgateway 安裝位置」一文。
如果變更系統設定檔,您必須重新初始化、重新設定,並重新啟動 Edge Microgateway:
edgemicro initedgemicro configure [params]
edgemicro start [params]
新初始化 Edge Microgateway 執行個體的預設設定檔
當您執行 edgemicro init
時,系統設定檔 (如前所述) default.yaml
會放在 ~/.edgemicro
目錄中。
如果您變更 ~/.edgemicro
中的設定檔,必須重新設定並重新啟動 Edge Microgateway:
edgemicro stopedgemicro configure [params]
edgemicro start [params]
運作中執行個體的動態設定檔
執行 edgemicro configure [params]
時,系統會在 ~/.edgemicro
中建立動態設定檔。這個檔案是依據以下模式命名:org-env-config.yaml
,其中 org 和 env 是您的 Apigee Edge 機構和環境名稱。您可以使用這個檔案變更設定,然後在零停機的情況下重新載入檔案。舉例來說,如果您新增並設定外掛程式,則可重新載入設定,而不會產生任何停機時間。如下所述。
如果 Edge Microgateway 正在執行 (零停機時間選項):
- 重新載入 Edge Microgateway 設定:
edgemicro reload -o org_name -e env_name -k key -s secret
在此情況下:
- org_name 是您的 Edge 機構名稱 (您必須是機構管理員)。
- env_name 是機構中的環境 (例如「test」或「prod」)。
- key 是設定指令先前傳回的金鑰。
- secret 是設定指令先前傳回的金鑰。
範例說明
edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \ -s 05c14356e42ed1...4e34ab0cc824
如果 Edge Microgateway 已停止:
- 重新啟動 Edge Microgateway:
edgemicro start -o org_name -e env_name -k key -s secret
在此情況下:
- org_name 是您的 Edge 機構名稱 (您必須是機構管理員)。
- env_name 是貴機構的環境 (例如「test」或「prod」)。
- key 是設定指令先前傳回的金鑰。
- secret 是設定指令先前傳回的金鑰。
例如:
edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \ -s 05c1435...e34ab0cc824
以下是設定檔範例。如要進一步瞭解設定檔設定,請參閱 Edge Microgateway 設定參考資料。
edge_config: bootstrap: >- https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test jwt_public_key: 'https://docs-test.apigee.net/edgemicro-auth/publicKey' managementUri: 'https://api.enterprise.apigee.com' vaultName: microgateway authUri: 'https://%s-%s.apigee.net/edgemicro-auth' baseUri: >- https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s bootstrapMessage: Please copy the following property to the edge micro agent config keySecretMessage: The following credentials are required to start edge micro products: 'https://docs-test.apigee.net/edgemicro-auth/products' edgemicro: port: 8000 max_connections: 1000 max_connections_hard: 5000 config_change_poll_interval: 600 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24 plugins: sequence: - oauth headers: x-forwarded-for: true x-forwarded-host: true x-request-id: true x-response-time: true via: true oauth: allowNoAuthorization: false allowInvalidAuthorization: false verify_api_key_url: 'https://docs-test.apigee.net/edgemicro-auth/verifyApiKey' analytics: uri: >- https://edgemicroservices-us-east-1.apigee.net/edgemicro/axpublisher/organization/docs/environment/test
設定環境變數
需要用於 Edge 機構和環境值的指令列介面指令,以及啟動 Edge Microgateway 所需的金鑰和密鑰,可以儲存在這些環境變數中:
EDGEMICRO_ORG
EDGEMICRO_ENV
EDGEMICRO_KEY
EDGEMICRO_SECRET
您不一定要設定這些變數。設定這些設定後,在使用指令列介面 (CLI) 設定及啟動 Edge Microgateway 時,不必指定這些值。
在 Edge Microgateway 伺服器上設定 SSL
您可以將 Microgateway 伺服器設為使用 SSL。舉例來說,在已設定 SSL 的情況下,您可以使用「https」通訊協定,透過 Edge Microgateway 呼叫 API,如下所示:
https://localhost:8000/myapi
如要在 Microgateway 伺服器上設定 SSL,請按照下列步驟操作:
- 使用 openssl 公用程式或任何您偏好的方法產生或取得 SSL 憑證和金鑰。
- 在 Edge Microgateway 設定檔中加入
edgemicro:ssl
屬性。如需完整的選項清單,請參閱下表。舉例來說:
edgemicro: ssl: key: <absolute path to the SSL key file> cert: <absolute path to the SSL cert file> passphrase: admin123 #option added in v2.2.2 rejectUnauthorized: true #option added in v2.2.2 requestCert: true
- 重新啟動 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 |
pfx 檔案的路徑,該檔案含有用戶端的私密金鑰、憑證和 CA 憑證 (以 PFX 格式表示)。 |
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
以下列出所有支援的用戶端選項:
選項 | 說明 |
---|---|
pfx |
pfx 檔案的路徑,該檔案含有用戶端的私密金鑰、憑證和 CA 憑證 (以 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 和記錄檔。
如何設定記錄層級
您可以設定這些記錄層級:info、warn 和 error。建議提供資訊層級。它會記錄所有 API 要求與回應,而且預設為預設。
如何變更記錄間隔
您可以在 Edge Microgateway 設定檔中設定這些間隔。另請參閱「變更設定」。
可設定的屬性如下:
- stats_log_interval:(預設值:60) 統計資料記錄寫入 API 記錄檔時,以秒為單位。
- rotate_interval:(預設值:24) 記錄檔輪替時以小時為單位。例如:
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: info dir: /var/tmp stats_log_interval: 60 rotate_interval: 24
良好的記錄檔維護做法
隨著記錄檔資料逐漸累積,Apigee 建議您採用以下做法:
- 由於記錄檔可能會變得相當大,因此請確保記錄檔目錄有足夠的空間。請參閱以下各節記錄檔儲存位置和如何變更預設記錄檔目錄。
- 每週至少將記錄檔刪除或移動至獨立的封存目錄一次。
- 如果政策是刪除記錄檔,您可以使用 CLI 指令
edgemicro log -c
移除 (清理) 較舊的記錄檔。
記錄檔命名慣例
每個 Edge Microgateway 執行個體都會產生三種類型的記錄檔:
- api - 記錄透過 Edge Microgateway 傳送的所有要求與回應。API 計數器 (統計資料) 和錯誤也會記錄到這個檔案。
- err:記錄傳送至 stderr 的所有內容。
- out:記錄傳送至 stdout 的內容。
命名慣例如下:
edgemicro-<Host Name>-<Instance ID>-<Log Type>.log
例如:
edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log edgemicro-mymachine-local-MTQzNTg1NDMODAyMQ-err.log edgemicro-mymachine-local-mtqzntgndmxodaymq-out.log
關於記錄檔內容
已新增至 2.3.3 版
根據預設,記錄服務會忽略已下載的 Proxy、產品和 JSON Web Token (JWT) 的 JSON 檔案。如要將這些物件輸出至記錄檔,請在啟動 Edge Microgateway 時設定 DEBUG=*
。例如:
DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456
「api」記錄檔的內容
「api」記錄檔包含透過 Edge Microgateway 提出的要求與回應相關流程的詳細資訊。「api」記錄檔的名稱如下:
edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log
針對每項向 Edge Microgateway 發出的要求,「api」記錄檔中會擷取四個事件:
- 來自用戶端的要求
- 傳送至目標的傳出要求
- 來自目標的傳入回應
- 回覆用戶端的傳出回應
每個獨立項目都以簡寫標記表示,有助於讓記錄檔更精簡。以下提供四個項目範例,分別代表這四個事件。在記錄檔中看起來會像這樣 (行號僅供文件中的參照之用,不會顯示在記錄檔中)。
(1) 1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0 (2) 1436403888665 info treq m=GET, u=/, h=127.0.0.18080, i=0 (3) 1436403888672 info tres s=200, d=7, i=0 (4) 1436403888676 info res s=200, d=11, i=0
以下逐一為您介紹:
1. 來自用戶端的傳入要求範例:
1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
- 1436403888651 - Unix 日期戳記
- info - 取決於背景資訊。這可能是資訊、警告或錯誤,視記錄層級而定。可以是統計資料記錄的統計資料、警告的警告或錯誤錯誤。
- req:用於識別事件。在這種情況下,請從用戶端提出要求。
- m - 要求中使用的 HTTP 動詞。
- u - 基本路徑後的網址部分。
- h - Edge Microgateway 正在監聽的主機和通訊埠編號。
- r:產生用戶端要求的遠端主機和通訊埠。
- i - 要求 ID。這四個活動項目都會共用這個 ID。每個要求都會獲得一組不重複的要求 ID。依據要求 ID 找出相關聯的記錄檔記錄,能讓您深入瞭解目標的延遲時間。
- d - 自 Edge Microgateway 收到要求後的時間長度,以毫秒為單位。在上述範例中,系統在 7 毫秒 (第 3 行) 後收到目標 0 的要求回應,並在額外 4 毫秒 (第 4 行) 後將回應傳送至用戶端。換句話說,要求的總延遲時間為 11 毫秒,其中 7 毫秒是由目標佔用 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。這四個事件項目都會共用這個 ID。
3.來自目標的傳入回應範例
1436403888672 info tres s=200, d=7, i=0
1436403888651 - Unix 日期戳記
- info - 取決於背景資訊。這可能是資訊、警告或錯誤,視記錄層級而定。可以是統計資料記錄的統計資料、警告的警告或錯誤錯誤。
- tres - 用於識別事件。在本例中是目標回應。
- s:HTTP 回應狀態。
- d - 以毫秒為單位的時間長度。目標執行 API 呼叫所需的時間。
- i:記錄項目的 ID。這四個事件項目都會共用這個 ID。
4.給用戶端的傳出回應範例
1436403888676 info res s=200, d=11, i=0
1436403888651 - Unix 日期戳記
- info - 取決於背景資訊。這可能是資訊、警告或錯誤,視記錄層級而定。可以是統計資料記錄的統計資料、警告的警告或錯誤錯誤。
- res:用於識別事件。在這種情況下,應回應用戶端。
- s:HTTP 回應狀態。
- d - 以毫秒為單位的時間長度。這是 API 呼叫花費的總時間,包括目標 API 耗費的時間,以及 Edge Microgateway 本身花費的時間。
- i:記錄項目的 ID。這四個事件項目都會共用這個 ID。
記錄檔排程
記錄檔會依 rotate_interval 設定屬性指定的時間間隔輪替。項目會持續新增至相同的記錄檔,直到輪替間隔到期為止。不過,每次重新啟動 Edge Microgateway 時,系統都會收到新的 UID,並以這個 UID 建立一組新的記錄檔。另請參閱良好的記錄檔維護做法一文。
錯誤訊息
部分記錄項目會包含錯誤訊息。為協助您找出發生錯誤的位置和原因,請參閱 Edge Microgateway 錯誤參考資料。
Edge Microgateway 設定參考資料
設定檔的位置
本節所述的設定屬性位於 Edge Microgateway 設定檔中。另請參閱「變更設定」一文。
Edge_config 屬性
這些設定是用來設定 Edge Microgateway 執行個體與 Apigee Edge 之間的互動。
- bootstrap:(預設值:無) 指向在 Apigee Edge 上執行的 Edge Microgateway 專屬服務的網址。Edge Microgateway 會使用這項服務與 Apigee Edge 通訊。當您執行指令來產生公開/私密金鑰組時,系統會傳回這個網址:
edgemicro genkeys
。詳情請參閱「設定及設定 Edge Microgateway」。 - jwt_public_key:(預設值:無) 指向在 Apigee Edge 上部署的 Edge Microgateway Proxy 的網址。這個 Proxy 會做為驗證端點,向用戶端發出已簽署的存取權杖。當您執行部署 Proxy 的指令時,系統會傳回這個網址:edgemicro configuration。詳情請參閱「設定及設定 Edge Microgateway」。
Edgemicro 屬性
這些設定會調整 Edge Microgateway 程序。
- port:(預設值:8000) Edge Microgateway 程序監聽的通訊埠編號。
- max_connections:(預設值:-1) 指定 Edge Microgateway 可接收的同時連入連線數量上限。如果超過這個數字,系統會傳回以下狀態:
res.statusCode = 429; // Too many requests
- max_connections_hard:(預設值:-1) 在關閉連線前,Edge Microgateway 可接收的同時要求數量上限。這項設定的用途是防範阻斷服務攻擊。建議設為大於 max_connections 的數字。
-
logging:
-
level:(預設值:錯誤)
- info - 記錄透過 Edge Microgateway 執行個體傳輸的所有要求和回應。
- warn - 僅記錄警告訊息。
- error - 僅記錄錯誤訊息。
- dir:(預設值:/var/tmp) 儲存記錄檔的目錄。
- stats_log_interval:(預設值:60) 統計資料記錄寫入 API 記錄檔時,以秒為單位。
- rotate_interval:(預設值:24) 記錄檔輪替時以小時為單位。
-
level:(預設值:錯誤)
- 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: (預設值:false) 設為 true 即可關閉自動變更輪詢。
- request_timeout:設定目標要求的逾時。逾時時間設為以秒為單位。如果逾時,Edge Microgateway 會傳回 504 狀態碼的回應。(新增 2.4.x 版)
標頭屬性
這些設定可指定特定 HTTP 標頭的處理方式。
- x-forwarded-for:(default: true) 設為 false,即可避免將 X 前的標頭傳遞至目標。請注意,如果要求中包含 x-forward-ed 標頭,該標頭的值會設為 Edge Analytics 中的 client-ip 值。
- x-forwarded-host:(default: true) 設為 false,即可避免將 x 轉寄的主機標頭傳遞至目標。
- x-request-id:(default: true) 設為 false,可防止 x-request-id 標頭傳遞至目標。
- x-response-time:(預設值:True) 設為 false,可防止 x-response-time 標頭傳遞至目標。
- via:(預設值:true) 設為 false,防止透過標頭傳遞至目標。
OAuth 屬性
這些設定可控管 Edge Microgateway 用戶端驗證的執行方式。
- allowNoAuthorization:(預設值:false) 如果設為 true,API 呼叫即可通過 Edge Microgateway,而且完全不需要授權標頭。將此欄位設為 false,即可要求使用授權標頭 (預設值)。
- allowInvalidAuthorization:(預設值:false) 如果設為 true,如果「Authorization」標頭中傳遞的權杖無效或已過期,系統就會允許 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 都必須包含包含不記存取權杖的授權標頭。這項設定可讓您僅允許 OAuth 安全性模型 (同時維持回溯相容性)。(新增 2.4.x)
- allowAPIKeyOnly:如果設為 true,每個 API 都必須包含包含 API 金鑰的 x-api-key 標頭 (或自訂位置)。允許您僅允許 API 金鑰安全性模型 (同時保有回溯相容性)。(已新增 2.4.x)
- gracePeriod:這個參數可防止系統時鐘與 JWT 授權權杖指定的「Not 前」(nbf) 或「Issued At (iat)」時間之間有些微差異而導致錯誤。請將這個參數設為秒數,以允許這類差異。(新增 2.5.7)
外掛程式專屬屬性
如要進一步瞭解每個外掛程式可設定的屬性,請參閱使用外掛程式。
篩選 Proxy
您可以篩選 Edge Microgateway 執行個體要處理的微閘道感知 Proxy。
Edge Microgateway 啟動時,會下載相關聯的機構中的所有微閘道感知 Proxy。使用以下設定來限制微閘道可處理的 Proxy。舉例來說,這項設定會將微閘道程序的 Proxy 處理為三個:edgemicro_proxy-1
、edgemicro_proxy-2
和 edgemicro_proxy-3
:
proxies: - edgemicro_proxy-1 - edgemicro_proxy-2 - edgemicro_proxy-3
設定數據分析推送頻率
您可以使用這些設定參數,控管 Edge Microgateway 傳送數據分析資料至 Apigee 的頻率:
- bufferSize (選用):緩衝區在開始刪除最舊的記錄之前,緩衝區可保留的數據分析記錄數量上限。預設:10000
- batchSize (選用):傳送至 Apigee 的數據分析記錄批次大小上限。預設:500
- flushInterval (選填):每次傳送至 Apigee 的數據分析記錄批次之間的毫秒數。預設:5000
例如:
analytics: bufferSize: 15000 batchSize: 1000 flushInterval: 6000
遮蓋數據分析資料
下列設定會防止要求路徑資訊顯示在 Edge 數據分析中。將以下內容新增至 Migateway 設定,以遮蓋要求 URI 和/或要求路徑。請注意,URI 由要求的主機名稱和路徑部分組成,
analytics: mask_request_uri: 'string_to_mask' mask_request_path: 'string_to_mask'
在 Edge Analytics 中區隔 API 呼叫
您可以設定數據分析外掛程式來隔離特定 API 路徑,讓該路徑在 Edge Analytics 資訊主頁中顯示為獨立的 Proxy。舉例來說,您可以在資訊主頁中區隔健康狀態檢查 API,以免與實際的 API Proxy 呼叫混淆。在 Analytics (分析) 資訊主頁中,獨立的 Proxy 遵循下列命名模式:
edgemicro_proxyname-health
下圖顯示 Analytics (分析) 資訊主頁中的兩個獨立 Proxy:edgemicro_hello-health
和 edgemicro_mock-health
:
您可以使用這些參數,將 Analytics (分析) 資訊主頁中的相對路徑和絕對路徑區分為個別 Proxy:
- relativePath (選用):指定 Analytics (分析) 資訊主頁中隔離的相對路徑。舉例來說,如果指定
/healthcheck
,所有包含路徑/healthcheck
的 API 呼叫都會在資訊主頁中顯示為edgemicro_proxyname-health
。請注意,這個標記會忽略 Proxy 基本路徑。如要根據完整路徑 (包括基本路徑) 隔離,請使用proxyPath
旗標。 - proxyPath (選用):指定在數據分析資訊主頁中隔離的完整 API Proxy 路徑 (包括 Proxy 基本路徑)。舉例來說,如果您指定
/mocktarget/healthcheck
,其中/mocktarget
是 Proxy 基本路徑,則所有具備路徑/mocktarget/healthcheck
的 API 呼叫都會在資訊主頁中顯示為edgemicro_proxyname-health
。
舉例來說,在下列設定中,包含 /healthcheck
的所有 API 路徑都會由數據分析外掛程式分開。也就是說,/foo/healthcheck
和 /foo/bar/healthcheck
會在數據分析資訊主頁中獨立為名為 edgemicro_proxyname-health
的 Proxy。
analytics: uri: >- https://xx/edgemicro/ax/org/docs/environment/test bufferSize: 100 batchSize: 50 flushInterval: 500 relativePath: /healthcheck
在下列設定中,系統會針對所有具備 Proxy 路徑 /mocktarget/healthcheck
的 API,在數據分析資訊主頁中將其區隔為名為 edgemicro_proxyname-health
的獨立 Proxy。
analytics: uri: >- https://xx/edgemicro/ax/org/docs/environment/test bufferSize: 100 batchSize: 50 flushInterval: 500 proxyPath: /mocktarget/healthcheck
在公司防火牆後方設定 Edge Microgateway
支援的 2.4.x 版
如果 Edge Microgateway 安裝在防火牆後方,閘道可能無法與 Apigee Edge 通訊。在這種情況下,您可以考慮採用以下兩種做法:
選項 1:
第一個選項是在 Migateway 設定檔中將 Edgemicro: Proxy_tunnel 選項設為 true:
edge_config: proxy: http://10.224.16.85:3128 proxy_tunnel: true
當 proxy_tunnel 為 true 時,Edge Microgateway 就會使用 HTTP CONNECT 方法,透過單一 TCP 連線通道 HTTP 要求。(如果設定 Proxy 的環境變數已啟用 TLS,也會發生同樣的情況)。
選項 2:
第二個選項是在 Migateway 設定檔中指定 Proxy,並將 Proxy_tunnel 設為 false。例如:
edge_config: proxy: http://10.224.16.85:3128 proxy_tunnel: false
在此情況下,您可以設定下列變數,針對要使用的每個 HTTP Proxy 控制主機,或是控制不應處理 Edge Microgateway Proxy 的主機:HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY。
您可以將 NO_PROXY 設為以逗號分隔的網域清單,其中 Edge Microgateway 不應透過 Proxy 進行 Proxy 處理。例如:
export NO_PROXY='localhost,localhost:8080'
將 HTTP_PROXY 和 HTTPS_PROXY 設為 HTTP Proxy 端點 Edge Microgateway 可將訊息傳送至 HTTP Proxy 端點。例如:
export HTTP_PROXY='http://localhost:3786' export HTTPS_PROXY='https://localhost:3786'
如要進一步瞭解這些變數,請參閱 https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables
另請參閱
如何在 Apigee 社群中 在公司防火牆後方設定 Edge Microgateway。
在可感知微閘道的 Proxy 中使用萬用字元
您可以在 edgemicro_* (適用於 Microgateway 感知) Proxy 的基本路徑中使用一或多個「*」萬用字元。舉例來說,/team/*/members 的基本路徑可讓用戶端呼叫 https://[host]/team/blue/members 和 https://[host]/team/green/members,而不需要建立新的 API Proxy 來支援新團隊。請注意,系統不支援 /**/
。
重要事項:Apigee 不支援使用萬用字元「*」做為基本路徑的第一個元素。例如,系統不支援 /*/
搜尋。
輪替 JWT 金鑰
初次產生 JWT 後,有時可能需要變更儲存在 Edge 加密 KVM 中的公開/私密金鑰組。此產生新金鑰組的程序稱為金鑰輪替。
Edge Microgateway 如何使用 JWT
JSON Web Token (JWT) 是 RFC7519 中所述的權杖標準。JWT 提供一種簽署一組憑證附加資訊的方法,可由 JWT 的接收者可靠地驗證。
Edge Microgateway 運用 JWT 做為 OAuth 安全性的不記名權杖。為 Edge Microgateway 產生 OAuth 權杖之後,您會收到 JWT。接著,您就能在 API 呼叫的「授權」標頭中使用 JWT。例如:
curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"
產生新的 JWT
您可以使用 edgemicro token
指令或 API 產生 Edge Microgateway 的 JWT。例如:
edgemicro token get -o docs -e test -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy
這個指令會要求 Apigee Edge 產生 JWT,接著就能用於驗證 API 呼叫。-i
和 -s
參數是 Apigee Edge 機構中開發人員應用程式的用戶端 ID 和密鑰值。
您也可以使用管理 API 產生 JWT:
curl -i -X POST "http://org-env.apigee.net/edgemicro-auth/token" \ -H "Content-Type: application/json" \ -d '{ "client_id": "your consumer key", "client_secret": "your consumer secret", "grant_type": "client_credentials" }'
在此情況下:
- org 是您的 Edge 機構名稱 (您必須是機構管理員)。
- env 是貴機構的環境 (例如「test」或「prod」)。
- client_id 是您之前建立的開發人員應用程式中的消費者 ID。
- client_secret 是您先前建立的開發人員應用程式中的用戶端密鑰。
什麼是金鑰輪替?
初次產生 JWT 後,有時可能需要變更儲存在 Edge 加密 KVM 中的公開/私密金鑰組。此產生新金鑰組的程序稱為金鑰輪替。輪替金鑰時,系統會產生新的私密/公開金鑰組,並儲存在 Apigee Edge 機構/環境中的「微閘道」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 時,系統將使用新的公開金鑰進行驗證。如果驗證失敗,系統會繼續使用舊的公開金鑰,直到 30 分鐘後失效。這樣一來,您就可以「輪替」金鑰,而不會立即影響 API 流量。
如何輪替金鑰
本節說明如何輪替金鑰。
如果您設定的是 2.5.2 版之前的 Edge Microgateway 執行個體
如果您在 2.5.2 版之前設定 Edge Microgateway 執行個體,則必須執行下列兩項指令,才能升級 KVM 和驗證政策:
upgradekvm -o org -e env -u username
如要進一步瞭解這個指令,請參閱升級 KVM 一文。
接下來的指令會升級在設定 Edge Microgateway 時部署至 Apigee 機構的 edgemicro-oauth Proxy。這個 Proxy 會提供產生權杖所需的服務。
upgradeauth -o org -e env -u username
如要進一步瞭解這個指令,請參閱升級 Edgemicro-auth Proxy。
輪替金鑰
請在 ~/.edgemicro/org-env-config.yaml
檔案中加入以下這行程式碼,您必須在其中指定和設定微閘道時所使用的機構和環境:
jwk_public_keys: 'https://org-env.apigee.net/edgemicro-auth/jwkPublicKeys'
執行金鑰輪替指令來輪替金鑰。(如要進一步瞭解這個指令,請參閱輪替金鑰)。
edgemicro rotatekey -o org -e env -u username -k kid_value
例如:
edgemicro rotatekey -o jdoe -e test -u jdoe@google.com -k 2 current nodejs version is v6.9.1 current edgemicro version is 2.5.7 password: Checking if private key exists in the KVM... Checking for certificate... Found Certificate Generating New key/cert pair... Extract new public key Key Rotation successfully completed!
-k
參數會指定金鑰 ID (kid)。這個 ID 是用來比對特定鍵,Edge Microgateway 能在金鑰輪替期間,使用這個值選擇一組金鑰。詳情請參閱 JSON Web Key 規格 4.5 節。
金鑰輪替後,Edge 會將多個金鑰傳回 Edge Microgateway。請注意,在以下範例中,每個鍵都有專屬的「kid」(金鑰 ID) 值。然後使用這些金鑰來驗證授權權杖。如果權杖驗證失敗,微閘道會檢查金鑰組合中是否有較舊的金鑰,並嘗試使用該金鑰。傳回的金鑰格式為 JSON Web Key (JWK)。如要進一步瞭解這個格式,請參閱 RFC 7517。
{ "keys": [ { "kty": "RSA", "n": "nSl7R_0wKLiWi6cO3n8aOJwYGBtinq723Jgg8i7KKWTSTYoszOjgGsJf_MX4JEW1YCScwpE5o4o8ccQN09iHVTlIhk8CNiMZNPipClmRVjaL_8IWvMQp1iN66qy4ldWXzXnHfivUZZogCkBNqCz7VSC5rw2Jf57pdViULVvVDGwTgf46sYveW_6h8CAGaD0KLd3vZffxIkoJubh0yMy0mQP3aDOeIGf_akeZeZ6GzF7ltbKGd954iNTiKmdm8IKhz6Y3gLpC9iwQ-kex_j0CnO_daHl1coYxUSCIdv4ziWIeM3dmjQ5_2dEvUDIGG6_Az9hTpNgPE5J1tvrOHAmunQ", "e": "AQAB", "kid": "2" }, { "kty": "RSA", "n": "8BKwzx34BMUcHwTuQtmp8LFRCMxbkKg_zsWD6eOMIUTAsORexTGJsTy7z-4aH0wJ3fT-3luAAUPLBQwGcuHo0P1JnbtPrpuYjaJKSZOeIMOnlryJCspmv-1xG4qAqQ9XaZ9C97oecuj7MMoNwuaZno5MvsY-oi5B_gqED3vIHUjaWCErd4reONyFSWn047dvpE6mwRhZbcOTkAHT8ZyKkHISzopkFg8CD-Mij12unxA3ldcTV7yaviXgxd3eFSD1_Z4L7ZRsDUukCJkJ-8qY2-GWjewzoxl-mAW9D1tLK6qAdc89yFem3JHRW6L1le3YK37-bs6b2a_AqJKsKm5bWw", "e": "AQAB", "kid": "1" } ] }
篩選已下載的 Proxy
根據預設,Edge Microgateway 會下載 Edge 機構中開頭為「edgemicro_」的所有 Proxy。您可以變更這項預設值,下載名稱符合模式的 Proxy。
- 開啟 Edge Micro 設定檔:
~/.edgemicro/org-env-config.yaml
- 在 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 支援這項產品設定。
偵錯和疑難排解
連線至偵錯工具
您可以透過偵錯工具執行 Edge Microgateway,例如節點檢查器。這有助於解決自訂外掛程式的問題及偵錯。
- 以偵錯模式重新啟動 Edge Microgateway。方法是在
start
指令的開頭加上DEBUG=*
。例如:DEBUG=* edgemicro start -o myorg -e test -k db4e9e8a95aa7fabfdeacbb1169d0a8cbe42bec19c6b98129e02 -s 6e56af7c1b26dfe93dae78a735c8afc9796b077d105ae5618ce7ed
- 啟動偵錯工具,並將其設為監聽偵錯程序的通訊埠編號。
- 您現在可以逐步查看 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 要求搭配使用,請參閱 安全 Edge Microgateway。
使用 OAuth2 權杖安全性
本節說明如何取得 OAuth2 存取權杖及更新權杖。存取權杖的用途是透過微閘道執行安全的 API 呼叫。重新整理權杖會用來取得新的存取權杖。
如何取得存取權杖
本節說明如何使用 edgemicro-auth
Proxy 取得存取權杖。
您也可以使用 edgemicro token
CLI 指令取得存取權杖。如要進一步瞭解 CLI,請參閱管理權杖。
API 1
將網址替換成您的機構和環境名稱,並將 client_id 和 client_secret 主體參數替換成在 Apigee Edge 上從開發人員應用程式取得的「Consumer Id」和「Consumer 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
(v2.5.31 已新增) 傳送用戶端憑證做為基本驗證標頭,並將grant_type
做為表單參數傳送。另外,RFC 6749:OAuth 2.0 授權架構中也會討論這個指令表單。http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \ -d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"
輸出內容範例
API 會傳回 JSON 回應。請注意,token
和 access_token
屬性沒有任何差異。您可以擇一使用。
{ "token": "eyJraWQiOiIxIiwidHlwIjoi", "access_token": "eyJraWQiOiIxIiwid", "token_type": "bearer", "expires_in": "108000" }
如何取得更新權杖
如要取得更新權杖,請對 edgemicro-auth
Proxy 的 /token
端點發出 API 呼叫。您「必須」使用 password
授權類型進行這個 API 呼叫。下列步驟會逐步引導您完成這項程序。
- 使用
/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" }
- 您現在可以呼叫相同 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 的間隔時間。這個檔案會設定名為 ever-Monitor 的永久服務,這項服務可透過程式管理 Forever。
您可以在 Edge Microgateway 根目錄中找到 forever.json 檔案。請參閱「 Edge Microgateway 的安裝位置」一節。如要進一步瞭解設定選項,請參閱永久監控說明文件。
edgemicro forever
指令包含的標記可讓您指定 forever.json
檔案的位置 (-f
標記),以及啟動/停止永久監控程序 (-a
標記)。例如:
edgemicro forever -f ~/mydir/forever.json -a start
詳情請參閱 CLI 參考資料中的「永久監控」相關說明。
指定設定檔端點
如果您執行多個 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
您可以執行 Edge Microgateway 與任何 Apigee Edge 依附元件完全中斷連線。這種做法稱為獨立模式,可讓您在離線狀態下執行及測試 Edge Microgateway。
在獨立模式下,下列功能需要連線至 Apigee Edge,因此無法運作:
- OAuth 和 API 金鑰
- 配額
- 數據分析
另一方面,自訂外掛程式和尖峰流量報備可以正常執行,因為不需要連線至 Apigee Edge。此外,名為 extauth
的新外掛程式可讓您在獨立模式下,使用 JWT 授權透過 JWT 呼叫微閘道。
設定及啟動閘道
如何在獨立模式下執行 Edge Microgateway:
- 確認您已安裝 Edge Microgateway 2.5.25 以上版本。否則,您必須執行下列指令才能升級至最新版本:
npm install -g edgemicro
如需協助,請參閱「安裝 Edge Microgateway」一文。
- 建立如下所示的設定檔:
$HOME/.edgemicro/
org_name-
env_name-config.yaml
例如:
vi $HOME/.edgemicro/foo-bar-config.yaml
- 將下列程式碼貼入檔案:
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
- 匯出以下值為「1」的環境變數:
export EDGEMICRO_LOCAL=1
- 執行下列
start
指令,提供值,將本機 Proxy 執行個體化:edgemicro start -o org_name -e environment_name -a local_proxy_name \ -v local_proxy_version -t target_url -b base_path
在此情況下:
- your_org 是設定檔名稱中使用的「機構」名稱。
- your_environment 是您在設定檔名稱中使用的「env」名稱。
- local_proxy_name 是要建立的本機 Proxy 名稱。您可以使用任何名稱。
- local_proxy_version 是 Proxy 的版本號碼。
- target_url 是 Proxy 目標的網址。(「目標」是 Proxy 呼叫的服務)。
- base_path 是 Proxy 的基本路徑。這個值的開頭必須是正斜線。如果是根基本路徑,請只指定正斜線,例如「/」。
例如:
edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
- 測試設定。
curl http://localhost:8000/echo { "error" : "missing_authorization" }
由於
extauth
外掛程式位於foo-bar-config.yaml
檔案中,您會收到「missing_Authorization」錯誤。這個外掛程式會驗證 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
端點取得權杖:
- 您必須執行 Edge Microgateway 的標準設定和設定,才能將
edgemicro-auth
Proxy 部署至 Apigee Edge 中的機構/環境。如果您之前已完成這個步驟,就不必重複執行相同步驟。 - 如果您已將 Edge Microgateway 部署至 Apigee Cloud,您必須連上網際網路,才能從這個端點取得 JWT。
-
停止 Edge Microgateway:
edgemicro stop
- 在先前建立的設定檔中 (
$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'
-
使用先前在設定檔名稱中使用的 org/env 名稱,重新啟動 Edge Microgateway。例如:
edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
-
從授權端點取得 JWT 權杖。由於您使用的是
edgemicro-auth/jwkPublicKeys
端點,因此可以使用以下 CLI 指令:
您可以使用 edgemicro token
指令或 API 產生 Edge Microgateway 的 JWT。例如:
edgemicro token get -o your_org -e your_env \ -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy
在此情況下:
- your_org 是您之前設定 Edge Microgateway 的 Apigee 機構名稱。
- your_env 是機構中的環境。
i
選項會指定開發人員應用程式提供的用戶端金鑰,而該開發人員應用程式的產品包含edgemicro-auth
Proxy。s
選項會指定開發人員應用程式提供的用戶端密鑰,該開發人員應用程式含有包含edgemicro-auth
Proxy 的產品。
這個指令會要求 Apigee Edge 產生 JWT,接著就能用於驗證 API 呼叫。
另請參閱「產生權杖」。測試獨立設定
如要測試設定,請使用 Authorization 標頭中新增權杖的 API 呼叫 API,如下所示:
curl http://localhost:8000/echo -H "Authorization: Bearer your_token
示例:
curl http://localhost:8000/echo -H "Authorization: Bearer eyJraWQiOiIxIiwidHlwIjo...iryF3kwcDWNv7OQ"
輸出內容範例:
{ "headers":{ "user-agent":"curl/7.54.0", "accept":"*/*", "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP", "client_received_start_timestamp":"1535134472699", "x-authorization-claims":"eyJhdDbiO...M1OTE5MTA1NDkifQ==", "target_sent_start_timestamp":"1535134472702", "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896", "x-forwarded-proto":"http", "x-forwarded-host":"localhost:8000", "host":"mocktarget.apigee.net", "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513", "via":"1.1 localhost, 1.1 google", "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212", "connection":"Keep-Alive" }, "method":"GET", "url":"/", "body":"" }
使用本機 Proxy 模式
在本機 Proxy 模式中,Edge Microgateway 不需要在 Apigee Edge 上部署微閘道感知 Proxy。您只要在啟動微閘道時提供本機 Proxy 名稱、基本路徑和目標網址,即可設定「本機 Proxy」。接著,對微閘道的 API 呼叫會傳送至本機 Proxy 的目標網址。在所有其他方面,本機 Proxy 模式的運作方式與在一般模式下執行 Edge Microgateway 完全相同。驗證的運作方式相同,無論是尖峰流量防範和配額強制執行作業、自訂外掛程式等。
用途和範例
如果只需要將單一 Proxy 與 Edge Microgateway 執行個體建立關聯,本機 Proxy 模式就非常實用。舉例來說,您可以將 Edge Microgateway 做為補充 Proxy 插入 Kubernetes 中,讓微閘道和服務在單一 Pod 中執行,而 Microgateway 可用於管理與隨附服務之間的流量。下圖說明這個架構在 Kubernetes 叢集中,將 Edge Microgateway 做為補充 Proxy 運作。每個微閘道執行個體都只會與隨附服務中的單一端點通訊:
這種架構的優點在於 Edge Microgateway 為部署至容器環境 (例如 Kubernetes 叢集) 的個別服務提供 API 管理機制。
設定本機 Proxy 模式
如要將 Edge Microgateway 設為在本機 Proxy 模式中執行,請按照下列步驟操作:
- 確認您已安裝 Edge Microgateway 2.5.25 以上版本。否則,您必須執行下列指令才能升級至最新版本:
npm install -g edgemicro
如需協助,請參閱「安裝 Edge Microgateway」一文。
- 執行
edgemicro init
來設定本機設定環境,做法與一般 Edge Microgateway 設定環境相同。另請參閱「設定 Edge Microgateway」。 - 按照一般 Edge Microgateway 設定程序執行
edgemicro configure
。例如:edgemicro configure -o your_org -e your_env -u your_apigee_username
這個指令會將 edgemicro-auth 政策部署至 Edge,並傳回啟動 Microgateway 的金鑰和密鑰。如需協助,請參閱「設定 Edge Microgateway」一文。
- 在 Apigee Edge 上建立 API 產品並設定下列必要設定需求 (您可以隨意管理所有其他設定):
在 Apigee Edge 上建立開發人員,或視需求使用現有的開發人員。如需相關說明,請參閱「使用 Edge 管理 UI 新增開發人員」。
- 在 Apigee Edge 建立開發人員應用程式。您必須將剛剛建立的 API 產品新增至應用程式。如需相關說明,請參閱「在 Edge 管理 UI 中註冊應用程式」。
- 在已安裝 Edge Microgateway 的機器中,匯出下列環境變數為「1」。
export EDGEMICRO_LOCAL_PROXY=1
- 執行下列
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":"" }