Python向Google Sheets追加数据时如何指定表头匹配列？

要解决列顺序不匹配和新列的问题，核心思路是先对齐待追加数据与Google Sheets的现有表头，同时自动处理新列的添加，具体步骤如下：

1. 获取Google Sheets的现有表头 #

首先通过API读取表格第一行的表头，明确目标列的顺序和已有列：

# 获取现有表头行
header_range = f"{sheet_name}!1:1"
header_response = service.spreadsheets().values().get(
    spreadsheetId=gsheetid,
    range=header_range
).execute()
existing_headers = header_response['values'][0]

2. 处理待追加数据的列对齐与新列 #

根据现有表头调整待追加DataFrame的列顺序，缺失列补空，同时自动添加新列到表头（如果需要）：

import pandas as pd

# 假设这是你的待追加数据DataFrame
df_to_append = pd.DataFrame({
    'date': ['2017-08-07', '2017-08-08'],
    'kfc': [52, 726],
    'burgerking': [52, 45],
    'anw': [32, 53]
})

# 检测待追加数据中的新列（现有表头没有的列）
new_columns = [col for col in df_to_append.columns if col not in existing_headers]

# 如果有新列，先更新Google Sheets的表头
if new_columns:
    updated_headers = existing_headers + new_columns
    update_header_req = service.spreadsheets().values().update(
        spreadsheetId=gsheetid,
        range=header_range,
        valueInputOption="USER_ENTERED",
        body={'values': [updated_headers]}
    ).execute()
    # 更新表头变量，后续对齐数据用
    existing_headers = updated_headers

# 对齐数据列顺序到现有表头，缺失列填充空字符串（可改为0等默认值）
aligned_df = df_to_append.reindex(columns=existing_headers, fill_value="")

3. 执行数据追加 #

将对齐后的DataFrame转成符合API要求的二维列表，再执行追加：

# 转成二维列表（仅数据行，不含表头）
new_list = aligned_df.values.tolist()

# 执行追加操作
append_request = service.spreadsheets().values().append(
    spreadsheetId=gsheetid,
    range=sheet_name,
    valueInputOption="USER_ENTERED",
    insertDataOption="INSERT_ROWS",
    body={'values': new_list}
)
response = append_request.execute()

关键注意事项 #

• 如果不需要保留新列，可跳过新列检测和表头更新步骤，直接reindex到现有表头，新列会被自动丢弃
• 缺失列的填充值可根据需求修改（比如数值列填0，字符串列填空）
• 确保你的Google Sheets API服务账号拥有读取、写入表格的权限

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