本页面适用于 Apigee 和 Apigee Hybrid。
查看 Apigee Edge 文档。
视频:观看此视频短片,了解如何保护 API。
学习内容
本教程介绍如何:
- 创建需要 API 密钥的 API 代理。
- 创建 API 产品、开发者和开发者应用。
- 使用 API 密钥调用 API。
请务必保护您的 API 免遭未经授权的访问。一种方法是使用 API 密钥。
当应用向配置为验证 API 密钥的 API 代理发出请求时,应用必须提供有效的密钥。在运行时,“验证 API 密钥”政策会检查提供的 API 密钥:
- 有效
- 尚未撤消
- 匹配公开所请求资源的 API 产品的 API 密钥
如果密钥有效,则允许请求。如果密钥无效,则请求会导致授权失败。
创建 API 代理
Cloud 控制台中的 Apigee
在 Google Cloud 控制台中,前往代理开发 > API 代理页面。
- 在 Google Cloud 窗格的项目选择器中选择您的组织。组织名称与您的 Google Cloud 项目名称相同。
- 点击 + 创建。
- 在创建代理窗格的代理模板下,选择反向代理(最常见)。反向代理会将传入流量路由到后端服务。
- 按如下方式配置代理:
名称 值 代理名称 helloworld_apikey
基本路径 /helloapikey
项目基本路径是用于向 API 代理发出请求的网址的一部分。
说明 hello world protected by API key
目标(现有 API) http://mocktarget.apigee.net
这定义了 Apigee 在对 API 代理的请求上调用的目标网址。 此目标只返回一个简单的响应:
Hello, Guest!
。 - 点击下一步。
- 部署(可选)。将这些字段留空。
- 点击创建。
- Apigee 会创建新代理,并在代理摘要窗格中显示代理详情摘要。
经典版界面
- 转到 Apigee 界面并登录。
- 使用界面左上角的下拉菜单选择您的组织。
-
点击开发 > API 代理以显示 API 代理列表。
- 点击新建。
- 在“构建代理”向导中,选择反向代理(最常见) (Reverse proxy (most common))。
- 按如下方式配置代理:
在此字段中 执行该操作 代理名称 输入: helloworld_apikey
项目基本路径 更改为:
/helloapikey
项目基本路径是用于向 API 代理发出请求的网址的一部分。
说明 输入: hello world protected by API key
目标(现有 API) 输入:
http://mocktarget.apigee.net
这定义了 Apigee 在对 API 代理的请求上调用的目标网址。 此目标只返回一个简单的响应:
Hello, Guest!
。 - 点击下一步。
- 在通用政策 (Common policies) 页面上,选择 API 密钥。此选项会自动向您的 API 代理添加两个政策,并创建生成 API 密钥所需的 API 产品。
- 点击下一步。
- 在摘要页面上,确保已选择部署环境,然后点击创建并部署。
- 点击修改代理 (Edit proxy),以显示 API 代理的概览页面。
查看政策
Cloud 控制台中的 Apigee
- 在 helloworld_apikey 代理的代理摘要窗格中,点击开发标签页。
- 在政策菜单中,点击 添加政策。
- 在创建政策窗格中,选择安全性下的验证 API 密钥。
- 在 Verify API Key 窗格中,使用以下值填写名称和显示名称部分中的必填字段:
- 名称:输入政策名称。例如
VerifyAPIKey
。 - 显示名称:输入要在界面中使用的政策名称。例如
Verify API Key
。
- 名称:输入政策名称。例如
- 点击创建。
- 点击 可添加其他政策。
- 在创建政策窗格中,选择中介下的分配消息。
- 在分配消息窗格中,使用以下值填充名称和显示名称部分中的必填字段:
- 名称:输入政策名称。例如
AssignMessage
。 - 显示名称:输入要在界面中使用的政策名称。例如
Assign Message
。
- 名称:输入政策名称。例如
- 点击创建。
- 以下 XML 代码中的
<APIKey>
元素用于指定传入请求中 API 密钥的位置。 默认情况下,该政策会从 HTTP 请求中名为apikey
的查询参数中检索密钥。<APIKey ref="request.queryparam.apikey" />
名称
apikey
是任意名称,可以是包含 API 密钥的任何属性。 - 将分配消息政策的内容更新为以下内容:
- 添加
VerifyApiKey
和Remove Query Param apikey
政策。- 在代理端点菜单中,点击 Preflow。
- 在可视化编辑器的请求窗格中,点击 添加政策步骤。
- 在添加政策步骤窗格中,选择 Verify API Key。
- 点击添加。
- 在可视化编辑器的请求窗格中,点击 添加政策步骤。
- 在添加政策步骤窗格中,选择 Remove Query Param apikey。
- 点击添加。
- 点击保存。
- 将代理部署到环境:
- 点击部署。
- 选择修订版本和环境。
- 点击部署。
- 按照 尝试调用 API 中的说明调用 API,以测试您的更改。
<AssignMessage async="false" continueOnError="false" enabled="true" name="remove-query-param-apikey"> <DisplayName>Remove Query Param apikey</DisplayName> <Remove> <QueryParams> <QueryParam name="apikey"/> </QueryParams> </Remove> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
经典版界面
- 在 API 代理编辑器中,点击开发标签页。您将看到 API 代理的请求流程中添加了两个政策:
- 验证 API 密钥 - 检查 API 调用,以确保存在有效的 API 密钥(作为查询参数发送)。
- 删除查询参数 apikey - 一项分配消息政策,选中后会移除 API 密钥,以防不必要地传递和公开该 API 密钥。
-
点击流视图中的验证 API 密钥政策图标,然后在下部的代码视图中查看政策的 XML 配置。
<APIKey>
元素会告知政策应在调用时从何处查找 API 密钥。默认情况下,它会在 HTTP 请求中查找作为名为apikey
的查询参数的密钥:<APIKey ref="request.queryparam.apikey" />
名称
apikey
是任意名称,可以是包含 API 密钥的任何属性。
尝试调用 API
在此步骤中,您将对目标服务直接进行成功的 API 调用,然后对 API 代理进行失败调用,以了解它如何受政策保护。
-
成功
在网络浏览器中,转到以下地址。这是将 API 代理配置为将请求转发到的目标服务,但您现在将直接命中它:
http://mocktarget.apigee.net
您应该成功收到以下响应:
Hello, Guest!
-
失败
现在尝试调用您的 API 代理:
curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey
其中,
YOUR ENV_GROUP_HOSTNAME
是环境组主机名。请参阅查找环境组主机名。如果没有验证 API 密钥政策,则此调用将返回与前一调用相同的响应。但在这种情况下,您应该会收到以下错误响应:
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}
也就是说,您未正确传递有效的 API 密钥(作为查询参数)。
在接下来的步骤中,您将获得所需的 API 密钥。
添加 API 产品
Cloud 控制台中的 Apigee
如需使用 Apigee 界面添加 API 产品,请执行以下操作:
在 Google Cloud 控制台中,前往分发 > API 产品页面:
- 点击 +创建。
- 输入 API 产品的产品详情。
字段 说明 名称 API 产品的内部名称。请勿在名称中指定特殊字符。
注意:API 产品一经创建,便无法再修改其名称。显示名称 API 产品的显示名称。显示名用于界面中,您可以随时进行修改。如果未指定,则使用 Name 值。此字段会使用 Name 值自动填充;您可以修改或删除其内容。显示名可以包含特殊字符。 说明 API 产品的说明。 环境 API 产品将允许访问的环境。例如, test
或prod
。访问 选择公开。 自动批准访问请求 从任何应用启用此 API 产品的密钥请求的自动批准。 配额 在本教程中忽略。 允许的 OAuth 范围 在本教程中忽略。 - 在操作部分中,点击添加操作。
- 在 API 代理字段中,选择您刚刚创建的 API 代理。
- 在路径字段中,输入“/”。忽略其他字段。
- 点击保存以保存该操作。
- 点击保存以保存该 API 产品。
如需详细了解如何添加 API 产品,请参阅 创建 API 产品。
经典版界面
如需使用 Apigee 界面添加 API 产品,请执行以下操作:
- 选择发布 > API 产品。
- 点击+创建。
- 输入 API 产品的产品详细信息。
字段 说明 名称 API 产品的内部名称。请勿在名称中指定特殊字符。
注意:API 产品一经创建,便无法再修改其名称。显示名称 API 产品的显示名称。显示名用于界面中,您可以随时进行修改。如果未指定,则系统会使用 Name 值。此字段会使用 Name 值自动填充;您可以修改或删除其内容。显示名可以包含特殊字符。 说明 API 产品的说明。 环境 API 产品将允许访问的环境。例如 test
或prod
。访问 选择公开。 自动批准访问请求 从任何应用启用此 API 产品的密钥请求的自动批准。 配额 在本教程中忽略。 允许的 OAuth 范围 在本教程中忽略。 - 在操作 (Operations) 部分中,点击添加操作 (ADD AN OPERATION)。
- 在“API 代理”字段中,选择您刚刚创建的 API 代理。
- 在“路径”字段中,输入“/”。忽略其他字段。
- 点击保存以保存该操作。
- 点击保存以保存该 API 产品。
将开发者和应用添加到您的组织
接下来,我们将模拟开发者注册使用 API 的工作流。开发者将有一个或多个应用调用您的 API,并且每个应用都会获得唯一的 API 密钥。这样,API 提供方就可以更精细地控制对 API 的访问,并更精细地按应用报告 API 流量。
创建一个开发者
Cloud 控制台中的 Apigee
如需创建开发者,请执行以下操作:
-
在 Google Cloud 控制台中,前往分发 > 开发者页面:
- 点击 + 创建。
- 在添加开发者窗口中输入以下内容:
字段 值 名字 Keyser
姓氏 Soze
电子邮件 keyser@example.com
用户名 keyser
- 点击添加。
如需详细了解如何创建开发者,请参阅 注册应用开发者。
经典版界面
如需创建开发者,请执行以下操作:
- 在菜单中选择 Publish > Developers。
注意:如果您仍在“开发”屏幕中,请点击 DEVELOP 旁边的 "<",以显示菜单,然后依次选择发布 > 开发者 - 点击 + 开发者。
- 在“新开发者”窗口中输入以下内容:
在此字段中 Enter 名字 Keyser
姓氏 Soze
用户名 keyser
电子邮件 keyser@example.com
- 点击创建。
注册一个应用
Cloud 控制台中的 Apigee
-
在 Google Cloud 控制台中,前往分发 > 应用页面:
- 点击 + 创建。
- 在创建应用窗口中输入以下内容:
字段 值 应用名称 输入: keyser_app
显示名称 输入: keyser_app
开发者 选择: Keyser Soze (keyser@example.com)
回调网址 留空 备注 留空 - 在“凭证”部分中,点击添加凭证。
- 选择从不。此应用的凭据永不会过期。
- 点击添加商品。
- 选择您刚创建的产品。
- 点击添加。
- 点击创建。
如需详细了解如何注册应用,请参阅 注册应用。
经典版界面
如需注册开发者应用,请执行以下操作:
- 选择发布 > 应用。
- 点击 + 应用。
- 在“新开发者应用”窗口中输入以下内容:
字段 值 名称和显示名 输入: keyser_app
开发者 选择: Keyser Soze (keyser@example.com)
回调网址和备注 留空 - 在“凭据”部分,选择永不。此应用的凭据永不会过期。
- 点击添加产品。
- 选择您刚创建的产品。
- 点击创建。
获取 API 密钥
Cloud 控制台中的 Apigee
如需获取 API 密钥,请执行以下操作:
在 Google Cloud 控制台中,前往分发 > 应用页面。
- 从应用列表中选择所需的应用。
- 在查看应用页面上,点击凭据下密钥字段旁边的 。请注意,此密钥与您创建的产品相关联。
- 点击 复制。 您将在下一步中使用此密钥。
经典版界面
如需获取 API 密钥,请执行以下操作:
- 在“应用”页面(发布 > 应用)上,点击 keyser_app。
- 在 keyser_app 页面上,点击凭据部分中密钥旁边的显示。请注意,此密钥与您创建的产品相关联。
- 选择并复制密钥。您将在下一步中用到它。
使用密钥调用 API
您拥有 API 密钥后,就可以使用它来调用 API 代理了。按所示粘贴 API 密钥,将其作为查询参数。确保查询参数中不存在额外空格。
curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey?apikey=YOUR_API_KEY
现在,在调用 API 代理时,您应得到以下响应:Hello,
Guest!
恭喜!您创建了一个 API 代理,并要求在调用中包含有效的 API 密钥,以对其进行保护。
请注意,通常情况下,最好将 API 密钥作为查询参数传递。您应该考虑改为在 HTTP 标头中传递它。
最佳做法:在 HTTP 标头中传递密钥
在这一步中,您将修改代理,以在名为 x-apikey
的标头中查找 API 密钥。
Cloud 控制台中的 Apigee
- 在 Google Cloud 控制台中,前往代理开发 > API 代理页面。
- 从代理列表中选择所需的代理。
- 在代理详情页面上,点击开发。
- 修改政策 XML,以指示政策在标头中查找,而不是在 queryparam 中查找:
- 点击保存以保存所做更改。
- 点击部署。
- 选择修订版本和环境。
- 点击部署。
-
使用 c网址 发出以下 API 调用,以将 API 密钥作为名为
x-apikey
的标头传递。别忘了替换您的组织名称。curl -v -H "x-apikey: YOUR_API_KEY" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey
<APIKey ref="request.header.x-apikey"/>
请注意,如需完全完成更改,您还需要配置“分配消息”政策以移除标头,而不是查询参数。例如:
<Remove> <Headers> <Header name="x-apikey"/> </Headers> </Remove>
经典版界面
- 修改 API 代理。依次选择开发 > API 代理 > helloworld_apikey,然后转到开发视图。
-
选择验证 API 密钥政策,然后修改政策 XML 以指示政策在
header
而不是queryparam
中查找:<APIKey ref="request.header.x-apikey"/>
- 保存 API 代理,然后使用部署进行部署。
-
使用 cURL 发出以下 API 调用,以将 API 密钥作为名为
x-apikey
的标头传递。别忘了替换您的组织名称。curl -v -H "x-apikey: {api_key_goes_here}" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey
请注意,如需完全完成更改,您还需要配置“分配消息”政策以移除标头,而不是查询参数。例如:
<Remove> <Headers> <Header name="x-apikey"/> </Headers> </Remove>