DateTime

代表民用時間 (有時是實際時間)。

這種類型可透過以下幾種方式表示民間時間：

  • 已設定 utcOffset 且未設定 timeZone 時：日曆天中的民用時間，與世界標準時間的偏移量。
  • 已設定 timeZone 且未設定 utcOffset 時：特定時區的日曆日中民用時間。
  • 如果時區和 utcOffset 均未設定，則：當地時間某一天的民用時間。

日期以公曆為基準。

如果年、月或日為 0，DateTime 不會分別有特定的年、月或日。

如果所有日期和時間欄位皆已設定，且已設定 time_offset 其中一項，這個類型也可以用來代表實際時間。建議改用Timestamp訊息表示實際時間。如果您的用途也想儲存使用者的時區，則可在其他欄位中完成儲存。

這種類型比某些應用程式更有彈性。請務必記錄及驗證應用程式的限制。

JSON 表示法 
{
  "year": integer,
  "month": integer,
  "day": integer,
  "hours": integer,
  "minutes": integer,
  "seconds": integer,
  "nanos": integer,

  // Union field time_offset can be only one of the following:
  "utcOffset": string,
  "timeZone": {
    object (TimeZone)
  }
  // End of list of possible types for union field time_offset.
}
欄位
year

integer

選用設定。年份。必須是 1 到 9999 之間的數字，如果指定不含年份的日期時間，則輸入 0。
month

integer

選用設定。月份。必須為 1 到 12，如要指定不含月份的日期時間，請輸入 0。
day

integer

選用設定。日。值必須介於 1 至 31 之間，且必須是有效的年份和月份；如果未指定日期的日期，則必須指定 0。
hours

integer

選用設定。一天中的小時，以 24 小時製表示。必須介於 0 到 23，預設值為 0 (午夜)。API 可選擇允許使用「24:00:00」這類的值來表示營業打烊時間等情況。
minutes

integer

選用設定。一天內的分鐘數。必須介於 0 到 59 之間，預設值為 0。
seconds

integer

選用設定。時間的秒數。通常介於 0 至 59 之間，預設值為 0。如果 API 允許閏秒，則可允許值為 60。
nanos

integer

選用設定。秒數的小數，以奈秒為單位。必須介於 0 到 999,999,999 之間，預設值為 0。
聯集欄位 time_offset。選用設定。指定 UTC 偏移或 DateTime 時區。請謹慎選擇，因為時區資料未來可能會變更 (例如，某個國家/地區修改了 DST 開始/結束日期，而該國家/地區內的未來 DateTime 已經儲存完畢)。如果省略日期時間，系統會將 DateTime 視為當地時間。time_offset 只能是下列其中一項：
utcOffset

string (Duration format)

世界標準時間偏移。必須是完整的秒數，介於 -18 小時至 +18 小時之間。舉例來說，-4:00 世界標準時間偏移的偏移值會以 { seconds: -14400 } 表示。

時間長度以秒為單位，最多可有 9 個小數位數，並結尾為「s」。例如："3.5s"。
timeZone

object (TimeZone)

時區。

TimeZone

代表 IANA 時區資料庫中的時區。

JSON 表示法 
{
  "id": string,
  "version": string
}
欄位
id

string

IANA 時區資料庫時區，例如「America/New_York」。
version

string

選用設定。IANA 時區資料庫版本號碼，例如「2019a」。