用CloudKit REST API server-to-server key创建公共记录报INTERNAL_ERROR

1. 优先核查签名计算逻辑 #

这是触发该错误的最高发原因，CloudKit 在校验签名失败时，经常不会返回明确的鉴权错误，而是直接抛出无具体上下文的 INTERNAL_ERROR

• 你当前脚本的签名生成流程不符合规范：
  • 直接把明文拼接的$date:$encoded:$subpath字符串放到X-Apple-CloudKit-Request-SignatureV1请求头中，没有按照CloudKit要求，用对应的EC私钥对拼接好的签名串做SHA256加密、再做base64编码，服务端校验流程会直接异常
  • base64编码请求体时，用echo $body | base64会自动在编码内容末尾追加换行符，导致编码结果和实际发送的请求体内容不匹配，进一步引发签名校验失败。应该换成不带额外换行的编码方式，比如用printf "%s" "$body" | base64生成编码串。

2. 核查请求体字段格式 #

CloudKit 写入接口不接受直接的原生JSON字段值，所有字段必须按照指定类型的嵌套结构传参，格式不符时极易触发服务端解析异常：

• Date/Time类型的date字段，不能直接传裸字符串"2021-01-09T12:00:00Z"，需要套成CloudKit要求的字段结构："date": {"value": "2021-01-09T12:00:00Z"}
• Int(64)单值类型的type字段，不能直接传裸数字1，需要嵌套结构传值："type": {"value": 1}
• Int(64)列表类型的numbers字段，不能直接传原生数字数组，需要按照列表类型的规范嵌套："numbers": {"value": [14, 26, 38, 45, 46, 13]}
  如果直接传原生值，服务端类型解析失败时会直接抛出内部错误，不会返回明确的字段格式报错。

3. 核查操作参数配置 #

• 你当前使用的操作类型是forceReplace，该操作仅适用于已存在的记录。首次创建新recordName对应的记录时，应该把operationType改成create，对不存在的记录执行强制替换操作，部分场景下会触发服务端逻辑异常返回内部错误。
• 首次排查阶段可以把atomic: true暂时改成false，原子事务模式下任意一个操作的校验异常，都可能被包装成通用内部错误，关闭原子模式可以更快定位具体出错的操作项。

4. 核查权限与配置匹配度 #

• 确认你请求头里填的KeyID，是开发者后台专门为CloudKit生成的服务端到服务端专用密钥，不是其他类型的开发者密钥
• 确认该密钥已经被授予对应iCloud容器公共数据库的写入权限，公共数据库本身没有设置只读锁定
• 确认请求路径里的container ID、环境标识和开发者后台配置的完全一致，没有拼写、大小写偏差

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