使用 Edge API 發布 API

您正在查看 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 產品)。

根據預設,資源路徑會透過 proxy.pathsuffix 變數對應。Proxy 路徑後置字串定義為緊接 Proxy 端點基本路徑的 URI 片段。例如,在下方的 API 範例產品中,apiResources 元素定義為 /forecastrss。由於這個 API Proxy 定義的基本路徑為 /weather,這表示此 API 產品只允許向 /weather/forecastrss 發出的要求。

您可以選取特定路徑,或選取所有含有萬用字元的子路徑。支援萬用字元 (/** 和 /*)。雙星號萬用字元表示包含所有子 URI。一個星號表示只會納入一個層級的 URI。

根據預設,'/' 支援與「/**」相同的資源,以及 API Proxy 定義的基本路徑。舉例來說,如果 API Proxy 的基本路徑為 /v1/weatherapikey,則 API 產品支援向 /v1/weatherapikey 和任何子 URI 提出的要求,例如 /v1/weatherapikey/forecastrss/v1/weatherapikey/region/CA 等。如要瞭解如何變更這項預設行為,請參閱「管理 API 產品」一文。

不適用
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 產品:

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 會執行下列程序:

  1. Apigee Edge 已收到要求,並轉送至適當的 API Proxy。
  2. 系統會執行政策,驗證用戶端顯示的 API 金鑰或 OAuth 存取權杖。
  3. Edge 可將 API 金鑰或存取權杖解析為應用程式設定檔。
  4. 邊緣會解析與應用程式相關聯的 API 產品清單 (如有)。
  5. 符合的第一個 API 產品會用來填入配額變數。
  6. 如果沒有 API 產品符合 API 金鑰或存取權杖,要求就會遭拒。
  7. Edge 會根據 API 產品設定和配額設定,強制執行以 URI 為基礎的存取權控管機制 (環境、API Proxy 和 URI 路徑)。