使用 Edge API 发布 API

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档
信息

本部分介绍如何使用 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 产品。对部署在 test 环境中的 API 代理(称为 weatherapi)所公开的所有 API,此 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 代理授权。它定义了一个 API 产品,使授权的应用可以访问通过在测试环境中运行的 API 代理访问的任何 API 资源。API 产品提供了其他配置设置,可让您针对不同的开发者群组自定义对 API 的访问权限控制。例如,您可以创建两个提供不同 API 代理访问权限的 API 产品。您还可以创建两个 API 产品,这些产品提供对相同 API 代理的访问权限,但具有不同的关联配额设置。

API 产品配置设置

API 产品提供以下配置选项:

名称 说明 默认 重启?
apiResources

捆绑到 API 产品中的 URI 或资源路径逗号分隔列表。

默认情况下,资源路径是从 proxy.pathsuffix 变量映射的。代理路径后缀被定义为位于 ProxyEndpoint 基本路径后面的 URI 片段。例如,在以下示例 API 产品中,apiResources 元素定义为 /forecastrss。由于此 API 代理定义的基本路径为 /weather,这表示只有此 API 产品允许对 /weather/forecastrss 的请求。

您可以选择特定路径,也可以选择带通配符的所有子路径。 支持通配符(/** 和 /*)。双星号通配符表示包含所有子 URI。一个星号表示仅包含一个级别的 URI。

默认情况下,“'/”支持与“/**”相同的资源,以及由 API 代理定义的基本路径。例如,如果 API 代理的基本路径是 /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 代理。通过指定代理,您可以将 API 产品内的资源与特定 API 代理相关联,从而防止开发者通过其他 API 代理访问这些资源。 不适用 否。如果未定义,则必须明确定义 apiResources(请参阅上文的 apiResources 信息),以及 AssignMessage 政策中设置的 flow.resource.name 变量。
environments 此 API 产品所绑定到的命名环境(例如“test”或“prod”)。通过指定一个或多个环境,您可以将 API 产品中列出的资源绑定到特定环境,以防止开发者通过其他环境中的 API 代理访问这些资源。例如,此设置用于防止与“prod”中的 API 代理相关联的资源被“test”中部署的 API 代理访问。 不适用 否。如果未定义,则必须明确定义 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 的开发者注册了个人资料,并使用 Create developer 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 产品关联。作为管理员,您可以随时使用获取开发者应用 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 产品到密钥 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 代理流程:

  • 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 代理。
  2. 执行的政策用于验证客户端提供的 API 密钥或 OAuth 访问令牌。
  3. Edge 将 API 密钥或访问令牌解析为应用配置文件。
  4. Edge 会解析与应用关联的 API 产品的列表(如果有)。
  5. 第一个匹配的 API 产品用于填充配额变量。
  6. 如果没有与 API 密钥或访问令牌匹配的 API 产品,则请求会被拒绝。
  7. Edge 会根据 API 产品设置和配额设置,强制执行基于 URI 的访问权限控制(环境、API 代理和 URI 路径)。