Zion API 配置与使用指南

API（应用程序编程接口）是连接不同应用与外部数据的桥梁。在 Zion 平台中，API 可用于集成外部数据源，实现数据交互与自动化操作。

API 基础构成

在 Zion 配置 API 前，请先了解 API 的基本要素：

方法（Method）
域名（Domain）
路径（Path）
请求头（Headers）
查询参数（Query Parameters）
请求体（Body）

如需深入了解 API 基础知识，建议查阅相关网络资料。

配置流程

本文以“从明道云获取数据”为例，演示完整配置流程。

添加 API

打开编辑器左上角的“API”菜单，点击“添加配置”。

Zion 添加 API 配置界面

选择操作类型

此步骤决定 API 的用途：

查询：API 作为组件（如列表、页面等）的数据源
修改：API 用于行为操作

本例选择“查询”，将 API 作为列表的数据源。

选择 API 操作类型

设置请求格式

Zion 支持两种请求格式配置方式：

自动解析（推荐）：成功发送一次请求后，系统自动解析格式
手动配置：开发者手动填写所有参数

自动解析格式流程如下：

打开调试模式。
填写方法、域名、路径、请求体等信息，点击“发送”。
发送成功后，点击“高级”，检查格式是否正确。
依次确认“请求参数”和“响应参数”无误。若为更新配置，需合并新旧参数。
完成确认后，即可获得标准的 API 请求与响应格式。

特殊字段格式与映射

1. 外部图片字段

当通过第三方 API 接收图片时，若获取到的是图片的 URL 地址或 Base64 编码的图片数据，需要将其转换为 Zion 系统兼容的图片格式。

此时，可将该字段的编码方式设置为：

URL_MEDIA_ENCODE（针对图片 URL）
BASE64_MEDIA_ENCODE（针对 Base64 数据）

系统会自动处理：对于 URL，将从指定地址下载图片；对于 Base64，将直接解析数据。随后，系统会将图片上传至对象存储数据库，完成格式转换，使其符合 Zion 系统的图片要求。

json_encode

2. JSON 字符串字段

在某些情况下，JSON 对象中的某个字段值可能是一个经过转义的 JSON 字符串，而非直接的 JSON 对象。例如，在以下 JSON 结构中，avatar 字段的内容是一个字符串，而不是预期的对象类型：


{
    "data": {
        "name": "won",
        "utime": "2025-06-16 11:15:59",
        "avatar": "[{\"file_id\":\"4f397aff-854a-4a6a-b0e9-bc727c6f7f0a\",\"thumbnail_path\":\"https://p1.mingdaoyun.cn/5468936e-68cb-4cd4-9c4c-27e595e2cbd4/f1de66a1-6f32-4689-8050-27daf8622a35/664b3008bf24123e1d6231eb/20250616/\",\"thumbnail_name\":\"9A5d7M6T841pck0samaQcp8z215e9L3f38cD6EdI3V5OfDfmfwauc04X2B97cocR.jpeg?imageView2/1/w/200/h/118\",\"large_thumbnail_path\":\"https://p1.mingdaoyun.cn/5468936e-68cb-4cd4-9c4c-27e595e2cbd4/f1de66a1-6f32-4689-8050-27daf8622a35/664b3008bf24123e1d6231eb/20250616/\",\"large_thumbnail_name\":\"9A5d7M6T841pck0samaQcp8z215e9L3f38cD6EdI3V5OfDfmfwauc04X2B97cocR.jpeg?imageView2/2/w/1280/h/800\",\"file_path\":\"https://p1.mingdaoyun.cn/5468936e-68cb-4cd4-9c4c-27e595e2cbd4/f1de66a1-6f32-4689-8050-27daf8622a35/664b3008bf24123e1d6231eb/20250616/\",\"file_name\":\"9A5d7M6T841pck0samaQcp8z215e9L3f38cD6EdI3V5OfDfmfwauc04X2B97cocR.jpeg\",\"file_size\":49779,\"is_delete\":false,\"file_type\":1,\"original_file_name\":\"20240329-173729.jpeg\",\"allow_down\":true,\"large_thumbnail_full_path\":\"https://p1.mingdaoyun.cn/5468936e-68cb-4cd4-9c4c-27e595e2cbd4/f1de66a1-6f32-4689-8050-27daf8622a35/664b3008bf24123e1d6231eb/20250616/9A5d7M6T841pck0samaQcp8z215e9L3f38cD6EdI3V5OfDfmfwauc04X2B97cocR.jpeg?imageView2/2/w/1280/h/800\",\"thumbnail_full_path\":\"https://p1.mingdaoyun.cn/5468936e-68cb-4cd4-9c4c-27e595e2cbd4/f1de66a1-6f32-4689-8050-27daf8622a35/664b3008bf24123e1d6231eb/20250616/9A5d7M6T841pck0samaQcp8z215e9L3f38cD6EdI3V5OfDfmfwauc04X2B97cocR.jpeg?imageView2/1/w/200/h/118\",\"original_file_full_path\":\"https://p1.mingdaoyun.cn/5468936e-68cb-4cd4-9c4c-27e595e2cbd4/f1de66a1-6f32-4689-8050-27daf8622a35/664b3008bf24123e1d6231eb/20250616/9A5d7M6T841pck0samaQcp8z215e9L3f38cD6EdI3V5OfDfmfwauc04X2B97cocR.jpeg\",\"origin_link_url\":null,\"short_link_url\":null,\"share_folder_url\":null,\"is_knowledge\":false,\"node_id\":\"\",\"allow_view\":true,\"width\":0,\"height\":0,\"duration\":0.0,\"allow_edit\":false,\"DownloadUrl\":\"https://p1.mingdaoyun.cn/5468936e-68cb-4cd4-9c4c-27e595e2cbd4/f1de66a1-6f32-4689-8050-27daf8622a35/664b3008bf24123e1d6231eb/20250616/9A5d7M6T841pck0samaQcp8z215e9L3f38cD6EdI3V5OfDfmfwauc04X2B97cocR.jpeg\",\"WaterMarkInfo\":null,\"preview_url\":\"https://p1.mingdaoyun.cn/5468936e-68cb-4cd4-9c4c-27e595e2cbd4/f1de66a1-6f32-4689-8050-27daf8622a35/664b3008bf24123e1d6231eb/20250616/9A5d7M6T841pck0samaQcp8z215e9L3f38cD6EdI3V5OfDfmfwauc04X2B97cocR.jpeg?e=1750134776&token=PGtAPYyCYxCQ1zckbL-ecATOk42z8P3jdPahEnzt:NwmuTHZsm-KENJXaWF1QahIQz9k=\",\"createTime\":\"2025-06-16 11:15:39\"}]",
    }
}