通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure API 管理中的订阅

适用于：所有 API 管理层级

在 Azure API 管理中，订阅是 API 使用者访问通过 API 管理实例发布的 API 时最常用的方式。 本文概述了此概念。

注意

API 管理订阅专门用于使用订阅密钥通过 API 管理调用 API。 它与 Azure 订阅不同。

什么是订阅？

通过 API 管理发布 API，可以使用订阅密钥轻松保护 API 访问。 需要使用已发布的 API 的开发人员在调用那些 API 时必须在 HTTP 请求中包括有效的订阅密钥。 如果没有有效的订阅密钥，这些调用：

  • 会立即被 API 管理网关拒绝。
  • 不会被转发到后端服务。

若要访问 API，开发者需要订阅和订阅密钥。 订阅是一个命名容器，对应于一对订阅密钥。

此外，

  • 开发者无需 API 发布者批准即可获取订阅。
  • API 发布者可以直接为 API 使用者创建订阅。

提示

API 管理还支持使用其他机制来保护对 API 的访问，包括以下示例：

管理订阅密钥

定期重新生成密钥是常见的安全预防措施。 与大多数需要订阅密钥的 Azure 服务一样，API 管理会生成成对的密钥。 使用服务的每个应用程序都可以从 密钥 A 切换到 密钥 B ，同时以最少的中断重新生成密钥 A；反之亦然。

可以通过调用 Azure API 管理订阅 - 创建或更新 Azure REST API 来设置特定密钥，而不是重新生成密钥。 具体而言，在 HTTP 请求正文中设置 properties.primaryKey 和/或 properties.secondaryKey 。

注意

  • API 管理不提供内置功能来管理订阅密钥的生命周期，例如设置过期日期或自动轮换密钥。 可以使用 Azure PowerShell 或 Azure SDK 等工具开发工作流来自动执行这些过程。
  • 若要强制对 API 进行限时访问，API 发布者可能能够将策略与订阅密钥一起使用，或者使用提供内置过期机制（例如基于令牌的身份验证）。

订阅范围

可以将订阅与各种范围相关联： 产品、所有 API 或单个 API。

产品的订阅

传统上，将 API 管理中的订阅与单个 产品 范围相关联。 开发 人员：

  • 在开发人员门户中查找产品列表。
  • 提交其要使用的产品的订阅请求。
  • 使用自动或 API 发布者批准的订阅中的密钥访问产品中的 API。

目前，开发人员门户只在“用户配置文件”部分显示产品范围订阅。

显示产品范围订阅的传统流的关系图。开发人员提交产品的订阅请求，并接收用于访问它的密钥。

订阅所有 API 或单个 API

你还可以创建密钥，以授予对以下任一项的访问权限：

  • 某一个 API，或
  • API 管理实例中的所有 API。

在这些情况下，无需先创建产品并为它添加 API。

全访问权限订阅

每个 API 管理实例都附带了一个内置全访问订阅，该订阅授予对所有 API 的访问权限。 使用此限定服务范围的订阅，服务所有者可以直接在测试控制台中测试和调试 API。

警告

所有访问订阅允许访问 API 管理实例中的每个 API。 只有经过授权的用户才应使用此订阅。 请勿将此订阅用于例程 API 访问或在客户端应用中嵌入“所有访问权限”订阅密钥。

注意

如果使用 API 范围的订阅、所有 API 订阅或内置全访问订阅，则产品范围内配置的策略不会应用于来自该订阅的请求。

独立订阅

API 管理还允许未与某个开发人员帐户关联的独立订阅。 此功能适用于多个开发人员或共享订阅的团队等方案。

在不分配所有者的情况下创建订阅会将其创建为独立订阅。 若要向开发人员和团队的其余人员授予对独立订阅密钥的访问权限，请执行以下任一操作：

  • 手动共享订阅密钥。
  • 使用自定义系统使订阅密钥可供团队使用。

注意

不能将 API 管理中的订阅直接分配给 Microsoft Entra ID 安全组。 若要向组中的多个用户提供订阅访问权限，请创建独立订阅并将订阅密钥分发给组成员，或与 Microsoft Entra ID 集成，以便进行身份验证，并使用策略基于组成员身份控制 API 访问。

在 Azure 门户中创建和管理订阅

API 发布者（具有适当权限的管理员或开发人员）可以通过登录到其 API 管理实例直接在 Azure 门户中 创建订阅 。 API 使用者无法通过 Azure 门户创建订阅;他们通常通过开发人员门户请求订阅，或者从 API 发布者那里接收订阅。

在门户中创建订阅时，它处于 活动 状态，这意味着订阅者可以使用有效的订阅密钥调用关联的 API。 可以根据需要更改订阅的状态。 例如，可以暂停、取消或删除任何订阅（包括内置的全访问权限订阅），以阻止 API 访问。

使用订阅密钥

订阅者可以通过两种方式使用 API 管理订阅密钥：

  • 将 Ocp-Apim-Subscription-Key HTTP 标头添加到请求，并传递有效订阅密钥的值。
  • 在 URL 中包含 subscription-key 查询参数和有效值。 仅当标头不存在时，才会检查该查询参数。

提示

Ocp-Apim-Subscription-Key 是订阅密钥标头的默认名称，subscription-key 是查询参数的默认名称。 如果需要，可以在每个 API 的设置中修改这些名称。 例如，在门户中，在 API 的“设置”选项卡上更新这些名称。

注意

请求标头或查询参数中包括时，订阅密钥默认传递到后端，并可能在后端监视日志或其他系统中公开。 如果此数据很敏感，可以在节末尾 inbound 配置策略，以删除订阅密钥标头（set-header）或查询参数（set-query-parameter）。

启用或禁用 API 或产品访问的订阅要求

默认情况下，创建 API 时，需要订阅密钥才可进行 API 访问。 同样，创建产品时，默认情况下需要订阅密钥才能访问添加到产品的任何 API。 在特定情形下，API 发布者可能会希望以不要求订阅的方式向公众发布产品或特定的 API。 虽然发布者可能会选择启用对某些 API 的无安全保护（匿名）的访问，但我们还是建议配置另一种机制来保护客户端访问。

警告

配置不需要订阅的产品或 API 时，请小心。 此配置可能过于宽松，并且可能会使 API 更容易受到某些 API 安全威胁的影响。

注意

打开的产品已禁用 “需要订阅 ”设置，这意味着用户无需订阅。 因此，打开的产品不会显示在开发人员门户 的“产品 ”页上。

创建 API 或产品或更高版本时，可以禁用订阅要求。

若要使用门户禁用订阅要求，请执行以下操作：

  • 禁用产品要求 - 在产品的 “设置” 页上，禁用 “需要订阅”。
  • API 的禁用要求 - 在 API 的“设置”页上禁用“需要订阅”。

在禁用订阅要求后，可在没有订阅密钥的情况下访问所选的一个或多个 API。

API 管理在有或没有订阅密钥的情况下如何处理请求

带有订阅密钥的 API 请求

在 API 管理收到来自客户端的带有订阅密钥的 API 请求时，它会根据以下规则来处理该请求：

  1. 它会检查密钥是否有效并与 活动订阅相关联，定义为：

    • 一个范围限定为该 API 的订阅。
    • 一个范围限定为分配给该 API 的产品的订阅。
    • 适用于所有 API 的订阅。
    • 服务范围的订阅（内置的所有访问订阅）。

    如果密钥在适当的范围内对活动订阅有效，API 管理会授予访问权限。 它根据指定范围内的策略定义配置来应用策略。

  2. 如果密钥无效，但存在包含 API 且不需要订阅（ 开放 产品）的产品，API 管理将忽略密钥，并将请求作为没有订阅密钥的 API 请求进行处理（请参阅以下部分）。

  3. 否则，API 管理将拒绝访问（401 访问被拒绝错误）。

没有订阅密钥的 API 请求

在 API 管理收到没有订阅密钥的来自客户端的 API 请求时，它会根据以下规则来处理该请求：

  1. 它检查包含 API 但不需要订阅（ 开放 产品）的产品是否存在。 如果打开的产品存在，API 管理在为打开的产品配置的 API、策略和访问规则的上下文中处理请求。 一个 API 最多可与一个开放产品相关联。
  2. 如果未找到包括 API 在内的开放产品，API 管理将检查 API 是否需要订阅。 如果不需要订阅，API 管理将在该 API 和操作的上下文中处理请求。
  3. 如果未找到配置的产品或 API，则 API 管理将拒绝访问（401 访问被拒绝错误）。

摘要表

下表总结了在不同方案中，网关如何处理带有或没有订阅密钥的 API 请求。 表会记录可能启用意外的匿名 API 访问的配置。

分配给 API 的所有产品都需要订阅 API 需要订阅 带有订阅密钥的 API 调用 没有订阅密钥的 API 调用 典型方案
✔️ ✔️ 允许访问：

• 产品范围的密钥
• API 范围的密钥
• 所有 API 范围的密钥
• 服务范围的密钥

访问被拒绝：

• 范围未限定为适用的产品或 API 的其他密钥		 访问被拒绝 使用产品范围或 API 范围的订阅保护的 API 访问
✔️ ❌ 允许访问：

• 产品范围的密钥
• API 范围的密钥
• 所有 API 范围的密钥
• 服务范围的密钥
• 范围未限定为适用的产品或 API 的其他密钥		 允许访问（API 上下文） • 使用产品范围的订阅进行的受保护 API 访问

• 匿名访问 API。 如果不应进行匿名访问，请配置 API 级策略以强制实施身份验证和授权。
❌ 1 ✔️ 允许访问：

• 产品范围的密钥
• API 范围的密钥
• 所有 API 范围的密钥
• 服务范围的密钥

访问被拒绝：

• 范围未限定为适用的产品或 API 的其他密钥		 允许访问（开放产品上下文） • 使用 API 范围的订阅进行的受保护 API 访问

• 匿名访问 API。 如果不应进行匿名访问，请使用产品策略进行配置以强制进行身份验证和授权
❌ 1 ❌ 允许访问：

• 产品范围的密钥
• API 范围的密钥
• 所有 API 范围的密钥
• 服务范围的密钥
• 范围未限定为适用的产品或 API 的其他密钥		 允许访问（开放产品上下文） 匿名访问 API。 如果不应进行匿名访问，请使用产品策略进行配置以强制进行身份验证和授权

1 有一个开放产品与 API 相关联。

注意事项

  • 无论产品是否已发布，产品上下文中的 API 访问都是相同的。 取消发布产品会将其从开发人员门户隐藏，但不会使新的或现有的订阅密钥失效。
  • 如果 API 不需要订阅身份验证，则包含订阅密钥的任何 API 请求都被视为与没有订阅密钥的请求相同。 订阅密钥会被忽略。
  • API 访问“上下文”是指在特定范围内（例如 API 或产品）应用的策略和访问控制。

相关内容

获取有关 API 管理的详细信息：

  • 了解 API 管理策略在不同的范围是如何应用的。
  • 了解 API 管理中的其他概念。
  • 按教程操作，详细了解 API 管理。
  • 查看常见问题解答页，了解常见问题。
  • Last updated on