Package google.type

索引

• Date (訊息)
• DayOfWeek (列舉)
• Interval (訊息)
• PhoneNumber (訊息)
• PhoneNumber.ShortCode (訊息)
• PostalAddress (訊息)
• TimeOfDay (訊息)
• TimeZone (訊息)

日期

表示完整或部分的日曆日期，例如生日。您可以視重要性決定是否要在別處指定時段和時區。日期以公曆為主，可代表下列任一項目：

• 完整日期，具有非零的年、月和日值。
• 月和日值，年值為零 (例如週年紀念日)。
• 只有年，月和日值為零。
• 年和月，日值為零 (例如信用卡到期日)。

相關類型：

• google.type.TimeOfDay
• google.type.DateTime
• google.protobuf.Timestamp

欄位
year	int32 日期的年份。必須為 1 到 9999；如要指定不含年份的日期，請輸入 0。
month	int32 月份。必須為 1 到 12；如要指定不含日期的年份，請輸入 0。
day	int32 當月第幾日。必須為 1 到 31，並屬於有效的年和月；如果只指定年份，或只指定年份和月份，而不指定當月第幾日的話，請輸入 0。

DayOfWeek

代表星期幾。

列舉
DAY_OF_WEEK_UNSPECIFIED	未指定星期幾。
MONDAY	星期一
TUESDAY	週二
WEDNESDAY	週三
THURSDAY	週四
FRIDAY	Friday (週五)
SATURDAY	Saturday (週六)
SUNDAY	星期日

時間間隔

代表時間間隔，編碼為時間戳記開始時間 (包含在內) 和時間戳記結束時間 (不含在內)。

開始時間必須小於或等於結束時間。如果開始時間等於結束時間，則表示間隔為空白 (不符合任何時間)。如果未指定開始和結束時間，則間隔會與任何時間相符。

欄位
start_time	Timestamp 選用設定。有效時間範圍的起始值 (含)。 如果指定了這個間隔，則時間戳記必須與這個間隔相同或之後。
end_time	Timestamp 選用設定。限制時段的結束時間 (不包含在內)。 如果指定了這個間隔，則必須在結束時間之前，提供符合這個間隔的時間戳記。

PhoneNumber

代表電話號碼的物件，適合作為 API 電報格式。

以下是這項表示法：

• 不應用於電話號碼的語言代碼專屬格式，例如「[phone] ext. 123」

• 並非針對高效儲存空間而設計

• 可能不適合用於撥號 - 應使用專用程式庫 (請參閱參考資料) 剖析號碼

如要對此號碼執行有意義的操作，例如為各種用途設定格式，請先將其轉換為 i18n.phonenumbers.PhoneNumber 物件。

例如，在 Java 中，這會是：

com.google.type.PhoneNumber wireProto =
    com.google.type.PhoneNumber.newBuilder().build();
com.google.i18n.phonenumbers.Phonenumber.PhoneNumber phoneNumber =
    PhoneNumberUtil.getInstance().parse(wireProto.getE164Number(), "ZZ");
if (!wireProto.getExtension().isEmpty()) {
  phoneNumber.setExtension(wireProto.getExtension());
}

參考資料：- https://github.com/google/libphonenumber

欄位
extension	string 電話號碼的副號。ITU 建議中並未對擴充字尾進行標準化，僅定義為一連串數字，長度上限為 40 位數。除了數字之外，這裡可能會儲存其他撥號字元，例如「,」(表示等待) 或「#」。 請注意，目前沒有任何地區使用含有短碼的擴充功能，因此這個欄位通常只會與 E.164 號碼一起設定。這項資訊會與 E.164 號碼分開保管，以便日後新增短碼擴充功能。
聯集欄位 kind。必要欄位。可以是一般號碼或簡碼。未來可能會在下方的 oneof 中新增欄位，因此如果用戶端所對應的任何欄位都未設定，就應忽略該電話號碼。kind 只能是下列其中一項：
e164_number	string 電話號碼，以開頭加號 ('+') 表示，後面接著採用放寬版 ITU E.164 格式的電話號碼，其中包含國家/地區撥打代碼 (1 到 3 位數) 和訂閱者號碼，不含額外的空格或格式設定。例如： - 正確："[phone]" - 不正確："[phone] x123"。 ITU E.164 格式規定後者最多只能有 12 位數，但實際上並非所有國家/地區都遵守這項規定，因此我們在這裡放寬了這項限制。不允許僅限國內使用的電話號碼。 參考資料：- https://www.itu.int/rec/T-REC-E.164-201011-I - https://en.wikipedia.org/wiki/E.164。- https://en.wikipedia.org/wiki/List_of_country_calling_codes
short_code	ShortCode 短碼。 參考資料：- https://en.wikipedia.org/wiki/Short_code

ShortCode

代表短碼的物件，短碼通常比一般電話號碼短得多，可用於 MMS 和 SMS 系統中的訊息，以及縮寫撥號 (例如「傳送簡訊至 611，查看你的方案剩餘分鐘數」。)

短碼僅限於特定區域使用，無法撥打國際電話，也就是說，同一個短碼可能會出現在不同區域，且使用方式和價格各異，即使這些區域使用相同的國家/地區撥打代碼 (例如美國和加拿大) 也是如此。

欄位
region_code	string 必要欄位。可撥打這個短碼的地區的 BCP-47 區域代碼，例如「US」和「BB」。 參考資料：- http://www.unicode.org/reports/tr35/#unicode_region_subtag
number	string 必要欄位。短碼的數字，不含開頭的加號 ('+') 或國家/地區撥號代碼。例如「611」。

PostalAddress

代表郵寄地址。例如郵寄地址或付款地址。如果是郵寄地址，郵政服務可將貨品寄送到場所、郵政信箱或類似位置。此表示法並不適用於建立地理位置 (街道、鄉鎮或山區) 的模型。

在一般使用情況下，系統會根據處理作業的類型，以使用者輸入或匯入現有資料的方式來建立地址。

地址輸入/編輯的建議：使用支援國際化的地址小工具 (如 https://github.com/google/libaddressinput)；在使用該欄位的國家/地區以外的位置上，不應向使用者顯示用於輸入或編輯欄位的 UI 元素。

如要進一步瞭解如何使用這個結構定義，請參閱：https://support.google.com/business/answer/6397478

欄位
revision	int32 PostalAddress 的結構定義修訂版本。這個欄位的值必須設為 0，即代表最新的修訂版本。 所有新的修訂版本都必須能夠與舊的修訂版本回溯相容。
region_code	string 必要欄位。地址所在國家/地區的 CLDR 地區代碼。這個代碼絕非透過推測而得出，並且是由使用者自行確保該值正確無誤。詳情請參閱 https://cldr.unicode.org/ 和 https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html。例如：瑞士的地區代碼為「CH」。
language_code	string 選填。這個地址內容的 BCP-47 語言代碼 (如果已知)。通常是輸入表單的 UI 語言，或是符合地址的國家/地區所用的其中一個語言，或是使用音譯的對應項目。這個欄位可能會影響某些國家/地區的格式設定，但是不會影響資料的正確性，也絕不會影響任何驗證或其他非格式的相關作業。 如果不知道這個值為何，則應省略該值 (而非指定可能不正確的預設值)。 例如：「zh-Hant」、「ja」、「ja-Latn」、「en」。
postal_code	string 選用設定。地址的郵遞區號。並非所有國家/地區都使用郵遞區號或要求必須填寫郵遞區號，不過在使用郵遞區號時，可能會對地址其他部分觸發額外的驗證作業 (例如美國對州/郵遞區號的驗證)。
sorting_code	string 選用設定。國家/地區專屬的其他分類代碼。大多數國家/地區並不使用這個代碼。在使用該值時，其值為「CEDEX」之類的字串，後面可視需要加上數字 (例如「CEDEX 7」)，或僅為數字，代表「部門代碼」(牙買加)、「送達區域指標」(馬拉威) 或「郵局指標」(例如象牙海岸)。
administrative_area	string 選用設定。最高行政區，用於國家/地區的郵遞地址。例如，此值可以是州、省或縣。以西班牙為例來具體說明，此欄位的值為省，而非自治區 (例如「巴塞隆納」省，而不是「加泰隆尼亞」自治區)。許多國家/地區的郵寄地址並沒有使用行政區。例如，就瑞士而言，該欄位應該留空不填。
locality	string 選用設定。一般是指地址的縣市/鄉鎮部分。例如：美國城市、義大利市鎮、英國郵鎮。如為未明確定義縣市或其縣市不適用此結構的地區，請將 locality 留白，改用 address_lines。
sublocality	string 選用設定。地址的縣市以下行政區，例如社區、自治市鎮和區等。
address_lines[]	string 非結構化的地址行，說明地址的低層級項目。 由於 address_lines 中的值不會有類型資訊，而且有時在單一欄位中可能會包含多個值 (例如「Austin, TX」)，因此地址行的順序務必要明確。地址行的順序應為該地址所在國家/地區的「信封書寫順序」。在信封書寫順序可能不盡相同的地區 (例如日本)，可使用 address_language 讓地址更明確 (例如「ja」表示由大到小的排序，而「ja-Latn」或「en」則表示由小到大)。如此一來，您便可以根據語言來選取明確度最高的地址行。 地址允許的最小結構表示法是包含一個 region_code，並將其餘所有資訊放置在 address_lines 中。您可以在幾乎不使用地理定位的情况下，設定這類地址的格式，但至少在地址局部解析完畢之前，您無法對地址的任何組成部分進行語意推論。 如要處理完全非結構化的地址，我們建議您只建立包含 region_code 和 address_lines 的地址，並使用地理定位來進行 (而非猜測地址的哪些部分應該是縣市還是行政區)。
recipients[]	string 選用設定。地址的收件人。在某些情況下，這個欄位可能會包含多行資訊。舉例來說，此欄位可能包含「代收者」資訊。
organization	string 選用設定。地址中的機構名稱。

TimeOfDay

代表一天中的時間。日期和時區並不需要指定，或是在其他位置上指定。API 可選擇允許閏秒。相關類型為 google.type.Date 和 google.protobuf.Timestamp。

欄位
hours	int32 一天中的小時，採用 24 小時制。必須大於或等於 0，且通常必須小於或等於 23。API 可選擇允許使用「24:00:00」這類的值來表示營業打烊時間等情況。
minutes	int32 小時內的分鐘。必須大於或等於 0，且小於或等於 59。
seconds	int32 分鐘內的秒數。必須大於或等於 0，且通常必須小於或等於 59。如果 API 允許閏秒，則可允許值為 60。
nanos	int32 秒數的小數，以奈秒為單位。必須大於或等於 0，且小於或等於 999,999,999。

TimeZone

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

欄位
id	string IANA 時區資料庫時區。例如「America/New_York」。
version	string 選用設定。IANA 時區資料庫版本號碼。例如「2019a」。