如何获取Gmail API休假设置startTime/endTime对应的时区信息

调用Gmail API的users.settings.getVacation接口获取用户自动回复（假期）设置时，返回的startTime和endTime字段均为纪元毫秒（epoch ms）格式的int64数值，这类数值和用户Gmail账户绑定的时区对应，但接口返回结果中没有附带时区信息，无法直接转换为用户当地的日期。

接口返回示例（GMT+0200时区用户）：

{
  "enableAutoReply": false,
  "responseSubject": "OOF",
  "responseBodyHtml": "OOF",
  "restrictToContacts": false,
  "restrictToDomain": false,
  "startTime": "1630188000000",
  "endTime": "1630879200000"
}

示例中的startTime对应的时间为 Sat Aug 28 2021 22:00:00 GMT+0000 / Sun Aug 29 2021 00:00:00 GMT+0200，也就是用户设置的假期开始时间为当地时区的8月29日零点。

要拿到用户时区对应的午夜日期，按以下两步操作即可：

1. 获取用户对应的时区 #

这是必要前提，没有正确的时区信息会导致转换出的日期偏移1天。两种常用获取方案：

• 方案1：通过Google官方接口获取账户绑定时区
  申请日历设置只读权限后，调用Google日历API的时区设置接口，可直接获取用户Gmail账户绑定的IANA格式时区（如Europe/Paris、Asia/Shanghai），该时区和假期时间戳的绑定时区完全一致，准确度最高。
• 方案2：前端直接获取设备时区
  如果应用运行在用户本地设备上，可直接通过运行环境的API获取当前设备的时区，只要用户设备时区和Gmail账户设置时区一致即可正常使用，无需额外申请授权权限。

2. 时间戳转换为对应时区的日期 #

拿到时区后，使用支持时区转换的日期库处理即可，以下是两种常用语言的代码示例：

JavaScript示例（基于dayjs+时区插件） #

const dayjs = require('dayjs')
const utc = require('dayjs/plugin/utc')
const timezone = require('dayjs/plugin/timezone')
dayjs.extend(utc)
dayjs.extend(timezone)

// 示例参数：startTime为1630188000000，用户时区为Europe/Paris
const userTimezone = 'Europe/Paris'
const startTime = 1630188000000
const localDate = dayjs(startTime).tz(userTimezone).format('YYYY-MM-DD')
// 输出：2021-08-29，即用户时区的午夜对应日期

Python示例（基于pytz库） #

from datetime import datetime
import pytz

user_timezone = pytz.timezone('Europe/Paris')
start_time = 1630188000000 / 1000 # 转换为秒级时间戳
local_dt = datetime.fromtimestamp(start_time, tz=user_timezone)
local_date = local_dt.strftime('%Y-%m-%d')
# 输出：2021-08-29

• 不要直接将时间戳转换为UTC时间或者运行环境的本地时间，否则会出现日期偏移，比如示例中的时间戳转UTC得到的是2021-08-28，和用户实际设置的日期差1天。
• 优先使用IANA格式的时区（如Asia/Shanghai），不要用固定偏移的GMT±X格式，避免夏令时切换导致的计算错误。

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