时区和 REST API

一些 REST API 端点允许您在请求中指定时区信息。

一些创建新数据（如创建新提交）的请求允许您在指定或生成时间戳时提供时区信息。

请注意，这些规则仅适用于传递给 API 的数据，不适用于 API 返回的数据。API 返回的时间戳采用 UTC 时间，ISO 8601 格式。

确定请求的时区

要确定适用的 API 调用的时区信息，我们按优先级顺序应用以下规则

  1. 明确提供带有时区信息的 ISO 8601 时间戳
  2. 使用 Time-Zone 标头
  3. 使用用户的上次已知时区
  4. 在没有其他时区信息的情况下，默认为 UTC

明确提供带有时区信息的 ISO 8601 时间戳

对于允许指定时间戳的 API 调用，我们使用该确切时间戳。这些时间戳看起来类似于 2014-02-27T15:05:06+01:00。

一个示例是管理提交的 API。有关更多信息，请参阅“Git 提交的 REST API 端点”。

使用 Time-Zone 标头

可以提供 Time-Zone 标头，该标头根据 Olson 数据库中名称列表定义时区。

curl -H "Time-Zone: Europe/Amsterdam" -X POST https://api.github.com/repos/github-linguist/linguist/contents/new_file.md

这意味着我们为您的 API 调用进行的时刻生成一个时间戳，在该标头定义的时区中。

例如，用于管理内容的 API 为每次添加或更改生成一个 git 提交，并使用当前时间作为时间戳。有关更多信息，请参阅“存储库内容的 REST API 端点”。Time-Zone 标头将确定用于生成该当前时间戳的时区。

使用用户的上次已知时区

如果没有指定 Time-Zone 标头，并且您对 API 进行身份验证调用，我们将使用经过身份验证的用户的上次已知时区。每当您浏览 GitHub 网站时，上次已知时区都会更新。

在没有其他时区信息的情况下，默认为 UTC

如果上述步骤未产生任何信息，我们将使用 UTC 作为时区。