Google Chat API如何切换Cards v1与Cards v2版本

Cards v2不需要单独通过请求头、路径参数向服务器声明版本，出现字段未知/缺失的报错，核心原因是请求体结构错误，而非版本未声明，具体排查和修复方法如下：

• 确认使用的API端点为正式版v1路径即可，不存在独立的Cards v2专属API路径，也不需要切换到beta版端点调用
• 修正请求体的字段层级：Cards v1的内容放在请求根节点的cards数组下，Cards v2的内容必须放在请求根节点的cardsV2数组下，且每个v2卡片对象需要包含cardId和嵌套的card字段，适配服务账号认证调用的Python请求结构示例如下：

# 服务账号认证场景下，发送Cards v2消息的正确请求体结构
message_body = {
    "parent": "spaces/对应聊天空间ID",
    "cardsV2": [
        {
            "cardId": "自定义全局唯一卡片标识",
            "card": {
                # 此处填写v2卡片的具体配置，包含header、sections等标准v2字段
                "header": {"title": "卡片标题"},
                "sections": [
                    {
                        "widgets": [
                            {"textParagraph": {"text": "卡片正文内容"}}
                        ]
                    }
                ]
            }
        }
    ]
}

• 常见报错触发场景：不要把v2的卡片组件字段直接塞到旧版cards数组下，也不要漏写cardId必填字段，这两类问题占该类报错的90%以上
• 原有服务账号认证逻辑完全不需要修改，和调用Cards v1时的认证流程完全兼容，只需要调整消息体的字段结构即可

不要尝试添加自定义版本声明请求头、或修改API路径到不存在的v2版本地址，目前Google Chat API公开正式版本为v1，Cards v2是该版本下原生支持的消息格式，不属于独立API版本。

内容的提问来源于stack exchange，提问作者Georg Wicke-Arndt