Edge Microgateway 的 CLI 參考資料

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

Edge Microgateway 3.3.x 版

總覽

Edge Microgateway CLI 可讓您控管及管理 Edge Microgateway 執行個體的所有層面。

管理憑證

cert 指令可讓您安裝及管理公開/私密金鑰組。這些金鑰組可用於簽署不記名權杖，供用戶端透過 Edge Microgateway 進行安全呼叫。這些金鑰會儲存在 Apigee Edge 的加密金鑰值對應 (KVM) 中。Edge Microgateway 使用公開金鑰來驗證已簽署的不記名權杖。這些金鑰會在您執行 Edgemicro 設定指令時產生，如設定及設定 Edge Microgateway 中所述。您可以使用這裡所述的 cert 指令，重新產生及管理這些金鑰 (如有需要)。

安裝憑證

在加密的金鑰值對應 (KVM) 中安裝金鑰，並傳回公開金鑰做為輸出內容。金鑰組的範圍限定於指定機構。

用法

edgemicro cert install -o [organization] -e [environment] -u [username] -p [password] --force

參數

範例

edgemicro cert install -o docs -e test -u jdoe@example.com -f

輸出功率

current nodejs version is v12.5.0
current edgemicro version is 3.0.2
password:
deleting vault
creating vault
adding private_key
adding public_key
installed cert

刪除憑證

刪除機構的金鑰組。

用法

edgemicro cert delete -o [organization] -e [environment] -u [username] -p [password]

參數

範例

edgemicro cert delete -o docs -e test -u jdoe@example.com

輸出功率

deleting vault
Vault deleted!

檢查憑證

檢查貴機構是否已安裝憑證。

用法

edgemicro cert check -o [organization] -e [environment] -u [username] -p [password]

參數

範例

edgemicro cert check -o docs -e test -u jdoe@example.com

輸出內容 (成功)

checked cert successfully

輸出內容 (失敗)

如果憑證不存在，系統會傳回錯誤。

取得公開金鑰

傳回指定機構的公開金鑰。不需要驗證。

用法

edgemicro cert public-key -o [organization] -e [environment]

參數

範例

edgemicro cert public-key -o docs -e test

輸出內容 (範例)

-----BEGIN CERTIFICATE-----

MIICpDCCAYwCCQCKpXWGum9uTjANBgkq9w0BAQsFADAUMRIwEAYDVQQDEwls
b2NhbGhvc3cNMTYxMTAyMjAxNTA2WhcNMTYxMTAzMjAxNTA2WjAUMRIwEAYD
VQQDEwlsb2Nvc3QwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDD
ETr/ne/gP47+9LgjLvBJjpbFVdaeUabZZ3wbA7sSIVnnNXWt3yPklrWSfIh+
L2+dq4k+YunsQE2+dwPdXA2x8DPGvqGcCdWPxnpZ7ix5Akbs8i/J+Ue0pXT4
jkpWbaDDftGL2tcxwP45yI+slpDYvmWRps07TFXkAPjGEHYPvCT9/v/35GkL
0h4v0S+XfpcjS5c47o7CIWlkgEM5GBosQUb17kuVR48392vGFPsnCP34iNe7
zguhiCXYg2zkOcj/N3AE4xKIhCz0QcewULy08GltWMmyjJ/30zs8P41JqoA4
RwfeEZ8RenN3rJQim1ppAAEwDQYJKoZIhvcNAQELBQADggEBAHcORIfc+ySe
2FMmqicNe6Wt5V/5zOaBMLsGQdqGOHB5cQc79sMBrk680KVhrwHXZ2nBIkVe
UEL+2qLY1VLfswBNAvcNwV9U4TwHq4eIANiD751oJK1tHmM/ujThQkwNf96o
6I7Ws+wfpGO3ppJCttRbtnATIxrwsCHN4i5lbW/tJSL7t/Zf6T1B+YSJU9AF
xuvLq22cCqyYJQdmKq2vVS55WRZdllm+mRtJrv7MLM9gfDPRxVlwrBz/eQHy
Fv+dwzxcvQjkz03RNhZUodzuD34DPJoYeK++rItsddwQ26KTahH80yYTAFzY
x9gfPf1/+qo=?

-----END CERTIFICATE-----

為 Apigee Edge Cloud 設定 Edge Microgateway

讓 Edge Microgateway 透過 Apigee Edge Cloud 執行個體運作。這項服務可包裝並執行一系列指令，將必要的驗證 Proxy 部署至 Edge、產生驗證權杖，以及更新設定檔。如需完整的工作範例，請參閱「設定及設定 Edge Microgateway」。

用法

edgemicro configure -o [organization] -e [environment] -u [username] -p [password]

參數

使用注意事項

這個指令會將設定資訊儲存在 ~/.edgemicro/org-env-config.yaml 中。

範例

edgemicro configure -o docs -e test -u jdoe@example.com

輸出功率

成功執行時，指令會傳回一組啟動 Edge Microgateway 時需要使用的金鑰。

...

The following credentials are required to start edge micro
  key: d2f0a246ad52b5d2a8b04ba65b43c76348aba586691cf6185cd7bb9fb78fe9f
  secret: 59813bc1db4a7ada182705ae40893c28a6fae680c3deb42aefbf1a4db42e372

edgemicro configuration complete!

產生金鑰

genkeys 指令會產生 Edge Microgateway 所使用的金鑰和密鑰組合，以便在將數據分析資料非同步發布至 Apigee Edge 時進行驗證。

用法

edgemicro genkeys -o [organization] -e [environment] -u [username] -p [password]

參數

使用注意事項

成功執行時，指令會傳回三個項目。第一個是需要放在設定檔中的網址。另外兩個是啟動 Edge Microgateway 執行個體時所需的金鑰組。

• Bootstrap URL (啟動網址)：這個網址指向 Apigee Edge 服務，這項服務可讓 Edge Microgateway 執行個體將數據分析資料傳送至 Apigee Edge。您必須將該網址複製到 Edge Microgateway 設定檔：~/.edgemicro/org-env-config.yaml。
• key：金鑰。系統會使用這組金鑰和密鑰做為 CLI 指令的輸入內容，以便用於啟動 Edge Microgateway 執行個體。
• secret：密鑰。

範例

edgemicro genkeys -o docs -e test -u jdoe@example.com

輸出內容 (範例)

成功執行時，指令會傳回一組啟動 Edge Microgateway 時需要使用的金鑰。

configuring host edgemicroservices-us-east-1.apigee.net for region us-east-1
Please copy the following property to the edge micro agent config
  bootstrap: https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/jdoe/environment/test

The following credentials are required to start edge micro
  key: db39324077989c75eac34c13d285772ea8e3b982b957b3f52916f3048511443f
  secret: 5bf8da39de0056f88fdd5f25a8602d22f312c1c8c870580a5fef55ac6637b7ae

finished

設定 Apigee Edge 私有雲的 Edge Microgateway

設定 Edge Microgateway，與 Apigee Edge 私人雲端安裝搭配使用。

用法

edgemicro private configure -o [organization] -e [environment] -u [username] -p [password]

參數

使用注意事項

這個指令會將設定資訊儲存在 ~/.edgemicro/org-env-config.yaml 中。

範例

edgemicro private configure -o docs -e test -u jdoe@example.com -r http://192.162.55.100:9002 -m http://192.162.55.100:8080

輸出功率

成功執行時，指令會傳回一組啟動 Edge Microgateway 時需要使用的金鑰。

...

The following credentials are required to start edge micro
  key: d2f0a246ad52b5d2a8b04ba65b43c76348aba586691cf6185cd7bb9fb78fe9f
  secret: 59813bc1db4a7ada182705ae40893c28a6fae680c3deb42aefbf1a4db42e372

edgemicro configuration complete!

啟動 Edge Microgateway

您必須先執行 edgeMicrogateway (公開雲端) 或 edgemicro 私人設定 (Private Cloud)。設定指令會傳回啟動 Edge Microgateway 所需的金鑰和密鑰值。

用法

edgemicro start -o [organization] -e [environment] -k [public-key] -s [secret-key]

參數

設定通訊埠

start 指令可讓您指定通訊埠編號，以覆寫設定檔中指定的通訊埠。您也可以使用 PORT 環境變數指定通訊埠編號。例如：

edgemicro start -o docs -e test -k abc123 -s xyz456 -p 2 --port 8002

或

export PORT=8002
edgemicro start -o org -e test -k key -s secret -p 2

如果通訊埠正在使用中，Edge Microgateway 會傳回錯誤。

關於分群法

Edge Microgateway 採用 Node.js 叢集模組來啟用叢集功能。叢集可讓 Edge Microgateway 利用多核心系統。詳情請參閱這份 Node.js 說明文件。

範例

edgemicro start -o docs -e test -k abc123 -s xyz456

範例輸出：

...

current nodejs version is v12.5.0
current edgemicro version is 3.0.2
info: jwk_public_keys download from null returned 200 undefined
info: jwt_public_key download from https://docs-test.apigee.net/edgemicro-auth/publicKey returned 200 OK
info: products download from https://docs-test.apigee.net/edgemicro-auth/products returned 200 OK
info: config download from https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test returned 200 OK
PROCESS PID : 17991

管理權杖

token 指令可讓您取得、解碼及驗證已簽署的 OAuth2 存取權杖。另請參閱「 使用 OAuth2 存取權杖確保 API 呼叫安全無虞」。

將權杖解碼

將已簽署的編碼不記器權杖解碼至純文字 JSON JWT (Java Web Token) 表示法。權杖會傳達 Apigee Edge 開發人員應用程式的相關資訊，這個應用程式會提供用於建立權杖的金鑰，包括應用程式名稱、client_id、產品清單等。

用法

edgemicro token decode -f [filename]

參數

範例

edgemicro token decode -f token.jwt

輸出內容 (範例)

{ header: { typ: 'JWT', alg: 'RS256' },

  payload:
   { application_name: 'b43342ef-86f6-4666-a121-b9ac2025d217',
     client_id: 'O9ZQRZKnn1rdgcKQgsABSMdOsKS',
     scopes: [],
     api_product_list: [ 'MicroTest' ],
     iat: 1436280566,
     exp: 1436282365 },
  signature: '' }

產生權杖

產生已簽署的不記名權杖。這個權杖可讓用戶端應用程式向 Edge Microgateway 進行經過驗證的 API 呼叫。該憑證是符合 OAuth 2.0 規範的 JSON Web Token (JWT)。您必須輸入 Apigee Edge 上已註冊開發人員應用程式的用戶端金鑰 (用戶端 ID) 和用戶端密鑰 (用戶端密鑰) 值，才能使用這個值。另請參閱「 使用 OAuth2 存取權杖確保 API 呼叫安全無虞」。

用法

edgemicro token get -o [org] -e [env] -i [client_id] -s [client_secret]

參數

範例

edgemicro token get -o docs -e test -i 5UzOwAXGoOeo60aew94PPG5MAZE3aJp -s 6vahKFGS9a3qMLwz

輸出內容 (範例)

{ token: 'eyJ0eXAiOiJKV1JhbGciOiJSUzI1NiJ9Glvbl9uYW1lIjoiNWNiMGY0NTV6TV3
EtOWMzOC00YmJjLWIzNzEtZGMxZTQzOGMxIiwiY2xpZW50X2lkIjoiNVV6T3dBWEdvSU9lbz
YwYWV3OTRQN0c1TUFaRTNhSnAiLCJzY2MiOltdLCJhcGlfcHJvZHVjdF9saXN0IjpbIkVkZ2
VNaWNyb1Rlc3RQcm9kdWN0Il0sImlhdCI3ODEyMzQ2MSwiZXhwIjoxNDc4MTI1MjYwfQ.Dx5
f5U7PXm8koNGmFX4N6VrxKMJnpndKgoJ5zWSJvBZ6Ccvhlpd85ipIIA5S2A5nx4obYWp_rpY
RJpIGYwyxP6Oq2j0rxnVjdCC4qyYMgthZjhKgEBVBe3s1ndP72GP2vV6PsSA9RQ2-yzsy9r0
TzhAZ3NJTxT1tS0XKqKngE-OhR3fJHVLAzdMDT0AmS9H0Z2NAJtQOuK6RTpCjG9B6Bc48AEM
sj7QSM-1LWiQ8LdY8k_BoC06qsTI7bCQGWwTuqL-ismbcx2bxovUxSemZIaoROfuF-dCZHG3
2aTP75WxBvvNgBBvPvQtPzbeSOtEaww' }

您也可以使用管理 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 是您先前建立的開發人員應用程式中的用戶端密鑰。

驗證權杖

在指定機構和環境下，根據儲存在 Apigee Edge 的公開金鑰驗證已簽署的不記名權杖。

用法

edgemicro token verify -o [org] -e [env] -f [filename]

參數

範例

edgemicro token get -o docs -e test -f token.jwt

有效權杖的輸出內容範例

{ application_name: 'b43342ef-86f6-4666-a121-b9ac2025d217',

  client_id: 'O9ZQRZKnn1rdgcKQsAZUBkQSMdOsKS',

  scopes: [],

  api_product_list: [ 'MicroTest' ],

  iat: 1436396155,

  exp: 1436397954 }

無效權杖的輸出內容範例

{ [JsonWebTokenError: invalid token] name: 'JsonWebTokenError', message: 'invalid token' }

過期權杖的輸出內容範例

{ [TokenExpiredError: jwt expired]

  name: 'TokenExpiredError',

  message: 'jwt expired',

  expiredAt: Tue Jul 07 2015 09:19:25 GMT-0600 (MDT) }

初始化新的 Edge Microgateway 設定

在首次安裝 Edge Microgateway 後，請執行一次這個指令。建立新的預設設定檔：~/.edgemicro/default.yaml。

用法

edgemicro init

參數

範例

edgemicro init

輸出內容 (成功)

config initialized to /MyHome/.edgemicro/default.yaml

驗證 Edge Microgateway 設定

驗證 Edge Microgateway 已正確設定。

用法

edgemicro verify -o [organization] -e [environment] -k [public-key] -s [secret-key]

參數

範例

edgemicro verify -o docs -e test -k abc123 -s xyz456

輸出內容 (成功)

logging to /var/tmp/edgemicro-My-Machine.local-a0c48610-a148-11e6-8466-93f081b05988
installed plugin from analytics
installed plugin from oauth
a0c48610-a148-11e6-8466-93f081b05988 edge micro listening on port 8000
verifying analytics negative case: OK
verifying bootstrap url availability:OK
verifying jwt_public_key availability: OK
verifying products availability: OK
verifying quota with configured products: OK
verifying analytics with payload: OK
verification complete

檢查微閘道叢集狀態

根據預設，Edge Microgateway 以叢集模式啟動。您可以使用這個指令查看叢集狀態。

用法

edgemicro status

參數

範例

edgemicro status

輸出內容 (成功)

current nodejs version is v12.5.0
current edgemicro version is 3.0.2
edgemicro is running with 8 workers

正在停止微閘道叢集

停止 Edge Microgateway 叢集。

用法

edgemicro stop

參數

範例

edgemicro stop

輸出內容 (成功)

current nodejs version is v12.5.0
current edgemicro version is 3.0.2
Stop Completed Successfully

正在重新載入微閘道叢集

在設定變更後提供零停機時間。提取新的設定來重新載入 Edge Microgateway。

用法

edgemicro reload -o [organization] -e [environment] -k [public-key] -s [secret-key]

參數

範例

edgemicro reload -o docs -e test -k abc123 -s xyz456

輸出內容 (成功)

...

Reload Completed Successfully

升級 Edgemicro-驗證 Proxy

如要使用金鑰輪替，您必須在 Apigee Edge 機構中部署升級的 Edgemicro-驗證 Proxy。(新增 2.5.x 版)

注意：如果您是在 2.5.2 版之前設定目前的 Edge Micro 執行個體，則必須升級這個 Proxy，才能使用金鑰輪替功能。這項升級只需要執行一次。

用法

edgemicro upgradeauth -o [organization] -e [environment] -u [username]

參數

範例

edgemicro upgradeauth -o docs -e test -u jdoe@example.com

輸出內容 (成功)

成功執行後，指令會傳回類似以下的輸出內容：

Going to create revision 2 of API edgemicro-auth
Using /Users/jdoe/npm/lib/node_modules/edgemicro/node_modules/microgateway-edgeauth/apiproxy/edgemicro-auth.xml as the root file
Creating revision 2 of API edgemicro-auth
Uploading java resource micro-gateway-products-javacallout-2.0.0.jar
Uploading jsc resource generate-verify-jwt.js
Uploading jsc resource send-public-key.js
Uploading jsc resource set-jwt-variables.js
Uploading jsc resource set-response.js
Uploading node resource index.js
Uploading node resource node_modules_apigee-access.zip
Uploading node resource node_modules_base64url.zip
Uploading node resource node_modules_buffer-equal-constant-time.zip
Uploading node resource node_modules_ecdsa-sig-formatter.zip
Uploading node resource node_modules_jsrsasign.zip
Uploading node resource node_modules_jwa.zip
Uploading node resource node_modules_jws.zip
Uploading node resource node_modules_safe-buffer.zip
Uploading node resource package.json
Uploading policy Access-App-Info-2.xml
Uploading policy Access-App-Info.xml
Uploading policy AccessTokenRequest.xml
Uploading policy Add-Custom-Claims.xml
Uploading policy Create-OAuth-Request.xml
Uploading policy Create-Refresh-Request.xml
Uploading policy Extract-API-Key.xml
Uploading policy Extract-OAuth-Params.xml
Uploading policy Extract-Refresh-Params.xml
Uploading policy Get-Private-Key.xml
Uploading policy Get-Public-Key.xml
Uploading policy Get-Public-Keys.xml
Uploading policy JavaCallout.xml
Uploading policy Products-to-JSON-2.xml
Uploading policy Products-to-JSON.xml
Uploading policy Raise-Fault-Unknown-Request.xml
Uploading policy RefreshAccessToken.xml
Uploading policy Send-Public-Key.xml
Uploading policy Set-JWT-Variables.xml
Uploading policy Set-Response.xml
Uploading policy Verify-API-Key.xml
Uploading target TargetEndpoint-1
Uploading proxy default
Deploying revision 2 of edgemicro-auth to test
Deployment on test successful
edgemicro-auth proxy upgraded

金鑰值對應 (KVM) 升級

使用 edgemicro upgradekvm 指令升級 Apigee 機構中的 KVM。如要使用金鑰輪替功能，必須升級 KVM。

用法

公有雲邊緣：

edgemicro upgradekvm -o [organization] -e [environment] -k [key] -s [secret]

私有雲的邊緣：

edgemicro private upgradekvm -o [organization] -e [environment] -k [key] -s [secret] -p 'https://[hostname]/edgemicro-auth'

參數

 -p 'https://[org]-[env].apigee.net/edgemicro-auth'

-p 'https://[hostname]/edgemicro-auth'

範例

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

輸出內容 (成功)

成功執行後，指令會傳回類似以下的輸出內容：

current nodejs version is v12.5.0
current edgemicro version is 3.1.5
password:
Checking for certificate...
Certificate found!
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsT6yVoT/h6pvkPlkUUtv
Hgs7MbDPcWxto7dZqJBwQ4oOQ0IJ2P4XGigc3kYUyPp5lFHg1ssP9+0onRpqn6Lq
z7N5iaTSv5YXb26bU2kSOl4hbwcljIzauAnBzQ13VaQ5SoflRxMGSZmTqZeu5jkQ
3JZ7F6k2bCar5sk1k84vd4WXcCVyngFlrMtlux5z0vOU56QYZFvvKYl/wOHNPLLB
Js54531CV1ZfhV3nDDq9Lh5D1C/oQVlm1Lc7BJoEUmKeFATmSsi50c14ScsmdtJ1
HqC/brSXCd185P6ifu2RH7IHKzNfcD4NlfAVmDScng4w5RxBan2avbmAJrokQ4b5
WQIDAQAB
-----END PUBLIC KEY-----
KVM update complete

金鑰輪替

使用 edgemicro rotatekey 指令輪替公開/私密金鑰組，這些金鑰組是用於產生 Edge Microgateway 中用於 OAuth 安全性的 JWT 權杖。

詳情請參閱 輪替 JWT 金鑰一文。

用法

公有雲邊緣：

edgemicro rotatekey -o [organization] -e [environment] -k [key] -s [secret]

私有雲的邊緣：

edgemicro private rotatekey -o [organization] -e [environment] -k [key] -s [secret] -r '[hostname]/edgemicro-auth/rotateKey'

參數

-r 'https://[org]-[env].apigee.net/edgemicro-auth/rotateKey'

-r '[hostname]/edgemicro-auth/rotateKey'

範例

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

輸出內容 (成功)

成功執行後，指令會傳回類似以下的輸出內容：

current nodejs version is v12.5.0
current edgemicro version is 3.0.2
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!

輪替之後，Edge UI 會顯示新的金鑰已新增至微閘道 KVM。

範例

這個範例使用 -p 和 -c 旗標指定私密金鑰/憑證組合的路徑。這些選項可讓您傳遞自訂私密金鑰與憑證組合。

edgemicro rotatekey -o docs -e test \
-k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
-s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47 \
-p /users/home/keys.pem -c /users/home/cert.cert

永久監控

撤銷金鑰

使用 edgemicro revokekeys 指令撤銷 Edge Microgateway 設定的金鑰和密鑰憑證。

用法

edgemicro revokekeys -o [organization] -e [environment] -u [username]
-k [key] -s [secret]

參數

edgemicro revokekeys -o ORG-NAME -e ENV-NAME -k KEY-TO-REVOKE \
    -s KEY-SECRET -t TOKEN

例子

edgemicro revokekeys -o myorg -e test -u jdoe@apigee.com
-k 2c0064f5bd85f5573dcaffe21566fa7a2d49885cdbf8899370c8a4479285f -s 4b5d6355b874f7c46838893823e8d929dcb2e42fb9aebcb535089c9b98513

成功後，您會看見下列訊息：