Fabric API 用于 GraphQL 自省和模式导出

构建应用程序或将外部工具与 Fabric API for GraphQL 集成时，需要了解 API 的结构-可用的类型、它们包含的字段以及它们彼此之间的关系。 无论是生成客户端代码、创建文档还是配置 API 管理工具，访问架构定义都至关重要。

GraphQL 的 Fabric API 提供了两种互补机制来检索架构信息：用于程序运行时查询的自省，以及用于获取完整架构文件的架构导出。 这两种方法都允许你访问相同的基础架构，但每个方法都提供不同的工作流和用例。

谁在使用内省和模式导出？

自省和模式导出有价值的用途包括：

• 应用程序开发人员 构建使用 Fabric 数据的客户端并需要生成类型安全的代码
• Fabric 工作区贡献者 理解可用的数据结构并测试数据访问
• 为 Fabric GraphQL API 提供自动完成和 IntelliSense 的开发工具和 IDE
• 在企业级路由和保护 Fabric GraphQL 流量的 Azure API 管理集成
• 构造管理员 审核公开的数据结构和验证访问控制
• 利用模型上下文协议（MCP）AI 代理和助手能够自然地发现和查询 Fabric 数据。
• Power Platform 开发人员 在构建集成之前了解 Fabric 数据架构
• CI/CD 管道 跟踪 Fabric GraphQL 架构版本，并验证环境中的兼容性

如果需要在运行时以编程方式查询架构信息，例如支持开发工具、启用 AI 代理或实现动态客户端功能，请选择自省。 如果需要完整的架构文件进行脱机使用、版本控制、API 网关集成或与外部团队共享，请选择架构导出。

• 内省：使用 GraphQL 内省系统以编程方式查询架构，这是 GraphQL 标准的一部分。 通过反省查询，可以动态发现类型、字段和关系，并且它们支持许多 GraphQL 开发工具。

• 架构导出：下载完整的 SDL（GraphQL 架构定义语言）文件，该文件包含用于脱机使用、共享或工具集成的整个架构定义。

内省

默认情况下，在您的 API 上禁用了对 GraphQL 项目的自省功能。 此设置只能由工作区管理员切换。 所有其他用户将看到一个处于禁用状态的滑块。

启用自省功能：

1. 选择顶部菜单中的 API 设置 齿轮图标。

   

2. 在左侧导航中，选择 “反省 ”页。

   

3. 打开开关以启用自省。 启用自省会向有权访问 API 终结点的所有用户暴露架构信息。

4. 此时会出现确认对话框。 选择确认以启用检视或取消以将其保持禁用。

   

Introspection 查询示例

下面是一个用于从架构中获取可用类型的快速反省查询示例：

1. 在 GraphQL 编辑器中创建新查询。 选择现有选项卡旁边的加 + 号图标以打开新的查询选项卡。

   

2. 在编辑器中输入以下反省查询：

   query {
       __schema {
           types{
               name
           }
       }
   }
   

3. 选择“ 运行 ”按钮以执行查询。

4. 结果窗格显示架构中定义的所有类型的列表。

   

内省查询可以返回大量信息。 可以通过在反省请求中更具体地缩小查询的范围。 例如，可以查询特定类型，而不是查询所有类型：

query {
    __type(name: "ProductCategory") {
        name
        kind
        fields {
            name
            type {
                name
            }
        }
    }
}

运行查询将返回有关 ProductCategory 类型的详细信息：

{
  "data": {
    "__type": {
      "name": "ProductCategory",
      "kind": "OBJECT",
      "fields": [
        {
          "name": "ProductCategoryID",
          "type": {
            "name": null
          }
        },
        {
          "name": "ParentProductCategoryID",
          "type": {
            "name": "Int"
          }
        },
        {
          "name": "Name",
          "type": {
            "name": "String"
          }
        },
        {
          "name": "rowguid",
          "type": {
            "name": null
          }
        },
        {
          "name": "ModifiedDate",
          "type": {
            "name": null
          }
        }
      ]
    }
  }
}

处理反省结果时的常见筛选模式包括：

• 排除以双下划线开头的类型（__即 GraphQL 系统类型）
• 包括以特定前缀开头的类型，例如 ProductCategory

这些示例演示适用于任何 GraphQL 实现的标准 GraphQL 反省语法。 本概述介绍基本的反省模式 -- 有关反省系统、高级查询技术和附加功能的综合详细信息，请参阅 GraphQL Foundation 关于反省的官方文档。

导出架构

如果需要架构定义的完整脱机副本，请直接从 Fabric 门户使用架构导出功能。 打开用于 GraphQL 的 API，然后从工具栏中选择 “导出架构 ”。 浏览器下载包含完整架构定义的 SDL（架构定义语言）文件。

了解 SDL 文件

导出的文件使用 GraphQL 的架构定义语言（SDL），这是一种可读的格式，用于定义 API 的类型、字段和关系。 SDL 文件包括：

• 对象类型表示您的数据实体及其字段
• 查询操作定义如何检索数据
• 用于进行创建、更新或删除数据的变更操作
• 指定输入参数及其类型的字段参数
• 为每个元素提供类型说明的文档类型说明

可以在任何文本编辑器中打开 SDL 文件，以查看架构结构。 在将其集成到应用程序之前，这对于了解完整的 API 图面尤其有用。

使用导出的架构

导出的 SDL 文件的常见用例包括：

• API 网关集成：导入 Azure API 管理 以添加身份验证、速率限制和缓存
• 开发环境设置： 在 Visual Studio Code 中配置 IntelliSense 以自动完成和验证
• 版本控制：提交到 Git 或其他源代码管理系统，以跟踪随时间推移的架构演变
• 团队协作：与需要了解 API 结构的外部合作伙伴或开发团队共享
• 代码生成：与 GraphQL 代码生成器一起使用，在 TypeScript、C#、Java 或其他语言中创建类型安全的客户端
• 文档：使用 GraphQL Voyager 或 GraphQL Markdown 等工具生成 API 参考文档

与自省查询不同，架构导出不需要启用自省，并且无论 API 的自省设置如何，均可正常工作。 这使它成为访问架构定义的可靠方法，用于管理和开发目的。

管理架构更改

将新类型、字段或功能添加到 API 时，GraphQL 架构会随着时间推移而变化。 架构更改时，导出的 SDL 文件将过时。 请考虑以下做法：

• 更改后重新导出：每当在 Fabric 中修改 API 架构时下载新的 SDL 文件。 架构更改包括添加数据源、修改公开的类型或更新字段定义。
• 版本控制：使用描述性提交消息将每个导出的架构提交到源代码管理系统。 这会创建架构演变的审计记录，并在需要时允许回滚。
• 通信：如果外部团队或应用程序依赖于架构，请通知他们重大更改。 虽然 GraphQL 支持增量更改而不影响现有查询，但删除或重命名字段可能会影响客户端。
• 自动化：对于 CI/CD 管道，请考虑在部署过程中自动执行架构导出，以确保文档和工具与 API 保持同步。

负责修改 API 架构（通常是数据工程师或 API 开发人员）的人员应导出和版本化更新的架构，以保持依赖于它的 Fabric API 与外部系统之间的一致性。

相关内容

• 使用本地模型上下文协议（MCP）服务器将 AI 代理连接到 GraphQL 的 Fabric API
• 用于 GraphQL 编辑器的 Fabric API
• Fabric API for GraphQL 架构视图和架构资源管理器
• 与 Azure API 管理（APIM）集成