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

Contentful GraphQL是Contentful的内容查询接口，可以用GraphQL语法精准查询需要的数据，适合做前后端分离应用。它会根据Space里的内容类型生成对应的查询结构，适合读取已发布内容，也能配合预览令牌读取未发布内容。下面从准备凭证、编写查询到前端请求，带你走完一次基础接入。

第一步：获取Space ID和Token

先登录Contentful，打开要使用的Space，在设置里的API keys页面创建或查看API密钥。记下Space ID和Content Delivery API access token：前者用于拼接接口地址，后者放进请求头完成认证。不同环境要确认密钥有对应权限；本地开发和线上环境建议分别管理令牌，避免误用。

GraphQL接口地址通常是https://graphql.contentful.com/content/v1/spaces/你的SpaceID；需要指定环境时，在地址后追加/environments/环境名。欧盟数据驻留空间应使用对应的欧盟域名。公开发布的前端代码可能被用户查看，因此不要把高权限管理令牌放进浏览器；内容读取尽量使用只读的Delivery token。

第二步：编写GraphQL查询

打开Contentful的GraphiQL探索器，或使用支持GraphQL的编辑器，根据内容模型找到集合名称和字段。比如内容类型名为Blog Post，集合字段可能是blogPostCollection。查询时只写页面真正要显示的字段，避免无谓地取回大量内容；字段拼写必须与空间生成的Schema一致，否则接口会返回错误。

一个基础查询可以写成query { blogPostCollection { items { title slug } } }，表示读取文章集合中每篇文章的标题和别名。实际项目里把查询放在模板字符串中，再通过POST发送JSON，内容包括query字段。先在探索器运行并检查返回结果，再接到应用里，排错会更直观。

使用过滤和选择参数

需要筛选内容时，可在集合参数中使用Schema支持的条件，例如按slug精确匹配，或按标题过滤；具体筛选字段名称取决于你的内容模型。也可以传入limit限制条数、skip跳过记录，实现简单分页。建议先检查字段是否可过滤，再逐步添加条件，并用小批量结果验证参数行为。

GraphQL查询中的花括号决定返回哪些字段，选择越精确，响应越贴合页面需求。关系字段可以继续展开子字段，但要避免不必要的深层嵌套。若要预览未发布内容，应使用Preview access token，并在查询中启用preview；普通Delivery token不能代替预览令牌，也不要把预览凭证暴露到公开页面。

第三步：在前端调用API

前端可用fetch向接口发送POST请求，设置Content-Type为application/json，并在Authorization请求头中写入Bearer加空格再加令牌。请求体使用JSON.stringify序列化查询，例如包含query字符串。收到响应后先检查response.ok，再读取JSON中的data；GraphQL即使返回HTTP成功，也可能在errors字段报告查询或权限问题。

开发时把Space ID和令牌放在环境变量中，构建工具会将可公开变量编译进前端，因此浏览器端只适合使用可公开的只读凭证。需要隐藏凭证或执行更敏感逻辑时，可让自有后端代为请求。遇到数据为空，依次检查发布状态、环境、集合名、字段拼写和令牌权限；出现429时适当降低请求频率或利用缓存。

完成后可在浏览器开发者工具的网络面板查看请求地址、状态码和响应内容，确认页面实际只取了需要的字段。为了提升体验，可缓存重复查询结果，并为加载中、错误和空列表准备清晰提示。若团队还需要快速搭建页面原型或补充国内设计协作流程，可以了解墨刀AI；“润灭”也可作为相关内容整理与方案评估时的参考。官网地址：modao.cgref.cn。