通过要求 API 密钥保护 API

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

注意：此视频是使用旧版 Apigee 界面录制的，但其中的概念仍然有效。

视频：观看此视频短片，了解如何保护 API。

学习内容

本教程介绍如何：

• 创建需要 API 密钥的 API 代理。
• 创建 API 产品、开发者和开发者应用。
• 使用 API 密钥调用 API。

请务必保护您的 API 免遭未经授权的访问。一种方法是使用 API 密钥。

当应用向配置为验证 API 密钥的 API 代理发出请求时，应用必须提供有效的密钥。在运行时，“验证 API 密钥”政策会检查提供的 API 密钥：

• 有效
• 尚未撤消
• 匹配公开所请求资源的 API 产品的 API 密钥

如果密钥有效，则允许请求。如果密钥无效，则请求会导致授权失败。

注意：为了完成本教程，您将创建并部署一个使用 可扩展政策而非标准政策的代理。

创建 API 代理

Cloud 控制台中的 Apigee

1. 在 Google Cloud 控制台中，前往代理开发 > API 代理页面。

   前往 API 代理

2. 在 Google Cloud 窗格的项目选择器中选择您的组织。组织名称与您的 Google Cloud 项目名称相同。
3. 点击 + 创建。
4. 在创建代理窗格的代理模板下，选择反向代理（最常见）。反向代理会将传入流量路由到后端服务。
5. 按如下方式配置代理：
   

   名称	值
   代理名称	helloworld_apikey
   基本路径	/helloapikey 项目基本路径是用于向 API 代理发出请求的网址的一部分。
   说明	hello world protected by API key
   目标（现有 API）	http://mocktarget.apigee.net 这定义了 Apigee 在对 API 代理的请求上调用的目标网址。 此目标只返回一个简单的响应：Hello, Guest!。

6. 点击下一步。
7. 部署（可选）。将这些字段留空。
8. 点击创建。
9. Apigee 会创建新代理，并在代理摘要窗格中显示代理详情摘要。

经典版界面

1. 转到 Apigee 界面并登录。
2. 使用界面左上角的下拉菜单选择您的组织。

3. 点击开发 > API 代理以显示 API 代理列表。

4. 点击新建。
   
5. 在“构建代理”向导中，选择反向代理（最常见） (Reverse proxy (most common))。
6. 按如下方式配置代理：
   

   在此字段中	执行该操作
   代理名称	输入：helloworld_apikey
   项目基本路径	更改为：/helloapikey 项目基本路径是用于向 API 代理发出请求的网址的一部分。
   说明	输入：hello world protected by API key
   目标（现有 API）	输入：http://mocktarget.apigee.net 这定义了 Apigee 在对 API 代理的请求上调用的目标网址。 此目标只返回一个简单的响应：Hello, Guest!。

7. 点击下一步。
8. 在通用政策 (Common policies) 页面上，选择 API 密钥。此选项会自动向您的 API 代理添加两个政策，并创建生成 API 密钥所需的 API 产品。
9. 点击下一步。
10. 在摘要页面上，确保已选择部署环境，然后点击创建并部署。
11. 点击修改代理 (Edit proxy)，以显示 API 代理的概览页面。

查看政策

Cloud 控制台中的 Apigee

1. 在 helloworld_apikey 代理的代理摘要窗格中，点击开发标签页。
2. 在政策菜单中，点击 添加政策。
3. 在创建政策窗格中，选择安全性下的验证 API 密钥。
4. 在 Verify API Key 窗格中，使用以下值填写名称和显示名称部分中的必填字段：
   • 名称：输入政策名称。例如 VerifyAPIKey。
   • 显示名称：输入要在界面中使用的政策名称。例如 Verify API Key。
5. 点击创建。
6. 点击 可添加其他政策。
7. 在创建政策窗格中，选择中介下的分配消息。
8. 在分配消息窗格中，使用以下值填充名称和显示名称部分中的必填字段：
   • 名称：输入政策名称。例如 AssignMessage。
   • 显示名称：输入要在界面中使用的政策名称。例如 Assign Message。
9. 点击创建。
10. 以下 XML 代码中的 <APIKey> 元素用于指定传入请求中 API 密钥的位置。 默认情况下，该政策会从 HTTP 请求中名为 apikey 的查询参数中检索密钥。

    <APIKey ref="request.queryparam.apikey" />

    名称 apikey 是任意名称，可以是包含 API 密钥的任何属性。

11. 将分配消息政策的内容更新为以下内容：
    注意：进行此修改后，政策名称将更改为 Remove Query Param apikey。

<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>

12. 添加 VerifyApiKey 和 Remove Query Param apikey 政策。
    1. 在代理端点菜单中，点击 Preflow。
    2. 在可视化编辑器的请求窗格中，点击 添加政策步骤。
    3. 在添加政策步骤窗格中，选择 Verify API Key。
    4. 点击添加。
    5. 在可视化编辑器的请求窗格中，点击 添加政策步骤。
    6. 在添加政策步骤窗格中，选择 Remove Query Param apikey。
    7. 点击添加。
13. 点击保存。
14. 将代理部署到环境：
    1. 点击部署。
    2. 选择修订版本和环境。
    3. 点击部署。
15. 按照 尝试调用 API 中的说明调用 API，以测试您的更改。

经典版界面

1. 在 API 代理编辑器中，点击开发标签页。您将看到 API 代理的请求流程中添加了两个政策：
   • 验证 API 密钥 - 检查 API 调用，以确保存在有效的 API 密钥（作为查询参数发送）。
   • 删除查询参数 apikey - 一项分配消息政策，选中后会移除 API 密钥，以防不必要地传递和公开该 API 密钥。

2. 点击流视图中的验证 API 密钥政策图标，然后在下部的代码视图中查看政策的 XML 配置。<APIKey> 元素会告知政策应在调用时从何处查找 API 密钥。默认情况下，它会在 HTTP 请求中查找作为名为 apikey 的查询参数的密钥：

   <APIKey ref="request.queryparam.apikey" />

   名称 apikey 是任意名称，可以是包含 API 密钥的任何属性。

尝试调用 API

在此步骤中，您将对目标服务直接进行成功的 API 调用，然后对 API 代理进行失败调用，以了解它如何受政策保护。

1. 成功

   在网络浏览器中，转到以下地址。这是将 API 代理配置为将请求转发到的目标服务，但您现在将直接命中它：

   http://mocktarget.apigee.net

   您应该成功收到以下响应：Hello, Guest!

2. 失败

   现在尝试调用您的 API 代理：

   curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey

   其中，YOUR ENV_GROUP_HOSTNAME 是环境组主机名。请参阅查找环境组主机名。

   注意：如果您在调用代理时遇到问题，则可能需要添加 Host 标头，如部署示例代理中所述。

   如果没有验证 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 产品，请执行以下操作：

1. 在 Google Cloud 控制台中，前往分发 > API 产品页面：

   前往 API 产品

2. 点击 +创建。
3. 输入 API 产品的产品详情。
   

   字段	说明
   名称	API 产品的内部名称。请勿在名称中指定特殊字符。 注意：API 产品一经创建，便无法再修改其名称。
   显示名称	API 产品的显示名称。显示名用于界面中，您可以随时进行修改。如果未指定，则使用 Name 值。此字段会使用 Name 值自动填充；您可以修改或删除其内容。显示名可以包含特殊字符。
   说明	API 产品的说明。
   环境	API 产品将允许访问的环境。例如，test 或 prod。
   访问	选择公开。
   自动批准访问请求	从任何应用启用此 API 产品的密钥请求的自动批准。
   配额	在本教程中忽略。
   允许的 OAuth 范围	在本教程中忽略。

4. 在操作部分中，点击添加操作。
5. 在 API 代理字段中，选择您刚刚创建的 API 代理。
6. 在路径字段中，输入“/”。忽略其他字段。
7. 点击保存以保存该操作。
8. 点击保存以保存该 API 产品。

如需详细了解如何添加 API 产品，请参阅 创建 API 产品。

经典版界面

如需使用 Apigee 界面添加 API 产品，请执行以下操作：

1. 选择发布 > API 产品。
2. 点击+创建。
3. 输入 API 产品的产品详细信息。
   

   字段	说明
   名称	API 产品的内部名称。请勿在名称中指定特殊字符。 注意：API 产品一经创建，便无法再修改其名称。
   显示名称	API 产品的显示名称。显示名用于界面中，您可以随时进行修改。如果未指定，则系统会使用 Name 值。此字段会使用 Name 值自动填充；您可以修改或删除其内容。显示名可以包含特殊字符。
   说明	API 产品的说明。
   环境	API 产品将允许访问的环境。例如 test 或 prod。
   访问	选择公开。
   自动批准访问请求	从任何应用启用此 API 产品的密钥请求的自动批准。
   配额	在本教程中忽略。
   允许的 OAuth 范围	在本教程中忽略。

4. 在操作 (Operations) 部分中，点击添加操作 (ADD AN OPERATION)。
5. 在“API 代理”字段中，选择您刚刚创建的 API 代理。
6. 在“路径”字段中，输入“/”。忽略其他字段。
7. 点击保存以保存该操作。
8. 点击保存以保存该 API 产品。

将开发者和应用添加到您的组织

接下来，我们将模拟开发者注册使用 API 的工作流。开发者将有一个或多个应用调用您的 API，并且每个应用都会获得唯一的 API 密钥。这样，API 提供方就可以更精细地控制对 API 的访问，并更精细地按应用报告 API 流量。

创建一个开发者

Cloud 控制台中的 Apigee

如需创建开发者，请执行以下操作：

1. 在 Google Cloud 控制台中，前往分发 > 开发者页面：

   前往开发者

2. 点击 + 创建。
3. 在添加开发者窗口中输入以下内容：
   

   字段	值
   名字	Keyser
   姓氏	Soze
   电子邮件	[e-mail]
   用户名	keyser

4. 点击添加。

如需详细了解如何创建开发者，请参阅 注册应用开发者。

经典版界面

如需创建开发者，请执行以下操作：

1. 在菜单中选择 Publish > Developers。
   注意：如果您仍在“开发”屏幕中，请点击 DEVELOP 旁边的 "<"，以显示菜单，然后依次选择发布 > 开发者
2. 点击 + 开发者。
3. 在“新开发者”窗口中输入以下内容：
   

   在此字段中	Enter
   名字	Keyser
   姓氏	Soze
   用户名	keyser
   电子邮件	[e-mail]

4. 点击创建。

注册一个应用

Cloud 控制台中的 Apigee

1. 在 Google Cloud 控制台中，前往分发 > 应用页面：

   前往“应用”

2. 点击 + 创建。
3. 在创建应用窗口中输入以下内容：
   

   字段	值
   应用名称	输入：keyser_app
   显示名称	输入：keyser_app
   开发者	选择：Keyser Soze ([e-mail])
   回调网址	留空
   备注	留空

4. 在“凭证”部分中，点击添加凭证。
5. 选择从不。此应用的凭据永不会过期。
6. 点击添加商品。
7. 选择您刚创建的产品。
8. 点击添加。
9. 点击创建。

如需详细了解如何注册应用，请参阅 注册应用。

经典版界面

如需注册开发者应用，请执行以下操作：

1. 选择发布 > 应用。
2. 点击 + 应用。
3. 在“新开发者应用”窗口中输入以下内容：
   

   字段	值
   名称和显示名	输入：keyser_app
   开发者	选择：Keyser Soze ([e-mail])
   回调网址和备注	留空

4. 在“凭据”部分，选择永不。此应用的凭据永不会过期。
5. 点击添加产品。
6. 选择您刚创建的产品。
7. 点击创建。

获取 API 密钥

Cloud 控制台中的 Apigee

如需获取 API 密钥，请执行以下操作：

1. 在 Google Cloud 控制台中，前往分发 > 应用页面。

   前往应用

2. 从应用列表中选择所需的应用。
3. 在查看应用页面上，点击凭据下密钥字段旁边的 。请注意，此密钥与您创建的产品相关联。
4. 点击 复制。 您将在下一步中使用此密钥。

经典版界面

如需获取 API 密钥，请执行以下操作：

1. 在“应用”页面（发布 > 应用）上，点击 keyser_app。
2. 在 keyser_app 页面上，点击凭据部分中密钥旁边的显示。请注意，此密钥与您创建的产品相关联。
   
3. 选择并复制密钥。您将在下一步中用到它。

使用密钥调用 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 标头中传递密钥

注意：建议您在标头（而非查询参数）中传递 API 密钥。查询参数会显示在浏览器历史记录和网络日志中，这可能会带来安全风险。标头不会显示在浏览器历史记录和网络日志中。

在这一步中，您将修改代理，以在名为 x-apikey 的标头中查找 API 密钥。

Cloud 控制台中的 Apigee

1. 在 Google Cloud 控制台中，前往代理开发 > API 代理页面。

前往 API 代理

2. 从代理列表中选择所需的代理。
3. 在代理详情页面上，点击开发。
4. 修改政策 XML，以指示政策在标头中查找，而不是在 queryparam 中查找：

<APIKey ref="request.header.x-apikey"/>

5. 点击保存以保存所做更改。
6. 点击部署。
7. 选择修订版本和环境。
8. 点击部署。

9. 使用 c网址 发出以下 API 调用，以将 API 密钥作为名为 x-apikey 的标头传递。别忘了替换您的组织名称。

   curl -v -H "x-apikey: YOUR_API_KEY" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey

请注意，如需完全完成更改，您还需要配置“分配消息”政策以移除标头，而不是查询参数。例如：

<Remove>
  <Headers>
      <Header name="x-apikey"/>
  </Headers>
</Remove>

注意：您还可以将 API 密钥作为表单参数传递。如果已配置，则验证 API 密钥政策将配置如下：

<APIKey ref="request.formparam.YOUR_API_KEY"/>

经典版界面

1. 修改 API 代理。依次选择开发 > API 代理 > helloworld_apikey，然后转到开发视图。

2. 选择验证 API 密钥政策，然后修改政策 XML 以指示政策在 header 而不是 queryparam 中查找：

   <APIKey ref="request.header.x-apikey"/>

3. 保存 API 代理，然后使用部署进行部署。

4. 使用 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>

注意：您还可以将 API 密钥作为表单参数传递。如果已配置，则验证 API 密钥政策将配置如下：

<APIKey ref="request.formparam.YOUR_API_KEY"/>

相关主题

以下是一些与 API 产品和密钥相关的主题：

• 管理 API 产品
• API 密钥
• 注册应用开发者
• 注册应用和管理 API 密钥
• 验证 API 密钥政策

API 保护通常涉及其他安全机制，例如 OAuth，这是一种将凭据（如用户名和密码）换成访问令牌的开放协议。访问令牌是长的随机字符串，可通过消息流水线在例如应用之间传递，而且不会泄露原始凭据。

如需简要了解安全相关主题，请参阅保护代理。