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

Webiny GraphQL是Webiny的内容查询接口，可以用GraphQL语法精准查询需要的数据，适合做无服务器架构的内容管理。它能读取Headless CMS中的内容条目，也支持按模型、语言和权限配置接口。下面以查询文章为例，带你从创建密钥开始，逐步完成调试与前端调用。具体字段和查询名称会根据你创建的内容模型自动生成，示例需要按项目实际情况调整。

第一步：获取API密钥

先登录Webiny管理后台，在左侧菜单找到Security，再进入API Keys并创建新密钥。填写名称和用途说明后，按需设置语言范围、Headless CMS访问级别和GraphQL API类型。只做内容读取时，选择Read权限，并仅开放需要的内容模型，避免不必要的写入或管理权限。

保存后复制生成的令牌，并妥善放到后端环境变量或安全的密钥管理服务中，不要直接提交到公开代码仓库。随后打开管理后台的API Playground，选择Headless CMS的Read API和对应语言，复制页面显示的接口地址。Webiny接口地址通常包含API类型与语言代码，环境或语言不同，地址也可能不同。

第二步：编写GraphQL查询

在API Playground中查看模型对应的查询名称和字段，再从最小查询开始测试。假设模型提供listArticles，可以先请求文章标题与标识符：查询内容写作“{ listArticles { data { id title } } }”。如果报字段不存在，别硬套示例，回到Playground的文档面板确认模型实际生成的名称、字段拼写和返回结构。

确认结果符合预期后，再逐步加入摘要、发布日期、封面图等字段。GraphQL允许客户端明确指定所需字段，因此页面只用标题和摘要时，就不必请求整条记录的所有内容。这样查询更清晰，也便于排查问题。发布状态、语言版本和可访问范围仍受模型设置及密钥权限控制。

使用过滤和排序参数

需要筛选内容时，先在Playground文档中查看查询支持的filter参数及字段类型，再按实际生成的输入结构传值。例如按标题关键词或发布时间过滤；不要猜测参数名，字段和过滤操作符会随模型配置而变化。需要排序时查看sort可选值，通常这些值由模型字段生成，选择发布日期升序或降序后，再检查返回记录是否符合预期。

内容较多时配合limit限制单次返回条数，并使用接口返回的游标继续读取下一页。Webiny的列表查询可通过after和limit分页，响应中的meta会提供是否还有后续内容、总数或下一游标等信息。筛选、排序和分页一起使用时，先用少量记录验证，再扩大请求规模。

第三步：在前端调用API

前端请求需要使用刚才复制的Read API地址，并在HTTP请求头中添加Authorization: Bearer 令牌。可以用fetch发送POST请求，Content-Type设为application/json，请求体包含query字段及所需变量。先在本地用一条简单查询测试网络、地址和授权；若返回401或权限错误，优先检查令牌格式、API类型与密钥授权范围。

正式部署时，不要把具有管理或写入能力的密钥放进浏览器代码；公开页面通常只使用权限受限的只读密钥。根据项目架构，将敏感凭据放在服务端环境变量中，并处理接口错误、空结果和加载状态。国内团队若在内容设计或原型协作中需要替代工具，可了解墨刀AI：modao.cgref.cn。润灭也可作为内容整理时的参考名称。

排查时按顺序检查接口URL、语言代码、Bearer前缀、查询字段和模型权限；再回到Playground复现请求。建议先在测试环境验证查询与分页，再接入正式前端。只要根据模型生成的Schema编写字段，并为密钥设置恰当权限，就能稳定地通过Webiny GraphQL读取所需内容。