您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
開始使用
- 如何安裝 Edge Microgateway?
- 請參閱安裝 Edge Microgateway。
- 如何執行 Edge Microgateway?
- 請參閱「 設定及設定 Edge Microgateway」。
- 我需要資料庫才能執行 Microgateway 嗎?
- 透過 Edge Microgateway 進行 Proxy 技術的 API 可能會與做為目標服務中運作的資料庫互動。不過,Edge Microgateway 的運作方式與任何資料庫或後端資料儲存庫無關。
作業
- Edge Microgateway 上的哪些變更需要重新啟動 Edge Microgateway?
- Edge Microgateway 能夠針對 Apigee Edge 上的變更 (例如對微閘道感知 Proxy、產品或開發人員應用程式所做的變更) 自動進行輪詢。預設的輪詢間隔為 600 秒;不過,您可以透過
config_change_poll_interval
設定變更間隔時間。請參閱「 Edgemicro 屬性」相關說明。 - 如果不想等待輪詢間隔,請使用
edgemicro reload
指令擷取最新的變更。請參閱「 重新載入微閘道叢集」一文。 - 如何區分部署於 Edge 和 Edge Microgateway 的 Proxy?
- 設定 Edge Microgateway 時,系統會將在 Apigee Edge 上部署的微閘道感知 Proxy 下載至 Edge Microgateway 的本機設定。微閘道感知 Proxy 是指以
edgemicro_
前置字串命名的 Proxy。 - 使用 Edge Microgateway 進行記錄時,有哪些選項?
- Edge Microgateway 內建記錄功能,詳情請參閱 管理記錄檔。
- 您也可以編寫自訂外掛程式,以便搭配 Edge Microgateway 使用第三方記錄服務。基於 Edge Microgateway 的運作方式,您無法使用 Apigee Edge 訊息記錄政策記錄 Edge Microgateway 的訊息。另請參閱 Microgateway 適用的 Logging 外掛程式社群文章。
- 我可以重複使用 Edge Microgateway 執行個體的鍵/密鑰組合嗎?
- 只要機構和環境與 Microgateway 執行個體相同,您就能重複使用在設定期間產生的金鑰/密鑰組合。
- 如何設定 Edge Microgateway 在實際工作環境中啟動?
- 您可以設定啟動指令參數的環境變數,例如
EDGEMICRO_KEY
、EDGEMICRO_SECRET
、EDGEMICRO_ORG
和EDGEMICRO_ENV
。透過這些 (和其他) 變數,您可以使用單一指令edgemicro start
啟動 Edge Microgateway。另請參閱「 設定環境變數」。 - 我可以搭配 Edge Microgateway 使用自訂產品或開發人員應用程式屬性嗎?
- 不可以。根據預設,Edge Microgateway 只會處理與基本轉送和安全性相關的屬性。不過,您可以採用以下可行做法:
-
將自訂屬性新增至 Edge Microgateway 部署至 Apigee Edge 的
edgemicro-auth
Proxy。使用 API 金鑰或 OAuth 權杖安全性時,即可使用這些屬性。 - 修改 OAuth 外掛程式來對這些屬性執行動作。
-
將自訂屬性新增至 Edge Microgateway 部署至 Apigee Edge 的
- 要求標頭大小是否有限制?
- 如果您將 Node.js 升級至 v8.14.0 以上版本,請注意要求的標頭大小上限已從 80KB 縮減至 8 KB。如果標頭超過 8 KB,就會導致 HTTP 431 錯誤。
- 在 Node.js v11.6.0 中新增 Node.js 設定選項可讓您變更預設的標頭大小上限。這個參數
--max-http-header-size
可讓您指定 HTTP 標頭的大小上限 (以位元組為單位)。 - 如要變更預設設定,請在指令列中設定
NODE_OPTIONS
環境變數的值,如下所示:NODE_OPTIONS=--max-http-header-size=NUM_BYTES
例如:
NODE_OPTIONS=--max-http-header-size=80000
Edge Microgateway 採用哪些管理 API?
下列 Edge Microgateway 指令會呼叫 Apigee Edge Management API 執行工作,如 Edge Microgateway 的 CLI 參考資料所述:
edgemicro configure
edgemicro upgradeauth
edgemicro upgradekvm
edgemicro rotatekey
edgemicro cert check
edgemicro cert delete
edgemicro cert install
以下各節列出每個指令使用的 Management API 呼叫。
edgemicro configure
和 upgradeauth
指令會呼叫下列管理 API:
- (列出部署作業)
GET: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/deployments
- (取得部署資訊)
GET: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth
- (上傳資源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=java&name=micro-gateway-products-javacallout-2.0.0.jar
- (上傳資源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=adjust-quota.js
- (上傳資源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=generate-jwk.js
- (上傳資源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=generate-verify-jwt.js
- (上傳資源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=jsrsasign-all-min.js
- (上傳資源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=jwt-initialization.js
- (上傳資源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=send-jwk-response.js
- (上傳資源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=send-product-list.js
- (上傳資源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=send-public-key.js
- (上傳資源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=set-jwt-variables.js
- (上傳資源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=set-quota-variables.js
- (上傳資源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=set-response.js
- (上傳資源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=validate-params.js
- (建立 API Proxy)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis?action=import&validate=false&name=edgemicro-auth
- (上傳政策)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/policies
- (上傳 Proxy)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/proxies?name=default
- (部署 Proxy)
POST: https://api.enterprise.apigee.com/v1/o/[org]/e/[env]/apis/edgemicro-auth/revisions/1/deployments
upgradekvm
指令會呼叫下列 Management API:
PUT: https://api.enterprise.apigee.com/v1/organizations/[org]/environments/[env]/keyvaluemaps/microgateway
rotatekey
指令會呼叫下列 Management API:
GET: https://api.enterprise.apigee.com/v1/organizations/[org]/environments/[env]/keyvaluemaps/microgateway/entries/private_key
cert check
指令會呼叫下列 Management API:
GET: https://api.enterprise.apigee.com/v1/organizations/[org]/environments/[env]/keyvaluemaps/microgateway
cert delete
指令會呼叫下列 Management API:
DELETE: https://api.enterprise.apigee.com/v1/organizations/[org]/environments/[env]/keyvaluemaps/microgateway
cert install
指令會呼叫下列 Management API:
POST: https://api.enterprise.apigee.com/v1/organizations/[org]/environments/[env]/keyvaluemaps
部署作業
- 我可以在執行目標服務的同一伺服器上部署 Edge Microgateway 嗎?
- 可以。Edge Microgateway 是一款輕量級程序,可在您的目標服務附近 (包括相同機器) 執行。
- 可以將現有的 Edge Proxy 組合部署為 Edge Microgateway 部署項目嗎?
- 不可以。Edge Microgateway 感知的 Proxy 有特定需求,且不支援一般 Edge Proxy 的所有功能。請參閱第 2 部分:在 Apigee Edge 上建立實體
- 我可以針對相同的 API Proxy,在 Edge Proxy 組合部署與 Edge Microgateway 部署作業之間啟用容錯移轉嗎?
- 否。Edge Microgateway 無法得知 Apigee Edge 上的非微閘道 API Proxy 部署作業。
- Edge Microgateway 的高可用性部署模式為何?
- 如需進一步瞭解如何使用 NGINX 做為負載平衡器執行 Edge Microgateway,請參閱 使用 Apigee Edge Microgateway 和 NGINX 管理 API。
- 哪些負載平衡器可以與 Edge Microgateway 搭配使用?
- Edge Microgateway 能夠與任何負載平衡器搭配使用。
- 我可以部署的 Edge Microgateway Proxy 數量有上限嗎?
- 請參閱為一般邊緣 Proxy 指定的產品設定限制。您可以在 Apigee Edge 機構和環境中部署,並透過 Edge Microgateway 呼叫的 Microgateway 感知 Proxy 數量,前提是這些 Proxy 數量必須符合相同的限制。
- 可以將 Edge Microgateway 部署作業與特定機構和環境建立關聯嗎?
- 設定 Edge Microgateway 執行個體時,必須將執行個體與特定 Edge 機構和環境建立關聯。
- 如果我是多區域客戶,可以將部署項目與特定區域建立關聯嗎?
- Edge Microgateway 會自動選擇最適合其與 Apigee Edge 互動的區域。 您可以在要提供服務的每個區域中部署 Edge Microgateway 執行個體。
管理
- 只有機構組織管理員才能設定及部署 Edge Microgateway 嗎?
- 可以。您必須擁有機構管理員憑證,才能設定及部署 Edge Microgateway。
- 只有機構管理員才能執行 Edge Microgateway 嗎?
- 不可以。Edge Microgateway 是
Node.js
應用程式,任何有權在特定機器上執行這些應用程式的使用者皆可執行。 - 我的任何機構使用者都可以使用 Edge Microgateway 嗎?
- 即使您不是 Apigee Edge 機構使用者,也能透過 Edge Microgateway 發出 API 呼叫。不過,您必須具備機構層級權限,才能建立或變更已部署於 Edge 的 Edge Microgateway 感知 Proxy。
效能
- 使用 Edge Microgateway 的效能注意事項為何?
- 如果對目標應用程式執行 Edge Microgateway,請確認伺服器具備充足的容量。
- 大規模執行 Edge Microgateway 的最佳做法為何?
- Apigee 建議在負載平衡器前方 (例如 NGINX) 的不同伺服器上執行多個 Edge Microgateway 執行個體。另請參閱 Apigee 社群中的 使用 Apigee Edge Microgateway 和 NGINX 管理 API 和 垂直水平資源調度的相關說明。
- 什麼是 Edge Microgateway TPS,以及 Microgateway 執行個體所需的硬體需求?
- 使用 Edge Microgateway 來衡量硬體需求和 TPS 測量結果。視您的設定而定,這包括調整 Edge Microgateway、外掛程式使用情形、自訂外掛程式,以及設定 TLS 等其他項目。Apigee 通常會建議您瞭解該組合的項目,並透過您的特定設定進行效能測試。
私有雲部署
- Edge Microgateway 能與 Edge for Private Cloud 搭配使用嗎?
- 可以。詳情請參閱 Apigee Private Cloud 設定步驟。
外掛程式
- Edge Microgateway 配額功能如何強制執行?
- 您可以選擇為 Edge Microgateway 執行個體新增配額外掛程式。詳情請參閱「使用配額外掛程式」一節。
- 如何透過 Edge Microgateway 強制執行 Spike 攻擊?
- 您可以選擇在 Edge Microgateway 執行個體中新增尖峰防範攻擊外掛程式。詳情請參閱使用尖峰流量防範外掛程式。
- 有其他方法可以編寫適用於 Edge Microgateway 的
Node.js
外掛程式嗎? - 不可以。外掛程式必須以
Node.js
編寫。 - 如果 Edge Microgateway 無法將 Analytics (分析) 資料上傳至 Edge,會有什麼影響?
- Edge Microgateway 具有記憶體內緩衝區。如果緩衝區填滿,系統會捨棄較舊的酬載,讓 API 流量順暢流動。
- 我可以為 Edge Microgateway 新增政策嗎?
- 如果您在 Apigee Edge 中將一般 Apigee Edge 政策附加至微閘道感知 Proxy,系統就會忽略這些政策。不過,Edge Microgateway 採用外掛程式來提供與 Edge 政策類似的功能,例如配額、尖峰流量防範、API 金鑰安全性和 OAuth2 安全性等。您也可以編寫自訂外掛程式。請參閱「使用外掛程式」和「開發自訂外掛程式」這兩篇文章。
下列 Apigee 社群貼文和網誌探討其他外掛程式的使用案例:
安全性
- 如何保護
/products
資源? - 總覽
- 設定 Edge Microgateway 時,系統會將名為
edgemicro-auth
的 API Proxy 部署至 Apigee Edge 上的環境。這個 Proxy 會公開/products
端點,可傳回 API 產品清單。如果您是在 2018 年 10 月 5 日當天或之前安裝 Edge Microgateway,Apigee 建議您採取行動保護這個端點,因為回應中會包含在您的 Apigee 機構中建立及修改 API 產品的開發人員電子郵件地址。 - 您可以升級 Edge Microgateway,或設定雙向 TLS 來保護端點。這兩種選項的說明如下。
- 檢查
/products
端點是否受到保護 -
如果您不確定
/products
端點是否已受到保護,請參閱「驗證/products
資源是否受到保護」一節,並在繼續操作前採取相關步驟。方法 1:升級 Edge Microgateway
如果您是在 2018 年 10 月 5 日當天或之前安裝 Edge Microgateway,Apigee 建議您升級至最新版本的 Edge Microgateway。如有網際網路連線,請按照 升級 Edge Microgateway 一文中的步驟進行。
如果您無法立即升級,請前往方法 2。
方法 2:設定雙向傳輸層安全標準 (TLS)
如果您目前無法升級 Edge Microgateway,Apigee 建議您使用雙向 TLS (又稱為雙向 TLS) 保護 Edge Microgateway 與
edgemicro-auth
Proxy 之間的通訊。- 開啟
$HOME/.edgemicro/org-env-config.yaml
檔案。如果找不到這個檔案,請參閱「 Edge Microgateway 安裝位置」一文。 - 將下列
tlsOptions
區塊新增至org-env-config.yaml
檔案,以啟用 Edge Microgateway 和 Apigee Edge 之間的雙向傳輸層安全標準:edge_config: bootstrap: >- https://domain/edgemicro/bootstrap/organization/org/environment/env jwt_public_key: 'https://domain/edgemicro-auth/publicKey' managementUri: 'https://api.enterprise.apigee.com' tlsOptions: agentOptions: requestCert: true cert: 'path/to/cert' key: 'path/to/key'
例如:
tlsOptions: agentOptions: requestCert: true cert: '/Users/jdoe/twowayssl/ssl/client.key' key: '/Users/jdoe/twowayssl/ssl/ca.crt'
您也可以加入下列選用的
agentOptions
參數:ca
:指定憑證授權單位的路徑。pfx
:要使用 p12/pfx 檔案,而非憑證和金鑰。passphrase
:pfx 檔案的通關密語。ciphers
:指定 TLS 加密。
- 確保部署
edgemicro-auth
Proxy 的虛擬主機已啟用雙向傳輸層安全標準 (TLS)。詳情請參閱 Apigee Edge 說明文件中的「定義雙向傳輸層安全標準 (TLS) 虛擬主機」一文。下列螢幕截圖說明如何在 Apigee Edge UI 中,在虛擬主機上啟用雙向傳輸層安全標準 (TLS):
- 查看 Edge UI 中的
edgemicro-auth
API Proxy,確認 Proxy 設定中指定正確的虛擬主機。舉例來說,如果您建立名為mutualtls
的虛擬主機 (已啟用 TLS),則 Proxy 的HTTPProxyConnection
Stanza 應如下所示:<HTTPProxyConnection> <BasePath>/edgemicro-auth</BasePath> <Properties/> <VirtualHost>mutualtls</VirtualHost> </HTTPProxyConnection>
- 開啟
/products
資源受到保護/products
資源是否受到保護。完成步驟 1 或選項 2 後,請務必執行這項測試來保護資源。您可以使用 cURL 執行此操作,例如:
curl -v https://your_domain/edgemicro-auth/products
/products
端點受到保護:
{ "error":"unauthorized", "error_description": "authentication failed" }
或
curl: (35) error:1408F10B:SSL routines:ssl3_get_record:wrong version number
如果您看到類似下方的回應,表示 /products
資源未受到保護,開發人員電子郵件地址可能會暴露在風險中:
{ "apiProduct":[ { "apiResources":[ "/", "/**" ], "approvalType":"auto", "attributes":[ ], "createdAt":1537374680948, "createdBy":"jdoe@foo.com", "description":"", "displayName":"mock", "environments":[ "test" ], "lastModifiedAt":1537374680948, "lastModifiedBy":"test@test.com", "name":"mock", "proxies":[ "edgemicro-auth", "edgemicro_mock" ], "quota":"null", "quotaInterval":"null", "quotaTimeUnit":"null", "scopes":[ "" ] } ] }
Apigee 也建議您測試 HTTP 虛擬主機:
例如:
curl -v http://your_domain/edgemicro-auth/products
如果 cURL 呼叫會傳回 API 產品清單,則開發人員電子郵件地址可能會顯示在這裡。如果您不想透過這個非傳輸層安全標準 (TLS) 虛擬主機公開端點,請務必從 edgemicro-auth
HTTPProxyConnection 設定中移除該端點。
為了保護資源,請採用下列其中一個選項:
您目前無法更新指定 Edge Microgateway 執行個體的 JWT 權杖。
解決方法:
每個 JWT 權杖都有 exp 屬性,用來標明憑證的到期日。應用程式可以直接對 edgemicro-auth
權杖端點發出 API 呼叫,藉此計算到期時間並要求新的權杖。舉例來說,您可以按照以下方式進行 API 呼叫:
POST https: //{your_org}-{your_env}.apigee.net/edgemicro-auth/token
... 使用類似下方的 JSON 主體:
{ "client_id": {your_id}, "client_secret": {your_secret},
"grant_type": "client_credentials" }
另請參閱:
- 在 Edge Microgateway 文件中,使用 OAuth 權杖或 API 金鑰保護 API。
- 在 Apigee 社群中,不記名權杖過期後如何更新。
目前系統只會檢查基本路徑,判斷特定 API 產品是否獲準使用與特定 OAuth 權杖相關的 API 產品。
例如:
- 您會建立含有基本路徑和目標的
edgemicro_
前置字串 Proxy, - 請將這個 Proxy 新增至產品。將其命名為
edgemicro-prod1
。 - 使用 API 金鑰或 OAuth 權杖透過 Edge Microgateway 呼叫 API 時,Edge Microgateway 會檢查 API 基本路徑是否與
edgemicro_*
Proxy 的基本路徑相符,且該 Proxy 已獲準使用該金鑰或權杖的產品清單。
另請參閱 Apigee 社群中的「 在產品中使用 Edge Mimicro 閘道時,如果產品所用的產品中,有哪些網址需要加入許可清單?」。
目前僅支援預設 Apigee SSL 憑證。目前不支援自訂 SSL 憑證。
解決方法:
如要使用自訂 (非 Apigee 預設) 安全資料傳輸層 (SSL) 憑證,您有下列選擇:
-
使用非 SSL
jwt_public_key
端點。修改 Edge Microgateway 設定檔以使用http://{org}-{env}.apigee.net/edgemicro-auth/publicKey
或 -
啟動 Edge Microgateway 之前,請先設定以下環境變數:匯出
NODE_TLS_REJECT_UNAUTHORIZED ="0"
另請參閱 Apigee 社群中的 確認 SSL 憑證上的 Edge Micro 安裝錯誤。
edgemicro-auth
Proxy 部署至 Edge,而這項部署作業需要機構管理員憑證。您可以使用自己的權杖,但必須先關閉 Edge Microgateway 的內建授權。做法如下:
- 開啟 Edge Microgateway 的設定檔。
-
將兩個 OAuth 設定變更為 true,如下所示:
oauth: allowNoAuthorization: true allowInvalidAuthorization: true
edgemicro start -o [org] -e [env] -k [key] -s [secret]
測試和偵錯
- 如何避免在負載測試期間發生「開啟太多檔案」錯誤?
-
在某些情況下,系統可能會發生開啟檔案連線過多的情況,進而導致 Edge Micro 當機。預設記錄功能需要兩個 HTTP 連線,才能透過 Microgateway 進行傳入和傳出交易。
為了進行測試與基準化,Apigee 建議將系統的 ulimit 指令設為無限制:
ulimit -n unlimited
。另請參閱 Apigee 社群中的負載測試期間的邊緣閘道錯誤。 - 快速進行開發及偵錯的訣竅
-
如果您要開發 Edge Microgateway 外掛程式,可能會發現對於快速開發的支援有限。
以下提供幾個訣竅:
- 如要啟動 Edge Microgateway,您可以將環境變數 EDGEMICRO_KEY 和 EDGEMICRO_SECRET 設為 Microgateway 啟動指令所需的金鑰/密鑰組合。如此一來,您不必在指令列中輸入金鑰/密鑰,就能啟動 Edge Microgateway。另請參閱 Edge Microgateway 文件中的「 設定環境變數」。
-
在偵錯模式中啟動 Edge Microgateway,以便在指令終端機中查看其他輸出內容:
DEBUG=* edgemicro start -o [org] -e [env] -k [key] -s [secret]
業務和授權
- Apigee-127 和 Edge Microgateway 支援模式之間的關係為何?
-
Apigee-127 是開放原始碼模型支援的開放原始碼軟體專案。也就是說,您可以在 GitHub 專案中提出問題,並在嘗試修正問題時提出提取要求。Apigee-127 不需要或加入任何與 Apigee 相關的軟體授權協議協議。
另一方面,Edge Microgateway 是一款企業產品,其是由 Apigee 為 Apigee 客戶提供支援。也就是說,Apigee 客戶可以透過 Google Cloud Apigee Edge 支援建立支援票證、功能要求和錯誤報告。