您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
本節說明如何使用 Edge API 建立要在開發人員入口網站中發布的 API 產品。
使用 API 建立 API 產品
API 產品可讓開發人員註冊使用 API 金鑰和 OAuth 存取權杖的應用程式。API 產品的設計可讓您將 API 資源「套裝組合」提供給不同的開發人員群組。舉例來說,您可能需要向合作夥伴開發人員發布一組 API 資源,然後向外部開發人員發布另一個套裝組合。API 產品可讓您即時執行這項設定,無須自行變更 API。另外,開發人員不必為應用程式取得新的用戶端金鑰,就能「升級」和「降級」的存取權。
如要使用 API 建立 API 產品,請向 /organizations/{org_name}/apiproducts
發出 POST 要求。
詳情請參閱「建立 API 產品」API 參考資料。
下列要求會建立名為 weather_free
的 API 產品。API 產品可讓您存取由 API Proxy 公開的所有 API (名為 weatherapi
),該 API 是部署於 test
環境中。核准類型設為 auto
,表示所有存取權要求都會獲準。
curl -X POST https://api.enterprise.apigee.com/v1/organization/myorg/apiproducts \ -H "Content-Type:application/json" \ -d \ '{ "approvalType": "auto", "displayName": "Free API Product", "name": "weather_free", "proxies": [ "weatherapi" ], "environments": [ "test" ] }' \ -u email:password
回應範例:
{ "apiResources" : [ ], "approvalType" : "auto", "attributes" : [ ], "createdAt" : 1362759663145, "createdBy" : "developer@apigee.com", "displayName" : "Free API Product", "environments" : [ "test" ], "lastModifiedAt" : 1362759663145, "lastModifiedBy" : "developer@apigee.com", "name" : "weather_free", "proxies" : [ "weatherapi" ], "scopes" : [ ] }
在上方建立的 API 產品會導入最基本情境,授權對環境中的 API Proxy 要求。它會定義一項 API 產品,可讓授權應用程式存取在測試環境中透過 API Proxy 存取的任何 API 資源。API 產品提供了額外的配置設定,可讓您針對不同的開發人員群組自訂 API 的存取權控管機制。舉例來說,您可以建立兩個提供不同 API Proxy 存取權的 API 產品,您也可以建立兩個 API 產品,為相同的 API Proxy 提供不同相關聯配額設定的存取權。
API 產品配置設定
API 產品包含下列設定選項:
名稱 | 說明 | 預設 | 必填與否 |
---|---|---|---|
apiResources |
以逗號分隔的 URI 清單,或「資源路徑」(組合至 API 產品)。 根據預設,資源路徑會透過 您可以選取特定路徑,或選取所有含有萬用字元的子路徑。支援萬用字元 (/** 和 /*)。雙星號萬用字元表示包含所有子 URI。一個星號表示只會納入一個層級的 URI。 |
不適用 | 否 |
approvalType |
指定如何核准 API 金鑰,以便存取 API 產品定義的 API。如果設為 manual ,為應用程式產生的金鑰會處於「待處理」狀態。這類金鑰必須等到明確核准後才能運作。如果設為 auto ,所有金鑰都會在「已核准」中產生並立即運作。(auto 通常用於提供配額有限或功能有限的免費/試用版 API 產品。) |
不適用 | 是 |
attributes |
屬性陣列,可用來擴充預設 API 產品設定檔的客戶專屬中繼資料。
請使用這項屬性,將 API 產品的存取層級指定為「公開」、「私人」或「內部」。例如:
"attributes": [
{
"name": "access",
"value": "public"
},
{
"name": "foo","value": "foo" }, { "name": "bar", "value": "bar" }
]
|
不適用 | 否 |
scopes |
會在執行階段驗證的 OAuth 範圍清單 (以半形逗號分隔),(Apigee Edge 會驗證任何存取權杖中的範圍,是否與 API 產品中設定的範圍相符)。 | 不適用 | 否 |
proxies |
與這個 API 產品繫結的已命名 API Proxy。您可以透過指定 Proxy 將 API 產品中的資源與特定 API Proxy 建立關聯,避免開發人員透過其他 API Proxy 存取這些資源。 | 不適用 | 否。如未定義,則必須明確定義 apiResources (請參閱上方的 apiResources 資訊),以及 AssignMessage 政策中設定的 flow.resource.name 變數。 |
environments |
這個 API 產品繫結的環境 (例如「test」或「prod」)。 您可以透過指定一或多個環境,將 API 產品中列出的資源繫結至特定環境,防止開發人員在其他環境中透過 API Proxy 存取這些資源。例如,使用這項設定可避免「test」中部署的 API Proxy 存取「prod」中與 API Proxy 相關聯的資源。 | 不適用 | 否。如未定義,則必須明確定義 apiResources ,且在 AssignMessage 政策中設定 flow.resource.name 變數。 |
quota |
每個應用程式在指定時間間隔內允許的要求數量。 | 不適用 | 否 |
quotaInterval |
評估配額的時間單位數量 | 不適用 | 否 |
quotaTimeUnit |
計算配額的時間單位 (分鐘、小時、日或月)。 | 不適用 | 否 |
以下提供建立 API 產品的詳細範例。
curl -X POST https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts \ -H "Content-Type:application/json" -d \ '{ "apiResources": [ "/forecastrss" ], "approvalType": "auto", "attributes": [ {"name": "access", "value": "public"} ], "description": "Free API Product", "displayName": "Free API Product", "name": "weather_free", "scopes": [], "proxies": [ "weatherapi" ], "environments": [ "test" ], "quota": "10", "quotaInterval": "2", "quotaTimeUnit": "hour" }' \ -u email:password
回應範例
{ "apiResources" : [ "/forecastrss" ], "approvalType" : "auto", "attributes" : [ { "name" : "access", "value" : "public" }, "createdAt" : 1344454200828, "createdBy" : "admin@apigee.com", "description" : "Free API Product", "displayName" : "Free API Product", "lastModifiedAt" : 1344454200828, "lastModifiedBy" : "admin@apigee.com", "name" : "weather_free", "scopes" : [ ], "proxies": [ {'weatherapi'} ], "environments": [ {'test'} ], "quota": "10", "quotaInterval": "1", "quotaTimeUnit": "hour"}' }
關於範圍
「範圍」是衍生自 OAuth 的概念,大致對應到「權限」的概念。在 Apigee Edge 中,範圍完全是選用的。您可以使用範圍執行更精細的授權。每個核發至應用程式的用戶端金鑰都與「主要範圍」建立關聯。主要範圍是這個應用程式中所有 API 產品的所有範圍組合,都已獲核准。如果應用程式已獲準使用多項 API 產品,主要範圍是用戶端金鑰已核准的 API 產品中定義的所有範圍聯集。
查看 API 產品
如要查看透過 API 為機構建立的 API 產品,請參閱以下各節:
- 查看 API 產品 (營利)
根據預設,系統只會顯示營利 API 產品 (也就是至少具備一個已發布費率方案的 API 產品)。 如要顯示所有 API 產品,請將
monetized
查詢參數設為false
。這相當於向非營利 List API 產品 API 發出 GET 要求:https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts?expand=true
- 查看 API 產品 (未啟用營利功能)
- 查看開發人員適用的 API 產品
- 查看公司符合資格的 API 產品
以下範例說明如何使用 API 查看 API 產品:
curl -X GET "https://ext.apiexchange.org/v1/mint/organizations/{org_name}/products?monetized=true" \ -H "Accept:application/json" \ -u email:password
回應應如下所示 (只會顯示回應的一部分):
{ "product" : [ { "customAtt1Name" : "user", "customAtt2Name" : "response size", "customAtt3Name" : "content-length", "description" : "payment api product", "displayName" : "payment", "id" : "payment", "name" : "payment", "organization" : { ... }, "pricePoints" : [ ], "status" : "CREATED", "transactionSuccessCriteria" : "status == 'SUCCESS'" }, { "customAtt1Name" : "user", "customAtt2Name" : "response size", "customAtt3Name" : "content-length", "description" : "messaging api product", "displayName" : "messaging", "id" : "messaging", "name" : "messaging", "organization" : ... }, "pricePoints" : [ ], "status" : "CREATED", "transactionSuccessCriteria" : "status == 'SUCCESS'" } ], "totalRecords" : 2 }
使用 API 為開發人員註冊
所有應用程式都屬於開發人員或公司。因此,如要建立應用程式,您必須先註冊開發人員或公司。
開發人員是以建立個人資料的方式在機構中註冊。請注意,設定檔中的開發人員電子郵件會做為開發人員在整個 Apigee Edge 中的唯一金鑰。
如要支援營利,您必須在建立或編輯開發人員時定義營利屬性。您也可以定義其他任意屬性,用於自訂分析、自訂政策強制執行等;Apigee Edge 不會解讀這些任意屬性。
舉例來說,下列要求會為電子郵件地址為 ntesla@theremin.com
的開發人員註冊設定檔,並使用「建立開發人員」 API 定義部分營利屬性:
$ curl -H "Content-type:application/json" -X POST -d \ '{"email" : "ntesla@theremin.com", "firstName" : "Nikola", "lastName" : "Tesla", "userName" : "theremin", "attributes" : [ { "name" : "project_type", "value" : "public" }, { "name": "MINT_BILLING_TYPE", "value": "POSTPAID" }, { "name": "MINT_DEVELOPER_ADDRESS", "value": "{\"address1\":\"Dev One Address\",\"city\":\"Pleasanton\",\"country\":\"US\",\"isPrimary\":true,\"state\":\"CA\",\"zip\":\"94588\"}" }, { "name": "MINT_DEVELOPER_TYPE", "value": "TRUSTED" }, { "name": "MINT_HAS_SELF_BILLING, "value": "FALSE" }, { "name" : "MINT_SUPPORTED_CURRENCY", "value" : "usd" } ] }' \ https://api.enterprise.apigee.com/v1/o/{org_name}/developers \ -u email:password
回應範例
{ "email" : "ntesla@theremin.com", "firstName" : "Nikola", "lastName" : "Tesla", "userName" : "theremin", "organizationName" : "{org_name}", "status" : "active", "attributes" : [ { "name" : "project_type", "value" : "public" }, { "name": "MINT_BILLING_TYPE", "value": "POSTPAID" }, { "name": "MINT_DEVELOPER_ADDRESS", "value": "{\"address1\":\"Dev One Address\",\"city\":\"Pleasanton\",\"country\":\"US\",\"isPrimary\":true,\"state\":\"CA\",\"zip\":\"94588\"}" }, { "name": "MINT_DEVELOPER_TYPE", "value": "TRUSTED" }, { "name": "MINT_HAS_SELF_BILLING, "value": "FALSE" }, { "name" : "MINT_SUPPORTED_CURRENCY", "value" : "usd" } ], "createdAt" : 1343189787717, "createdBy" : "admin@apigee.com", "lastModifiedAt" : 1343189787717, "lastModifiedBy" : "admin@apigee.com" }
使用 API 註冊開發人員應用程式
凡是在 Apigee Edge 中註冊的應用程式,都與開發人員和 API 產品相關聯。當應用程式代表開發人員註冊時,Apigee Edge 會產生用來識別應用程式的「憑證」(用戶端金鑰和密鑰配對)。接著,應用程式必須在每個要求中,將這些憑證傳送至與應用程式相關聯的 API 產品。
下列要求會使用 Create Developer App API 為上方建立的開發人員註冊應用程式:ntesla@theremin.com。註冊應用程式時,您必須定義應用程式名稱、callbackUrl,以及一或多個 API 產品的清單:$ curl -H "Content-type:application/json" -X POST -d \ '{ "apiProducts": [ "weather_free"], "callbackUrl" : "login.weatherapp.com", "keyExpiresIn" : "2630000000", "name" : "weatherapp"}' \ https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps \ -u email:password
某些 OAuth 授權類型 (例如授權碼) 會使用 callbackUrl 驗證應用程式的重新導向要求。如果您使用 OAuth,這個值必須設為與用來發出 OAuth 要求的 redirect_uri
相同的值。
keyExpiresIn
屬性會指定將為開發人員應用程式產生的消費者金鑰生命週期內 (以毫秒為單位)。預設值 (-1) 表示無限有效期間。
回應範例
{ "appId": "5760d130-528f-4388-8c6f-65a6b3042bd1", "attributes": [ { "name": "DisplayName", "value": "Test Key Expires" }, { "name": "Notes", "value": "Just testing this attribute" } ], "createdAt": 1421770824390, "createdBy": "wwitman@apigee.com", "credentials": [ { "apiProducts": [ { "apiproduct": "ProductNoResources", "status": "approved" } ], "attributes": [], "consumerKey": "jcAFDcfwImkJ19A5gTsZRzfBItlqohBt", "consumerSecret": "AX7lGGIRJs6s8J8y", "expiresAt": 1424400824401, "issuedAt": 1421770824401, "scopes": [], "status": "approved" } ], "developerId": "e4Oy8ddTo3p1BFhs", "lastModifiedAt": 1421770824390, "lastModifiedBy": "wwitman@apigee.com", "name": "TestKeyExpires", "scopes": [], "status": "approved" }
使用 API 管理應用程式的用戶端金鑰
取得應用程式的用戶端金鑰 (API 金鑰)
應用程式憑證 (API 產品、用戶端金鑰和密鑰) 會做為應用程式設定檔的一部分傳回。機構管理員可以隨時擷取用戶端金鑰。
應用程式設定檔會顯示用戶端金鑰和密鑰的值、用戶端金鑰狀態,以及該金鑰的任何 API 產品關聯。管理員隨時可以使用 Get Key Details for the Developer App API 擷取用戶端金鑰設定檔:
$ curl -X GET -H "Accept: application/json" \ https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J \ -u email:password
回應範例
{ "apiProducts" : [ { "apiproduct" : "weather_free", "status" : "approved" } ], "attributes" : [ ], "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J", "consumerSecret" : "1eluIIdWG3JGDjE0", "status" : "approved" }
詳情請參閱「 取得開發人員應用程式的重要詳細資料」。
將 API 產品新增至應用程式和金鑰
如要更新應用程式以新增 API 產品,您必須使用將 API 產品新增至 Key API,將 API 產品新增至應用程式的金鑰。詳情請參閱「 將 API 產品新增至金鑰」一文。
將 API 產品新增至應用程式金鑰,可讓保存金鑰的應用程式存取 API 產品隨附的 API 資源。下列方法呼叫會將新的 API 產品新增至應用程式:
$ curl -H "Content-type:application/json" -X POST -d \ '{ "apiProducts": [ "newAPIProduct"] }' \ https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J \ -u email:password
回應範例:
{ "apiProducts": [ { "apiproduct": "weather_free", "status": "approved" }, { "apiproduct": "newAPIProduct", "status": "approved" } ], "attributes": [], "consumerKey": "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J", "consumerSecret": "1eluIIdWG3JGDjE0", "expiresAt": -1, "issuedAt": 1411491156464, "scopes": [], "status": "approved" }
核准用戶端金鑰
將核准類型設為手動可讓您控制哪些開發人員能存取受 API 產品保護的資源。當 API 產品的金鑰核准設為 manual
時,用戶端金鑰必須明確獲得核准。您可以使用核准或撤銷開發人員應用程式的特定金鑰 API 明確核准金鑰:
$ curl -X POST -H "Content-type:appilcation/octet-stream" \ https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J?"action=approve" \ -u email:password
回應範例
{ "apiProducts" : [ { "apiproduct" : "weather_free", "status" : "approved" } ], "attributes" : [ ], "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J", "consumerSecret" : "1eluIIdWG3JGDjE0", "status" : "approved" }
詳情請參閱「 核准或撤銷開發人員應用程式的特定金鑰」。
核准用戶端金鑰的 API 產品
API 產品與消費者金鑰的關聯也有狀態。用戶端金鑰必須獲得核准,「且」用戶端金鑰必須獲準才能使用適當的 API 產品,API 存取權才能成功存取。您可以使用核准或撤銷開發人員應用程式金鑰的 API 產品 API,核准消費者金鑰與 API 產品之間的關聯:
$ curl -X POST -H "Content-type:application/octet-stream" \ https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J/apiproducts/weather_free?"action=approve" \ -u email:password
這個 cURL 指令不會傳回回應。詳情請參閱「 核准或撤銷開發人員應用程式金鑰的 API 產品」。
撤銷用戶端金鑰的 API 產品
您可能需要基於多種原因,撤銷用戶端金鑰與 API 產品之間的關聯。如果開發人員並未付款、試用期結束或應用程式從某項 API 產品升級為其他 API 產品,您可能需要將 API 產品從消費者金鑰中移除。
如要撤銷用戶端金鑰與 API 產品之間的關聯,請使用「核准或撤銷開發人員應用程式特定金鑰」 API,方法是針對開發應用程式的用戶端金鑰撤銷操作:
$ curl -X POST -H "Content-type:application/octet-stream" \ https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J/apiproducts/weather_free?"action=revoke" \ -u email:password
這個 cURL 指令不會傳回回應。詳情請參閱「 核准或撤銷開發人員應用程式的特定金鑰」。
強制執行 API 產品設定
如要強制執行 API 產品,必須將以下其中一種政策類型附加至 API Proxy 流程:
- VerifyAPIKey:擷取 API 金鑰的參照、驗證該金鑰代表有效的應用程式,並且與 API 產品相符。詳情請參閱「驗證 API 金鑰政策」一文。
- OAuthV1,「VerifyAccessToken」作業:驗證簽章、驗證 OAuth 1.0a 存取權杖和「用戶端金鑰」,並將應用程式與 API 產品進行比對。詳情請參閱 OAuth v1.0a 政策。
- OAuthV2「VerifyAccessToken」作業:驗證 OAuth 2.0 存取權杖是否有效、比對權杖與應用程式、驗證應用程式是否有效,然後將應用程式與 API 產品進行比對。詳情請參閱 OAuth 首頁。
政策和 API 產品設定完成後,Apigee Edge 會執行下列程序:
- Apigee Edge 已收到要求,並轉送至適當的 API Proxy。
- 系統會執行政策,驗證用戶端顯示的 API 金鑰或 OAuth 存取權杖。
- Edge 可將 API 金鑰或存取權杖解析為應用程式設定檔。
- 邊緣會解析與應用程式相關聯的 API 產品清單 (如有)。
- 符合的第一個 API 產品會用來填入配額變數。
- 如果沒有 API 產品符合 API 金鑰或存取權杖,要求就會遭拒。
- Edge 會根據 API 產品設定和配額設定,強制執行以 URI 為基礎的存取權控管機制 (環境、API Proxy 和 URI 路徑)。