如何在Google Sheets API v4(PHP)中将键值对映射到指定列？

Google Sheets API v4 已经完全弃用了 v3 版本基于 XML 的 gsx: 命名空间条目格式，改为使用 JSON 结构的请求体，要实现通过表头键名自动映射到对应列写入值的功能，按以下步骤操作即可：

1. 先建立表头列名与列位置的映射 #

首先读取表格的表头行（通常为工作表的第1行），获取所有列名，生成列名: 列索引的映射关系，逻辑如下：

• 假设表头行范围为 Sheet1!1:1，调用 spreadsheets.values.get 接口读取该行数据
• 遍历返回的表头数组，把每个表头字符串和对应的下标（从0开始计数）绑定存入映射字典

2. 构造写入请求 #

拿到映射关系后，把你的键值对按列索引顺序填充为行数据数组，再调用对应接口写入即可。

举个实际示例：
假设你读取到的表头为 ["姓名", "年龄", "职业"]，生成的映射为 {"姓名":0, "年龄":1, "职业":2}，现在需要写入的键值对为 {"姓名":"张三", "年龄":"28", "职业":"程序员"}，按索引顺序填充后得到的行数据为 ["张三", "28", "程序员"]。

常用场景示例 #

场景1：向表格末尾追加新行

调用 spreadsheets.values.append 接口，请求体结构如下：

{
  "values": [
    ["张三", "28", "程序员"]
  ]
}

请求参数里指定范围为你要写入的工作表范围（例如Sheet1!A1），并将 valueInputOption 参数设为 RAW 或 USER_ENTERED 即可。

场景2：更新指定行的数据

如果需要修改某一行的指定列值，同样通过映射找到对应列的位置，调用 spreadsheets.values.update 接口写入即可。

注意事项 #

• 表头如果包含空格、特殊字符不需要额外转义，直接和键名做字符串匹配即可，比v3的gsx:格式兼容更好
• 如果你的键值对存在缺失的键，对应列位置填空字符串即可，不会影响其他列的写入

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