您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。
Apigee Edge 可讓您發出使用 OAuth2 權杖進行驗證的 Edge API 呼叫。Cloud 帳戶預設會為 Edge 帳戶啟用 OAuth2 支援功能。如果您使用的是 Edge for Private Cloud,您必須先設定 SAML 或 LDAP,才能使用 OAuth2。
OAuth2 的運作方式 (與 Apigee Edge API 搭配使用)
呼叫 Apigee Edge API 時必須進行驗證,才能確認您是誰。為了驗證身分,您必須使用要求存取 API 的 OAuth2 存取權杖。
舉例來說,如果您想取得 Edge 上的機構詳細資料,可以向下列網址傳送要求:
https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval
但你必須表明自己的身分,才能傳送要求。否則,所有人都能查看貴機構的詳細資料。
此時 OAuth2 就派上用場了。在驗證要求中,我們也需要將存取權杖傳送給我們。存取權杖會告訴我們您的身分,以便確保您能看到機構詳細資料。
幸好,您可以透過將憑證傳送至 Edge OAuth2 服務來取得權杖。這項服務會回應存取和重新整理權杖。
OAuth2 流程:初始要求
下圖顯示了第一次存取 Edge API 時的 OAuth2 流程:

如圖 1 所示,首次向 Edge API 發出要求時:
- 你要求存取權杖。您可以使用 Edge API、acurl 或
get_token
完成這項操作。例如:get_token Enter username:
ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'[hidden input]
Enter the six-digit code if 'ahamilton@apigee.com' is MFA enabled or press ENTER:123456
- Edge OAuth2 服務會透過存取權杖回應,並列印至
stdout
;例如:Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0 RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG 420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M 2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw
acurl
和get_token
公用程式會默示將存取和重新整理權杖儲存至~/.sso-cli
(重新整理權杖不會寫入stdout
)。如果您使用 Edge OAuth2 服務取得權杖,則必須儲存憑證以供日後使用。 - 您利用存取權杖將要求傳送至 Edge API。
acurl
會自動附加權杖,例如:acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval
如果您使用的是其他 HTTP 用戶端,請務必新增存取權杖。例如:
curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \ -H "Authorization: Bearer ACCESS_TOKEN"
- Edge API 會執行你的要求,且通常會傳回包含資料的回應。
OAuth2 流程:後續的要求
針對後續的要求,你不需要交換憑證。您可以加入先前擁有的存取權杖,前提是該憑證尚未過期:

如圖 2 所示,您已擁有存取權杖:
- 您利用存取權杖將要求傳送至 Edge API。
acurl
會自動附加權杖。使用其他工具時,必須手動新增權杖。 - Edge API 會執行你的要求,且通常會傳回包含資料的回應。
OAuth2 流程:存取權杖到期
如果存取權杖過期 (12 小時後),您可以使用更新權杖取得新的存取權杖:

如圖 3 所示,存取權杖已過期時:
- 您將要求傳送至 Edge API,但存取權杖已過期。
- Edge API 會拒絕未經授權的要求。
- 您將更新權杖傳送至 Edge OAuth2 服務。如果您使用的是
acurl
,系統會自動為您完成這項作業。 - Edge OAuth2 服務可回應新的存取權杖。
- 您會使用新的存取權杖將要求傳送至 Edge API。
- Edge API 會執行你的要求,且通常會傳回包含資料的回應。
取得權杖
如要取得可傳送至 Edge API 的存取權杖,除了 curl
等公用程式以外,您還可以使用下列 Apigee 公用程式:
- get_token 公用程式:交換 Apigee 憑證,以便存取及重新整理可用來呼叫 Edge API 的權杖。
- acurl 公用程式:提供標準
curl
指令的便利包裝函式。建構至 Edge API 的 HTTP 要求、從get_token
存取及重新整理權杖,並將存取權杖傳遞至 Edge API。 - 邊緣 OAuth2 服務中的端點端點:透過呼叫 Edge API,交換 Apigee 憑證來取得存取權並更新權杖。
這些公用程式會交換您的 Apigee 帳戶憑證 (電子郵件地址和密碼),但其中包含的持續時間如下:
- 存取權杖將於 12 小時後失效。
- 更新權杖的有效期限為 30 天。
因此,如果您成功透過 acurl
或 get_token
發出 API 呼叫,30 天內可以繼續使用權杖配對。到期後,您必須重新輸入憑證並取得新的權杖。
透過 OAuth2 存取 Edge API
如要存取 Edge API,請將要求傳送至 API 端點,並加入存取權杖。您可以透過任何 HTTP 用戶端執行這項操作,包括 curl
等指令列公用程式、透過瀏覽器為基礎的使用者介面 (例如 Postman),或 Apigee 公用程式 (例如 acurl
)。
以下各節會說明使用 acurl
和 curl
存取 Edge API 的相關說明。
使用 curl
如要透過 acurl
存取 Edge API,您的初始要求必須包含憑證。Edge OAuth2 服務會透過存取及更新權杖回應。acurl
會將權杖儲存在本機。
後續要求時,acurl
會使用 ~/.sso-cli
中儲存的權杖,因此在憑證到期前,您都不需要再次納入憑證。
下例顯示初始 acurl
要求,取得「ahamilton-eval」機構的詳細資料:
acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \ -u ahamilton@apigee.com Enter the password for user 'ahamilton@apigee.com'[hidden input]
Enter the six-digit code (no spaces) if 'ahamilton@apigee.com' is MFA-enabled or press ENTER:1a2b3c
{ "createdAt" : 1491854501264, "createdBy" : "noreply_iops@apigee.com", "displayName" : "ahamilton", "environments" : [ "prod", "test" ], "lastModifiedAt" : 1491854501264, "lastModifiedBy" : "noreply_iops@apigee.com", "name" : "ahamilton", "properties" : { "property" : [ { "name" : "features.isSmbOrganization", "value" : "false" }, { "name" : "features.isCpsEnabled", "value" : "true" } ] }, "type" : "trial" }acurl https://api.enterprise.apigee.com/v1/o/ahamilton-eval/apis/helloworld/revisions/1/policies
[ "SOAP-Message-Validation-1", "Spike-Arrest-1", "XML-to-JSON-1" ]
除了取得機構的詳細資料外,這個範例也顯示第二次要求,取得「helloworld」API Proxy 中的政策清單。第二個要求會在網址中使用「機構」這個縮短的「o」。
請注意,acurl
會自動在第二個要求中傳遞存取權杖。acurl
儲存 OAuth2 權杖後,不需要傳遞使用者憑證,系統會從 ~/.sso-cli
取得後續呼叫的權杖。
詳情請參閱使用 curl 存取 Edge API。
使用 curl
您可以使用 curl
存取 Edge API。為此,您必須先取得存取權並更新權杖。您可以使用 get_token
或 Edge OAuth2 服務等公用程式取得這些憑證。
成功儲存存取權杖後,您必須在呼叫 Edge API 的呼叫中,將其傳送至 Authorization
標頭,如以下範例所示:
curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \ -H "Authorization: Bearer ACCESS_TOKEN"
存取權杖核發後,有效期限為 12 小時。存取權杖到期後,更新權杖可在 30 天內發出另一個存取權杖,且無需提供憑證。Apigee 建議只在述詞權杖到期後要求新的存取權杖,不要輸入憑證並針對每個 API 呼叫提出新的要求。
權杖到期
存取權杖到期後,您可以使用更新權杖取得新的存取權杖,無須再次提交憑證。
視您使用的工具而定,更新存取權杖的方式會有所不同:
acurl
:無須採取任何行動。當你傳送包含過時權杖的要求時,acurl
會自動重新整理存取權杖。get_token
:呼叫get_token
以更新存取權杖。- Edge OAuth2 服務:傳送包含下列項目的要求:
- 重新整理權杖
grant_type
個表單參數已設為「refresh_token」
適用於電腦使用者的 OAuth2
您可以使用 acurl
和 get_token
公用程式,透過適用於機器使用者的 OAuth2 驗證機制,自動存取 Edge API。以下範例說明如何使用 get_token
要求存取權杖,然後將權杖值新增至 curl
呼叫:
USER=me@example.com
PASS=not-that-secret
TOKEN=$(get_token -u $USER:$PASS -m '')
curl -H "Authorization: Bearer $TOKEN" 'https://api.enterprise.apigee.com/v1/organizations/...'
或者,您也可以使用 acurl
公用程式來合併權杖要求和 curl
呼叫。例如:
USER=me@example.com
PASS=not-that-secret
acurl -u $USER:$PASS -m '' 'https://api.enterprise.apigee.com/v1/organizations/...'
在這兩種範例中,如果將 -m
的值設為空白字串,系統會避免機器使用者收到 MFA 程式碼。