首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >数据鱼API · iCalendar 日历接口接入指南

数据鱼API · iCalendar 日历接口接入指南

原创
作者头像
用户12862874
发布于 2026-11-21 21:54:02
发布于 2026-11-21 21:54:02
60
举报

接口简介

「iCalendar 日历」是数据鱼API平台提供的日历文件生成与解析接口,Base 路径 /api/ics,共 3 个端点:健康检查、生成与解析。它把 RFC 5545 规定的 iCalendar 文本转换成一个 JSON 友好的事件结构,或反过来把事件数组拼装成可直接导入日历客户端的 .ics 内容,适合排班、会议邀请、活动日程这类需要跨客户端交换日程数据的业务。

接口的核心价值在于处理 iCalendar 的格式细节。日历文本对属性转义、字符集与折行有明确要求:分号、逗号与换行需要在文本属性中转义,单行不得超过 75 字节且必须按规则折行,多字节字符还不能在字节中间切断。这些规则手写容易出错,接口在生成侧统一转义与折行,在解析侧同步反转义并展开折行,调用方只需要关心业务字段。

时间处理采用浮动时间语义。生成时默认写入不带时区标识的本地时间,由日历客户端按所在时区解释;全天事件则改用 VALUE=DATE 的日期值,不写具体时刻。这一取舍让接口不必维护时区数据库,但也意味着跨时区协作时需要在业务侧明确约定。数据鱼API在这一接口上不引入外部依赖,所有处理都在请求内完成。

端点总览

方法

路径

说明

鉴权

GET

/api/ics/ping

健康检查,返回版本、时间与最大事件数

是(跨域预检除外)

POST

/api/ics/generate

由事件数组生成 iCalendar 文本

是

POST

/api/ics/parse

解析 iCalendar 文本为事件数组

是

通用约定

鉴权使用全站统一 Key,通过 X-API-Key 请求头或 ?api_key= 查询参数传递,未携带返回 4011,无效返回 4013。标注为 GET 的端点同样接受 POST,参数名一致,POST 可用 JSON body 或表单提交。响应默认是 JSON,统一为 code、msg、data 结构;generate 在 format=text 时例外,直接返回 .ics 文件内容而非 JSON 包裹。除跨域预检的 OPTIONS 外,所有端点都需要鉴权。

错误码方面,缺少参数返回 4001,参数非法返回 4002,路由不存在返回 4040,服务内部异常返回 5000。这一接口没有上游依赖,因此不会出现第三方服务不可用类的错误码,也没有缓存与任务轮询机制——每次请求都在当前进程内完成转换。

核心端点详解

生成 generate

把事件数组序列化为 iCalendar 文本,可同时返回 JSON 字段或直接输出文件。

参数

类型

必填

默认

说明

name

string

否

—

日历名称,写入 X-WR-CALNAME 属性

events

array

是

—

事件数组,每项含 title、start,可选 end、all_day、location、description

format

string

否

json

json 返回结构化结果,text 直接返回 .ics 文件内容

events 中每个元素的字段约定如下:title 为事件标题,start 为开始时间,end 为结束时间,all_day 为布尔值表示是否全天,location 与 description 为可选的文本属性。全天事件会以日期值写入 DTSTART;VALUE=DATE 与 DTEND;VALUE=DATE,此时 end 通常取次日日期,形成左闭右开的区间。

返回字段有三个:ics 是完整的日历文本,行间以回车换行分隔;data_uri 是把同一内容做 Base64 后拼成的 data:text/calendar 数据地址,可直接放进下载链接或前端预览;events 是成功写入的事件条数。

代码语言:javascript
复制
POST /api/ics/generate?api_key=YOUR_KEY
Content-Type: application/json

{"name":"项目日历","events":[{"title":"周会","start":"2026-11-09 10:00:00","end":"2026-11-09 11:00:00","location":"会议室 A"}]}

解析 parse

读取 iCalendar 文本,还原为事件数组,支持 RFC 折行展开与属性反转义。

参数

类型

必填

默认

说明

ics

string

是

—

待解析的 iCalendar 文本,可包含折行

返回 data 包含 name(日历名称,未设置时为 null)、events(事件数组)与 count(事件条数)。每个事件对象含 summary、start、end、all_day、location、description、uid、status 八个字段,其中后三项在源文本缺失时返回 null。时间统一输出为 YYYY-MM-DD HH:MM:SS 形式,全天事件同样按日期还原并置 all_day 为 true。

代码语言:javascript
复制
POST /api/ics/parse?api_key=YOUR_KEY
Content-Type: application/json

{"ics":"BEGIN:VCALENDAR\r\nVERSION:2.0\r\nBEGIN:VEVENT\r\nSUMMARY:周会\r\nDTSTART:20261109T100000\r\nEND:VEVENT\r\nEND:VCALENDAR\r\n"}

健康检查 ping

无请求参数,返回 msg 为 pong,data 含 version、time、max_events、endpoints 与一条关于浮动时间的 note。其中 max_events 明确给出单次生成的事件上限,endpoints 列出当前可用端点,便于探活时同时确认部署版本。该端点与其他接口一样需要鉴权,只有跨域预检请求例外。

数据与限制

  • 单次生成事件数:上限 50 条,由健康检查返回的 max_events 给出。
  • 折行规则:按 75 字节折行,多字节字符按安全边界切分,不会把 UTF-8 序列拆开。
  • 转义范围:文本属性中的分号、逗号与换行按 RFC 5545 转义,解析侧执行对应的反转义。
  • 时间口径:默认浮动时间,不带时区标识;全天事件使用日期值,不需要时分秒。
  • 解析能力:支持折行展开,可识别 SUMMARY、DTSTART、DTEND、LOCATION、DESCRIPTION、UID、STATUS 等常用属性。
  • 状态:无状态服务,不落库、不写文件,相同的输入在任意时刻得到相同输出。
  • 响应体积:data_uri 会把整份日历再以 Base64 展开一次,返回体积约为原文的 1.37 倍,事件较多时注意响应大小。

典型使用场景

会议与排班系统把数据库中的日程批量转换为 .ics,让用户下载后导入 Outlook、日历或手机自带日历。活动报名平台在确认邮件里附上 data_uri 形式的日历下载链接,收件人一次点击即可把活动加入本地日历。日程同步工具把第三方日历导出的文本提交给解析端点,转成统一的事件结构后再入库比对。运维脚本定时请求健康检查端点,确认服务版本与事件上限是否符合预期。

注意事项

format=text 是一个容易忽略的默认值陷阱:该取值下响应不再是 JSON,而是文件内容,调用方若统一按 JSON 解析会失败。需要结构化字段(包括 data_uri 与事件计数)时应显式传 format=json 或省略该参数。生成端点要求 events 为非空数组,空数组与缺失字段都会落入参数类错误。

时间语义需要业务侧自行约定。浮动时间在跨时区场景下会被不同客户端解释为各自的本地时间,如果日程必须对齐绝对时刻,应在业务层把时间统一换算到目标时区后再传入,或在文本中自行补充时区定义——当前接口不生成时区组件。全天事件的结束日期按左闭右开处理,传同一天会得到零长度区间。解析端点则信任输入文本,不对事件数量做与生成侧相同的上限约束,处理超长文本时应在网关层限制请求体大小。数据鱼API对解析结果只做格式还原,不校验日程本身的业务合理性。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 生成 generate
    • 解析 parse
    • 健康检查 ping
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档