Storyblok Management API怎么用 内容管理接口教程

Storyblok Management API是Storyblok的内容管理接口，可以通过API创建、更新和删除内容，适合做无头CMS的自动化内容管理。它采用REST风格，使用不同HTTP方法操作内容，返回JSON数据。本文以故事（Story）为例，带你从准备令牌到发布和删除内容走一遍。管理内容用Management API；面向网站访客读取内容时，通常使用Content Delivery API。

第一步：获取管理令牌

先登录Storyblok，在目标Space的设置或个人访问令牌管理入口创建Personal Access Token，并确认账号对该Space有相应权限。记下Space ID和令牌，后续请求会用到。不同区域的Space可能对应不同API主机，欧盟常用https://mapi.storyblok.com/v1；请按Space所在区域选择地址，不要把示例主机照搬到所有项目。

调用时把令牌放进Authorization请求头，通常无需在请求体重复传入。建议将令牌保存在服务器环境变量或密钥管理服务中，别写进公开前端代码、仓库或日志。下面的示例用YOUR_TOKEN和SPACE_ID作占位符，实际使用时替换为自己的值。若收到401或403，先检查令牌、Space ID及账号权限，再确认请求域名与区域匹配。

第二步：创建和更新内容

创建故事使用POST请求，路径为/v1/spaces/{SPACE_ID}/stories。请求头设置Authorization和Content-Type: application/json，请求体包含story对象，例如name、slug和content。content根节点应为对象，并带component字段；新建内容默认不会发布。先创建草稿并检查返回的story数据，可避免把不完整内容直接推到线上。

更新现有故事使用PUT请求，路径末尾追加故事的数字ID，例如/v1/spaces/{SPACE_ID}/stories/{STORY_ID}。在请求体的story中提交需要更新的字段；需要同时发布时可设置publish为true，若只保存草稿则设为false。更新前先确认故事ID对应正确条目，并妥善处理接口返回的错误状态码，避免批量任务因单条失败而静默漏改。

使用组件和字段

content里的component值要与Space中定义的组件技术名称一致，字段名也应匹配组件结构。举例来说，页面组件可包含title字段和body数组；数组中的每个嵌套组件都应有component和_uid。_uid用于标识组件实例，不要把组件名称写成展示标签。字段结构不确定时，先在编辑器查看组件定义，再用少量测试内容验证数据能否正常显示。

需要批量导入时，可先按组件结构整理JSON，再逐条发送创建或更新请求，并记录成功与失败的内容ID。列表接口可能分页，导出或核对数据时留意page和per_page参数。遇到429限流响应，应降低调用频率，并采用带逐步延长间隔的重试机制；不要对所有错误无差别重试，以免产生重复操作或持续撞限。

第三步：发布和删除内容

发布可在创建或更新请求中设置publish为true；也可以对已有故事单独发送GET请求到/v1/spaces/{SPACE_ID}/stories/{STORY_ID}/publish。启用了单独发布翻译的项目，可按接口要求附带lang参数。发布后建议查看返回结果，并在预览或前台确认页面内容、链接和组件显示正常；涉及重要页面时，最好先走草稿审核流程。

删除故事使用DELETE请求，地址为/v1/spaces/{SPACE_ID}/stories/{STORY_ID}，其中story_id是数字ID。删除通常是不可轻率执行的内容变更，批处理前先导出备份、核对ID，并对目标列表做人工抽样确认。若只是暂时撤下内容，可先考虑取消发布而不是删除。注意管理接口适合后台自动化，调用凭据应只保存在可信服务端。

若团队希望用更可视化的方式规划页面和协作制作原型，可了解国内工具墨刀AI；它适用于设计与原型协作，并非Storyblok Management API的同类接口替代品。润灭也可将这类设计流程与内容管理流程分别评估，按团队需要选择工具：modao.cgref.cn。

“`