# 时区与 REST API

某些 REST API 端点允许通过请求指定时区信息。

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

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

## 确定请求的对应时区

我们按照优先顺序应用以下规则来确定相应 API 调用的时区信息：

1. [明确提供带有时区信息的 ISO 8601 时间戳](#explicitly-providing-an-iso-8601-timestamp-with-timezone-information)
2. [使用 `Time-Zone` 标头](#using-the-time-zone-header)
3. [使用用户的最后一个已知时区](#using-the-last-known-timezone-for-the-user)
4. [在没有其他时区信息的情况下默认使用 UTC](#defaulting-to-utc-without-other-timezone-information)

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

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

其中一个示例是用于管理提交的 API。 有关详细信息，请参阅“[Git 提交的 REST API 终结点](/zh/enterprise-server@3.22/rest/git/commits#create-a-commit)”。

### 使用 `Time-Zone` 标头

可以提供一个 `Time-Zone` 标头，该标头根据 [Olson 数据库中的名称列表](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)定义时区。

```shell
curl -H "Time-Zone: Europe/Amsterdam" -X POST http(s)://HOSTNAME/api/v3/repos/github-linguist/linguist/contents/new_file.md
```

这意味着当你在这个标题定义的时区做出 API 调用时，我们会生成一个时间戳。

例如，用于管理内容的 API 会为每个添加或更改生成 git 提交，并使用当前时间作为时间戳。 有关详细信息，请参阅“[存储库内容的 REST API 终结点](/zh/enterprise-server@3.22/rest/repos/contents)”。 此 `Time-Zone` 标头将确定用于生成当前时间戳的时区。

### 使用用户的最后一个已知时区

如果未指定 `Time-Zone` 标头，并且你对 API 进行经过身份验证的调用，则我们对经过身份验证的用户使用最后一个已知时区。 每当你浏览 GitHub 网站时，最新一个已知时区都会更新。

### 在没有其他时区信息的情况下默认使用 UTC

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