您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息
学习内容
通过本教程,您将学会:
- 创建需要 API 密钥的 API 代理。
- 添加 API 产品。
- 添加开发者并注册应用。
- 使用 API 密钥调用 API。
请务必保护您的 API 免遭未经授权的访问。一种方法是使用 API 密钥(也称为公钥、使用方密钥或应用密钥)。
当应用向您的 API 发出请求时,必须提供有效的密钥。在运行时,“验证 API 密钥”政策会检查所提供的 API 密钥是否:
- 有效
- 尚未撤消
- 与公开了所请求资源的 API 产品的 API 密钥相匹配
如果密钥有效,则允许请求。如果密钥无效,请求会导致授权失败。
在本教程中,您将创建一个需要有效 API 密钥才能访问的 API 代理。
所需条件
- Apigee Edge 账号。如果您还没有 Apigee Edge 帐号,可按照 创建 Apigee Edge 帐号中的说明进行注册。
- 用于进行 API 调用的网络浏览器。
- (对于额外的赠金部分,不需要)在您的机器上安装 cURL,以从命令行进行 API 调用。
创建 API 代理
- 前往 https://apigee.com/edge 并登录。
点击侧边导航栏顶部的用户名以显示用户个人资料菜单,然后从列表中选择组织,以切换到所需的组织。
-
点击着陆页上的 API 代理以显示 API 代理列表。
- 点击 + Proxy。
- 在创建代理页面上,选择反向代理(最常见)。
- 在代理详细信息页面上,按如下方式配置代理:
在此字段中 执行该操作 代理名称 输入: helloworld_apikey
项目基本路径 更改为:
/helloapikey
项目基本路径是用于向 API 代理发出请求的网址的一部分。
注意:如需查看 Apigee 的 API 版本控制建议,请参阅 Web API 设计:缺失的链接电子书中的 版本控制。
现有 API 输入:
http://mocktarget.apigee.net
这定义了 Apigee Edge 在向 API 代理发出请求时调用的目标网址。
说明 输入: hello world protected by API key
- 点击下一步。
- 在通用政策页面的安全性:授权部分,选择 API 密钥,然后点击下一步。这会向您的 API 代理添加两项政策。
- 在 Virtual Hosts 页面上,选择 default 和 secure,然后点击 Next。选择 default 后,您可以使用
http://
调用 API。选择安全后,您就可以通过https://
调用 API。 - 在摘要页面上,确保已选择测试部署环境,然后点击创建和部署。
- 您会看到一条确认消息,告知您新 API 代理和 API 产品已成功创建,并且 API 代理已部署到测试环境。
- 点击修改代理以显示 API 代理的概览页面。
查看政策
- 在 API 代理编辑器中,点击开发标签页。您会看到 API 代理的请求流中添加了以下两项政策:
- 验证 API 密钥:检查 API 调用,确保存在有效的 API 密钥(作为查询参数发送)。
- Remove Query Param apikey:这项 AllocationMessage 政策用于移除 API 密钥,该政策在检查后会移除 API 密钥,以免其传递和不必要地公开。
-
点击流程视图中的“验证 API 密钥政策”图标,然后在下方代码视图中查看政策的 XML 配置。
<APIKey>
元素用于告知政策,在进行 API 调用时,该元素应该在哪里查找 API 密钥。默认情况下,它会在 HTTP 请求中以查询参数的形式查找该键(名为apikey
):<APIKey ref="request.queryparam.apikey" />
apikey
是任意名称,可以是包含 API 密钥的任何属性。
尝试调用 API
在此步骤中,您将直接成功地对目标服务进行 API 调用,然后对 API 代理进行一次失败的调用,看看政策如何保护该代理。
-
成功
在网络浏览器中,前往以下地址。 这是 API 代理配置为将请求转发到的目标服务,但您目前您可以直接访问该服务:
http://mocktarget.apigee.net
您应该成功收到以下响应:
Hello, Guest!
-
失败
现在尝试调用您的 API 代理:
http://ORG_NAME-test.apigee.net/helloapikey
将
ORG_NAME
替换为您的 Edge 组织的名称。如果没有“验证 API 密钥”政策,此调用将为您提供与上一次调用相同的响应。但在这种情况下,您应该会收到以下错误响应:
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}
这意味着您未传递有效的 API 密钥(作为查询参数)。
在接下来的步骤中,您将添加 API 产品。
添加 API 产品
如需使用 Apigee 界面添加 API 产品,请执行以下操作:
- 选择发布 > API 产品 (API Products)。
- 点击 +API 产品。
为您的 API 产品输入产品详情。
字段 说明 名称 API 产品的内部名称。请勿在名称中指定特殊字符。
注意:API 产品创建后,便无法修改名称。例如helloworld_apikey-Product
。显示名称 API 产品的显示名。显示名称会用在界面中,您可以随时修改。如果未指定,将使用“名称”值。此字段会使用“名称”值自动填充;您可以修改或删除其内容。显示名称可以包含特殊字符。例如 helloworld_apikey-Product
。说明 API 产品的说明。例如 Test product for tutorial
。环境 API 产品允许访问的环境。 例如, test
或prod
。有访问权限的应用 选择公开。 自动批准访问请求 启用自动批准来自任何应用对此 API 产品的密钥请求的功能。 配额 在本教程中忽略。 允许的 OAuth 范围 在本教程中忽略。 - 在 API 资源部分,选择您刚刚创建的 API 代理。例如
helloworld_apikey
。 - 点击添加。
- 在路径部分中,添加路径“/”。
- 点击添加。
- 点击保存。
在接下来的步骤中,您将获得所需的 API 密钥。
为您的组织添加开发者和应用
接下来,我们将模拟开发者注册使用您的 API 的工作流程。开发者会有一个或多个应用调用您的 API,而每个应用都会获得一个唯一的 API 密钥。这样一来,作为 API 提供方,您不仅可以更精细地控制对 API 的访问权限,还可以按应用更细致地报告 API 流量。
创建一个开发者
如需创建开发者,请执行以下操作:
- 在菜单中选择 Publish > Developers。
- 点击 + 开发者。
在“New Developer”(新开发者)窗口中输入以下内容:
在此字段中 进入 First Name(名字) Keyser
姓氏 Soze
用户名 keyser
电子邮件 keyser@example.com
- 点击创建。
注册一个应用
如需注册开发者应用,请执行以下操作:
- 选择发布 > 应用。
- 点击 + 应用。
在 New App 窗口中输入以下内容:
页在此字段中 执行该操作 名称和显示名 输入: keyser_app
公司/开发者 选择: Developer
开发者 选择: Keyser Soze (keyser@example.com)
回调网址和备注 留空 - 在凭据部分中,从过期菜单中选择永不。此应用的凭据永不会过期。
- 在产品下,点击添加产品。
- 选择 helloworld_apikey-Product。
- 点击添加。
- 点击应用详情部分上方和右侧的创建,保存您的工作。
获取 API 密钥
如需获取 API 密钥,请执行以下操作:
- 在应用页面(发布 > 应用)上,点击 keyser_app。
在 keyser_app 页面上,点击凭据部分中密钥旁边的显示。在产品部分中,请注意该键与 checkout_apikey 相关联
- 选择并复制 Key。您将在下一步中用到它。
使用密钥调用 API
您拥有 API 密钥后,就可以使用它来调用 API 代理了。在网络浏览器中输入以下内容。将 ORG_NAME 替换为 Edge 组织名称,并将下面的 API_KEY 替换为 API 密钥。 确保查询参数中没有多余的空格。
http://ORG_NAME-test.apigee.net/helloapikey?apikey=API_KEY
现在,当您调用 API 代理时,应该会得到以下响应:Hello, Guest!
恭喜!您已创建 API 代理,并通过要求在调用中包含有效的 API 密钥来保护该代理。
请注意,一般来说,最好不要将 API 密钥作为查询参数传递。您应考虑 改为在 HTTP 标头中传递该网址。
最佳实践:在 HTTP 标头中传递密钥
在此步骤中,您将修改代理,以在名为 x-apikey
的标头中查找 API 密钥。
- 修改 API 代理。依次选择 Develop > API Proxies > checkout_apikey,然后转到 Develop 视图。
-
选择验证 API 密钥政策,并修改政策 XML 以指示该政策在
header
(而不是queryparam
)中查找:<APIKey ref="request.header.x-apikey"/>
- 保存 API 代理以部署更改。
-
使用 c网址 进行以下 API 调用,将 API 密钥作为名为
x-apikey
的标头传递。请记得替换成您的组织名称。curl -v -H "x-apikey: API_KEY" http://ORG_NAME-test.apigee.net/helloapikey
请注意,要完全完成更改,您还需要配置 AllocationMessage 政策,以移除标头而不是查询参数。例如:
<Remove> <Headers> <Header name="x-apikey"/> </Headers> </Remove>
相关主题
以下是一些与本教程直接相关的主题:
深入探讨,使用 API 密钥保护 API 只是整个过程的一部分。通常,API 保护涉及额外的安全措施,例如 OAuth。
OAuth 是一种开放协议,简而言之,OAuth 是一种用凭据(如用户名和密码)交换访问令牌。访问令牌是一长串的随机字符串,可在消息流水线中传递,甚至可以在各应用之间传递,而不会损害原始凭据。访问令牌的生命周期通常很短,因此总是会生成新的访问令牌。