如何将Delivery API格式的JSON重新导入Kentico Kontent？

我之前处理过不少类似的场景，你遇到的报错核心原因很明确：Delivery API返回的JSON格式和Management API要求的导入格式完全不兼容。前者是为前端消费优化的，包含了大量解析后的字段（比如展开的链接内容、渲染好的富文本）；而后者是用来创建/更新内容的原始结构化格式，需要严格遵循内容类型、字段定义的规范。

下面是具体的解决步骤和方法：

一、先理清两种格式的核心差异 #

• Delivery API格式：返回的是items数组，每个内容项包含system（元数据）和elements（解析后的字段值，比如链接项会完整展开成对象），还会附带modular_content、includes等辅助数据。
• Management API格式：要求的是包含content_types（可选，若需创建类型）和content_items的结构，每个内容项的elements字段需要传入原始值（比如链接项只需要目标内容项的codename或id数组），且必须依赖已存在的内容类型。

二、针对kontent-sample-blog-travel-vue项目的导入流程 #

1. 先重建内容类型 #

从sample-data的Delivery JSON里，你可以提取所有用到的内容类型codename（比如blog_post、author、category）。你有两种方式创建这些类型：

• 手动在Kontent项目后台创建：对照Delivery JSON里的字段类型（比如text、rich_text、linked_items），逐个配置内容类型的字段。
• 用Management API批量创建：如果能找到该sample项目的内容类型定义（通常sample项目会附带），可以写脚本调用/content-types端点批量创建。

2. 转换Delivery JSON为Management兼容格式 #

你需要对每个内容项做以下调整（可以写简单的JavaScript脚本批量处理）：

• 保留system.name作为内容项的名称
• 将system.type映射为内容类型的codename
• 处理elements字段：
  • 对于linked_items类型：把Delivery里展开的对象数组，换成对应内容项的codename数组（比如把value: [{system: {codename: "jane_smith"}}]改成value: ["jane_smith"]）
  • 对于rich_text类型：如果Delivery返回的是HTML，Management API支持直接传入HTML让系统自动解析为结构化富文本
  • 对于date_time或其他字段：直接保留原始值即可

举个转换前后的示例：
Delivery格式片段：

{
  "system": {
    "name": "Summer in Kyoto",
    "type": "blog_post"
  },
  "elements": {
    "author": {
      "type": "linked_item",
      "value": [
        {
          "system": { "codename": "jane_smith" },
          "elements": { "name": { "value": "Jane Smith" } }
        }
      ]
    }
  }
}

Management格式片段：

{
  "name": "Summer in Kyoto",
  "type": {
    "codename": "blog_post"
  },
  "elements": {
    "author": {
      "type": "linked_items",
      "value": ["jane_smith"]
    }
  }
}

3. 导入转换后的内容 #

你有两种可靠的导入方式：

• 官方导入/导出工具：在Kontent项目后台的「项目设置」→「导入/导出」里，选择JSON导入，上传转换后的符合格式要求的文件。工具会自动校验格式并给出错误提示。
• 自定义脚本调用Management API：
  1. 从Kontent项目后台获取Management API密钥（「项目设置」→「API密钥」）
  2. 按依赖顺序导入内容项（比如先导入author、category，再导入blog_post，因为文章依赖作者和分类）
  3. 使用批量请求端点/bulk来提高导入效率，减少API调用次数

4. 快速捷径（针对该sample项目） #

很多Kontent sample项目会提供现成的导入脚本，你可以查看项目的README文件：

• 通常会用到kentico-kontent-cli工具，运行类似kontent import --project-id YOUR_PROJECT_ID --file sample-data/transformed-data.json的命令
• 如果项目提供了内容类型的JSON定义，可以直接用CLI导入类型和内容项

三、通用的Delivery API结果重新导入Kontent的方法 #

如果以后你需要把任意Delivery API的结果导回Kontent，流程都是一样的：

1. 提取内容类型信息：从Delivery响应的items里获取所有system.type，确保目标项目里存在对应的内容类型（或先创建）
2. 批量转换格式：编写脚本将Delivery格式的elements字段转换为Management API要求的原始值格式
3. 按依赖顺序导入：先导入被依赖的内容项（比如分类、作者），再导入依赖它们的内容项（比如文章）
4. 校验和调试：如果导入报错，查看Management API的错误响应，通常会提示字段类型不匹配、找不到内容类型或链接项等问题，针对性调整即可

内容的提问来源于stack exchange，提问作者hkato