将 Azure API 管理（APIM）与 Fabric API for GraphQL 集成

将 Azure API 管理（APIM）与 Microsoft Fabric 的 GraphQL API 集成，通过提供可靠的可伸缩性和安全功能来显著增强 API 的功能。 APIM 充当企业级网关，可添加高级功能，包括标识管理、速率限制、响应缓存、威胁防护和集中式监视，所有这些都无需修改 Fabric API 配置。

通过通过 APIM 路由 GraphQL 请求，可以进行缩放以处理增加的流量、实施复杂的安全策略，并深入了解整个组织的 API 使用模式。

本文指导你将 APIM 与 Fabric API for GraphQL 集成、配置托管标识身份验证以及实现缓存和速率限制策略。

谁将 Azure API 管理与 GraphQL 配合使用

APIM 集成的价值在于：

企业架构师 通过集中式受管理 API 网关公开 Fabric 数据，以实现组织范围的访问
Fabric 管理员正在实施速率限制、缓存和安全策略，以保护 Fabric 容量和数据。
IT 安全团队需要高级身份验证、授权和威胁防护来访问 Fabric 数据
平台团队管理和治理跨部门的多个 Fabric GraphQL API

如果需要企业级 API 管理功能（例如速率限制、缓存、安全策略和 Fabric GraphQL API 的集中式治理），请使用 APIM 集成。

先决条件

在开始之前，请确保具备：

已经创建了用于 GraphQL 的 Fabric API。如果没有，请参阅“为 GraphQL 创建 API”，或者在用于 GraphQL 的 API 门户中使用示例 SQL 数据库
一个 Azure API 管理实例。有关设置说明，请参阅创建 API 管理实例
创建托管标识和配置 APIM 策略的权限

将 Fabric GraphQL API 添加到 Azure API 管理

将 APIM 与 Fabric 集成的第一步是将 GraphQL API 导入 Azure API 管理。此过程创建一个代理，该代理通过 APIM 路由请求，同时维护与 Fabric 数据源的连接。通过导入 API，可以建立添加企业功能的基础，例如身份验证策略、缓存和速率限制。

导入过程需要 Fabric GraphQL API 中的两条信息：终结点 URL（其中 APIM 发送请求）和架构文件（用于定义 API 结构和可用作）。

导出 GraphQL API 详细信息

首先，从 Fabric GraphQL API 收集所需的信息：

在 Fabric 门户中打开 GraphQL API
在功能区中，选择 复制终结点 以获取 API 的 URL
选择 “导出架构 ”，将 GraphQL 架构文件下载到本地设备

将 API 导入 APIM

终结点 URL 和架构文件准备就绪后，现在可以在 APIM 中注册 GraphQL API。这会创建 APIM 用于验证请求、生成文档和应用策略的 API 定义。上传的架构定义客户端可以执行的查询和突变。

在 Azure 门户中导航到 API 管理实例
选择 API>+ 添加 API
选择 GraphQL 图标
在 “从 GraphQL 架构创建” 屏幕中，提供：
- 显示名称：API 的友好名称
- 名称：API 标识符
- GraphQL API 端点：从 Fabric 拷贝的端点 URL
选择 “上传架构 ”，然后选择下载的架构文件

配置托管身份身份验证

在 APIM 中注册 GraphQL API 后，需要配置 APIM 如何使用 Fabric 进行身份验证。托管标识提供安全的无密码身份验证方法，无需在 APIM 配置中存储凭据。 Azure 会自动管理标识生命周期并处理令牌获取，使此方法比传统身份验证方法更安全且更易于维护。

身份验证设置涉及三个主要步骤：在 Azure 中创建托管标识、授予访问 Fabric 工作区和数据源的权限，以及配置 APIM 以在向 Fabric 发出请求时使用此标识。

创建和分配托管标识

首先，创建 APIM 用来进行身份验证的托管标识：

在 Azure 门户中创建用户分配的托管标识。
请注意托管标识的 客户端 ID，以便于策略配置使用。

在 Fabric 中授予托管身份权限

创建托管标识后，必须向其授予访问 Fabric 资源的权限。托管身份需要访问 GraphQL API 项目本身及其连接到的任何数据源（例如数据湖仓或数据仓库）。将标识添加为工作区成员是最简单的方式，因为这样可以同时授予对工作区中所有项的访问权限。

打开包含 GraphQL API 的 Fabric 工作区
选择“管理访问权限”
添加托管标识（例如 apim-id），并至少授予贡献者角色。

小窍门

若要进行更精细的控制，可以直接向各个 Fabric 项（API 及其数据源）授予权限，而不是工作区级访问权限。如果 API 使用单一登录（SSO）身份验证，则精细控制尤其重要。有关详细信息，请参阅身份验证和权限摘要。

将 APIM 配置为使用托管标识

在 Fabric 中授予权限时，需要告知 APIM 要使用的托管标识。此关联允许 APIM 在向 Fabric GraphQL API 发出请求时使用该标识进行身份验证。

在 Azure 门户中，导航到 APIM 实例
转到安全>托管身份
添加之前创建的用户分配的托管标识

添加身份验证策略

最后一个身份验证步骤是添加 APIM 策略，该策略使用托管标识获取访问令牌，并将其包含在对 Fabric 的请求中。此策略在每个请求上运行，自动处理令牌获取和续订。该策略使用 authentication-managed-identity 元素获取 Fabric API 资源的令牌，然后将其添加到 Authorization 标头。

在 APIM 中的 GraphQL API 中，选择 “API 策略 ”选项卡
编辑入站处理策略

在 <inbound><base/> 下添加以下 XML：

<authentication-managed-identity 
    resource="https://analysis.windows.net/powerbi/api" 
    client-id="YOUR-MANAGED-IDENTITY-CLIENT-ID" 
    output-token-variable-name="token-variable" 
    ignore-error="false" />
<set-header name="Authorization" exists-action="override">
    <value>@("Bearer " + (string)context.Variables["token-variable"])</value>
</set-header>

将 YOUR-MANAGED-IDENTITY-CLIENT-ID 替换为您的托管身份的客户端 ID
保存策略

测试连接

在继续添加缓存和速率限制之前，请验证身份验证设置是否正常工作。现在，测试可确保以后遇到的任何问题都与身份验证配置无关。

在 APIM 中，导航到你的 GraphQL API
转到“ 测试 ”选项卡
执行示例查询或突变以确认连接正常工作

配置响应缓存

响应缓存可显著减少 API 调用者的延迟，并减少 Fabric 数据源上的后端负载。 APIM 支持内置缓存或外部 Redis 实例。对于 GraphQL API，缓存使用请求正文（GraphQL 查询）作为缓存键，确保相同的查询返回缓存响应。

缓存 GraphQL 响应的好处：

降低延迟：缓存响应立即返回，而无需查询 Fabric
容量消耗较低：减少对 Fabric 的请求以降低 CU（容量单位）的使用情况
更好的可伸缩性：在不增加后端负载的情况下处理更多并发用户

添加缓存策略

若要实现缓存，请修改现有的身份验证策略，以添加缓存查找和存储逻辑。策略在将请求转发到 Fabric 之前检查缓存的响应，并存储成功的响应以供将来使用。此完整的策略示例演示身份验证和缓存如何协同工作：

<policies>
    <inbound>
        <base />
        <!-- Authenticate with managed identity -->
        <authentication-managed-identity 
            resource="https://analysis.windows.net/powerbi/api" 
            client-id="YOUR-MANAGED-IDENTITY-CLIENT-ID" 
            output-token-variable-name="token-variable" 
            ignore-error="false" />
        <set-header name="Authorization" exists-action="override">
            <value>@("Bearer " + (string)context.Variables["token-variable"])</value>
        </set-header>
        <!-- Check if response is cached -->
        <cache-lookup-value 
            key="@(context.Request.Body.As<String>(preserveContent: true))" 
            variable-name="cachedResponse" 
            default-value="not_exists" />
    </inbound>
    <backend>
        <!-- Only forward request if not cached -->
        <choose>
            <when condition="@(context.Variables.GetValueOrDefault<string>("cachedResponse") == "not_exists")">
                <forward-request />
            </when>
        </choose>
    </backend>
    <outbound>
        <base />
        <choose>
            <!-- Return cached response if it exists -->
            <when condition="@(context.Variables.GetValueOrDefault<string>("cachedResponse") != "not_exists")">
                <set-body>@(context.Variables.GetValueOrDefault<string>("cachedResponse"))</set-body>
            </when>
            <!-- Cache successful responses for 60 seconds -->
            <when condition="@((context.Response.StatusCode == 200) && (context.Variables.GetValueOrDefault<string>("cachedResponse") == "not_exists"))">
                <cache-store-value 
                    key="@(context.Request.Body.As<String>(preserveContent: true))" 
                    value="@(context.Response.Body.As<string>(preserveContent: true))" 
                    duration="60" />
            </when>
        </choose>
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

此策略的工作原理：

入站：通过托管标识进行身份验证，并检查响应是否根据 GraphQL 查询已缓存
后端：如果存在缓存的响应，则跳过将请求转发到 Fabric
出站：返回缓存的响应或将新的成功响应缓存 60 秒

验证缓存是否正常工作

要确认请求是否被缓存，请执行以下步骤：

在 APIM 中，执行同一 GraphQL 查询两次
跟踪 API 调用以查看缓存命中数

优化缓存持续时间

该示例使用 60 秒的缓存持续时间。根据数据新鲜度要求调整持续时间：

高频率更新：对频繁更改的数据使用较短的持续时间（10-30 秒）
静态或引用数据：对不经常更改的数据使用更长的持续时间（5-60 分钟）
实时要求：不要缓存必须始终返回最新数据的查询

有关高级缓存方案，包括缓存失效和外部 Redis 配置，请参阅 APIM 缓存策略。

速率限制

可以限制客户端在特定时间段内可以执行的 API 调用数。下面是一个速率限制策略条目的示例，可以添加在 <inbound><base/> 下方，该条目对每位用户每 60 秒最多允许两次调用。

<rate-limit-by-key 
    calls="2" 
    renewal-period="60" 
    counter-key="@(context.Request.Headers.GetValueOrDefault("Authorization"))" 
    increment-condition="@(context.Response.StatusCode == 200)" 
    remaining-calls-variable-name="remainingCallsPerUser" />

在一分钟内发送两个以上的 API 调用后，将收到一条错误消息：

{
    "statusCode": 429,
    "message": "Rate limit is exceeded. Try again in 58 seconds."
}

有关如何在 APIM 中配置速率限制策略的详细信息，请参阅文档。

最佳做法

将 APIM 与 GraphQL 的 Fabric API 集成时，请遵循以下建议：

安全性

使用托管标识：首选托管标识而不是 API 密钥或连接字符串进行身份验证
实现最低权限：仅授予托管标识所需的最低权限
仅启用 HTTPS：配置 APIM 以拒绝 HTTP 请求并强制实施 HTTPS
验证输入：在转发到 Fabric 之前，使用 APIM 策略验证 GraphQL 查询

Performance

缓存经常访问的数据：识别常见查询并设置适当的缓存持续时间
监视缓存命中率：使用 APIM 分析跟踪缓存有效性
优化速率限制：通过容量保护平衡用户体验
使用区域部署：在 Fabric 容量所在的同一区域中部署 APIM

监视和管理

启用诊断：配置 APIM 诊断日志记录以跟踪 API 使用情况
设置警报：为速率限制违规和错误创建警报
对 API 进行版本控制：使用 APIM 版本控制管理任何重大更改
记录 API：使用 APIM 的开发人员门户提供 API 文档

成本优化

大小正确的速率限制：设置与容量层一致的限制
监视容量消耗：跟踪 APIM 和 Fabric 容量使用情况
战略性地使用缓存：通过节省容量来平衡新鲜度要求
查看使用模式：定期分析哪些查询消耗最多的资源

概要

将 Microsoft Fabric API for GraphQL 与 Azure API 管理集成，将 Fabric 的强大数据功能与 APIM 的企业级 API 网关功能相结合。此组合提供：

增强安全性：托管标识身份验证、威胁防护和基于策略的访问控制
改进了可伸缩性：响应缓存、速率限制和跨多个后端的负载分布
更好的性能：通过缓存和优化的请求路由降低延迟
集中治理：跨多个 API 统一监视、版本控制和管理
成本控制：速率限制和缓存可降低 Fabric 容量消耗

按照本文中的配置步骤和最佳做法，可以构建一个可靠的、安全且可缩放的 API 层，该层支持整个组织的生产工作负荷。

反馈

此页面是否有帮助？

Last updated on 2026-01-21