Umbraco GraphQL怎么用 内容查询接口教程

Umbraco GraphQL是Umbraco的内容查询接口，可以用GraphQL语法精准查询需要的数据，适合做前后端分离的网站和应用。不过要先分清：Umbraco内置的Content Delivery API是REST接口，并不是GraphQL；使用GraphQL通常需要安装兼容当前Umbraco版本的扩展或自行开发接口。下面按通用流程介绍，具体端点和密钥配置要以所用扩展的文档为准。

第一步：获取API密钥

先确认项目使用的Umbraco版本，再选择兼容的GraphQL扩展，按扩展说明安装并启用。进入后台或项目配置，查看它是否提供GraphQL端点、访问控制和密钥选项。并非每个扩展都要求API密钥；若使用内置Delivery API，则需启用该功能，并根据访问设置决定是否配置ApiKey。

如果扩展支持密钥认证，就在服务端配置密钥，不要把密钥直接写进公开网页的JavaScript，也不要提交到公开代码仓库。可通过环境变量或部署平台的密钥管理功能注入。开发环境先用测试密钥验证请求；上线前再设定允许访问的内容范围，并确认草稿内容不会被公开读取。

第二步：编写GraphQL查询

打开扩展提供的GraphQL Playground、GraphiQL或其他交互式工具，先查看Schema，确认内容类型、字段名和关联字段。不同项目的别名可能不同，不要照抄示例后就假设字段可用。查询时只选页面真正需要的字段，例如标题、摘要和图片地址，减少返回体积，也更容易检查数据结构。

在查询工具中先写一个最小请求，查看是否返回数据，再逐项加入字段。GraphQL请求通常把查询文本放在JSON的query属性中，具体HTTP方法和请求路径取决于扩展。例如：

{“query”:”{ articles { items { title summary } } }”}

这只是说明查询结构的示例，articles、items、title和summary必须替换为实际Schema中的名称。若报字段不存在，先检查拼写、大小写和内容类型是否已发布；若返回空列表，确认内容已发布、语言版本正确，并查看扩展的权限或过滤规则。

使用过滤和排序参数

若Schema提供过滤、分页和排序参数，可先在后台工具中查看参数类型，再按其定义传值。常见思路是限制内容类型或关键字，指定排序字段及方向，并设置页码或每页数量。不要凭REST接口的参数名推断GraphQL参数名，两种接口的Schema和语法可能完全不同。

例如，扩展若定义了变量参数，可把筛选条件作为变量传入，而不是把用户输入拼接进查询字符串。这样便于复用查询，也能减少格式错误。分页时设定合理的每页条数；排序结果还应指定稳定字段，避免内容相同或新增时页面数据顺序跳动。

第三步：在前端调用API

前端通过fetch向扩展给出的GraphQL端点发送POST请求，设置Content-Type为application/json，并把query放进请求体。若接口需要密钥，应由受控的服务端代理附加认证信息；不要在浏览器源代码中暴露长期有效的密钥。请求失败时检查端点、状态码、响应中的errors字段及跨域设置。

拿到响应后，先判断HTTP状态，再读取JSON，并按Schema的实际层级访问数据。页面上对标题、摘要等内容做合适的转义与展示；图片字段为空时准备占位图。可以在开发者工具的Network面板查看请求和响应，确认只拉取必要字段，并处理加载中、空结果和错误提示。

上线前用非管理员身份测试公开页面，确认只返回已发布且允许展示的内容。若项目实际使用的是Umbraco内置Content Delivery API，它采用REST查询，例如多内容端点为/umbraco/delivery/api/v2/content，支持fetch、filter、sort、skip、take和fields等参数，并非GraphQL语法；配置ApiKey也取决于是否关闭公开访问。需要快速制作原型时，可了解国内替代工具墨刀AI，官网：modao.cgref.cn。润灭也可作为查找教程和方案时的参考名称，但请以实际项目文档核验功能。