Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用 Edge API 發布 API

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

本節說明如何使用 Edge API 建立 API 產品，以便在開發人員入口網站中發布。

使用 API 建立 API 產品

開發人員可透過 API 產品，使用 API 金鑰和 OAuth 存取權杖註冊會耗用 API 的應用程式。API 產品的設計目的是讓您「組合」API 資源，然後將這些組合發布給不同的開發人員群組。舉例來說，您可能需要向合作夥伴開發人員發布一組 API 資源，同時向外部開發人員發布另一組資源。API 產品可讓您即時執行這項組合作業，不必變更 API 本身。此外，開發人員存取權可「升級」和「降級」，開發人員不必為應用程式取得新的消費者金鑰，也是一項優點。

如要使用 API 建立 API 產品，請對 /organizations/{org_name}/apiproducts 發出 POST 要求。詳情請參閱「建立 API 產品」API 參考資料。

下列要求會建立名為 weather_free 的 API 產品。API 產品可存取 API Proxy (名為 weatherapi) 在 test 環境中部署時公開的所有 API。核准類型設為 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 產品，分別提供不同 API Proxy 的存取權。您也可以建立兩個 API 產品，提供相同 API Proxy 的存取權，但配額設定不同。

API 產品設定

API 產品會公開下列設定選項：

名稱	說明	預設	是否必要？
`apiResources`	以逗號分隔的 URI 清單，或「組合」到 API 產品中的資源路徑。根據預設，資源路徑會從 `proxy.pathsuffix` 變數對應。Proxy 路徑後置字串定義為 ProxyEndpoint 底層路徑後方的 URI 片段。舉例來說，在下方的 API 產品範例中，`apiResources` 元素定義為 `/forecastrss`。由於這個 API Proxy 定義的「基本路徑」是 `/weather`，因此這個 API 產品只允許對 `/weather/forecastrss` 發出要求。您可以選取特定路徑，也可以使用萬用字元選取所有子路徑。支援萬用字元 (/** 和 /)。雙星號萬用字元表示包含所有子 URI。單一星號表示只會納入下一層級的 URI。根據預設，'/' 支援與 '/*' 相同的資源，以及 API Proxy 定義的 Base Path。舉例來說，如果 API Proxy 的基本路徑為 /v1/weatherapikey，則 API 產品支援對 /v1/weatherapikey 和任何子 URI 的要求，例如 /v1/weatherapikey/forecastrss、/v1/weatherapikey/region/CA 等。如要瞭解如何變更這項預設行為，請參閱「管理 API 產品」。	N/A	否
`approvalType`	指定如何核准 API 金鑰，以存取 API 產品定義的 API。如果設為 `manual`，系統為應用程式產生的金鑰會處於「待處理」狀態。這類金鑰必須經過明確核准才能運作。如果設為 `auto`，所有金鑰都會在「已核准」狀態下產生，並立即生效。(`auto` 通常用於提供免費/試用 API 產品的存取權，這類產品的配額或功能有限。)	N/A	是
`attributes`	可用於擴充預設 API 產品設定檔的屬性陣列，其中包含客戶專屬的中繼資料。使用這項屬性將 API 產品的存取層級指定為「公開」、「私人」或「內部」。例如： "attributes": [ { "name": "access", "value": "public" }, { "name": "foo", "value": "foo" }, { "name": "bar", "value": "bar" } ]	N/A	否
`scopes`	以半形逗號分隔的 OAuth 範圍清單，會在執行階段驗證。(Apigee Edge 會驗證所提供的任何存取權杖中的範圍，是否與 API 產品中設定的範圍相符)。	N/A	否
`proxies`	這個 API 產品繫結的具名 API Proxy。指定 Proxy 後，您就能將 API 產品中的資源與特定 API Proxy 建立關聯，防止開發人員透過其他 API Proxy 存取這些資源。	N/A	否。如未定義，則必須明確定義 `apiResources` (請參閱上方的 `apiResources` 資訊)，並在 AssignMessage 政策中設定 `flow.resource.name` 變數。
`environments`	這個 API 產品繫結的具名環境 (例如「test」或「prod」)。指定一或多個環境後，您就能將 API 產品中列出的資源繫結至特定環境，防止開發人員透過其他環境中的 API Proxy 存取這些資源。舉例來說，這項設定可防止部署在「test」中的 API Proxy 存取與「prod」中 API Proxy 相關聯的資源。	N/A	否。如未定義，則必須明確定義 `apiResources`，並在 AssignMessage 政策中設定 `flow.resource.name` 變數。
`quota`	在指定時間間隔內，每個應用程式可提出的要求數量。	N/A	否
`quotaInterval`	評估配額的時間單位數	N/A	否
`quotaTimeUnit`	計算配額的時間單位 (分鐘、小時、天或月)。	N/A	否

以下提供建立 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 a 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 產品，請使用 Add API Product to 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 產品的關聯，請使用「Approve or Revoke Specific Key of Developer App」(核准或撤銷開發人員應用程式的特定金鑰) 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 代理流程：

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 金鑰或存取權杖解析為應用程式設定檔。
Edge 會解析與應用程式相關聯的 API 產品清單 (如有)。
系統會使用第一個相符的 API 產品填入配額變數。
如果沒有任何 API 產品與 API 金鑰或存取權杖相符，系統就會拒絕要求。
Edge 會根據 API 產品設定和配額設定，強制執行以 URI 為準的存取權控管 (環境、API Proxy 和 URI 路徑)。