索引
Date
(訊息)DayOfWeek
(列舉)Interval
(訊息)PhoneNumber
(訊息)PhoneNumber.ShortCode
(訊息)PostalAddress
(訊息)TimeOfDay
(訊息)TimeZone
(訊息)
日期
代表完整或部分的日曆日期,例如生日。您可以指明時段和時區,或者在其他地方指定時間或時區。日期以公曆為基準。可能代表下列其中一項:
- 完整日期,具有非零的年、月和日值。
- 日期為 0 的月份和日期,例如週年紀念日。
- 有 1 年,第 0 個月卻為 0 天。
- 年和月,但數字為零 (例如信用卡到期日)。
相關類型:
google.type.TimeOfDay
google.type.DateTime
google.protobuf.Timestamp
欄位 | |
---|---|
year |
日期的年份。這個值必須介於 1 至 9999,或 0 之間可指定不含年份的日期。 |
month |
一年中的月份。必須介於 1 到 12 之間,或 0 可以指定不含月份和日期的年份。 |
day |
一個月中的第幾天。這個值必須介於 1 至 31 之間,且有效的年份和月份;或 0 可讓您指定本身或年份和月份,但這些日期不明顯。 |
DayOfWeek
代表星期幾。
列舉 | |
---|---|
DAY_OF_WEEK_UNSPECIFIED |
未指定星期幾。 |
MONDAY |
星期一 |
TUESDAY |
週二 |
WEDNESDAY |
星期三 |
THURSDAY |
星期四 |
FRIDAY |
星期五 |
SATURDAY |
Saturday (週六) |
SUNDAY |
星期日 |
時間間隔
代表時間戳記。編碼為開始 (含) 和時間戳記結束 (不含) 的時間間隔。
開頭必須小於或等於結尾。如果開始時間等於結束,則間隔會留空 (比對不相符的時間)。如果您未指定開始和結束,則時間間隔隨時都會比對。
欄位 | |
---|---|
start_time |
選用設定。包括該區間的開始時間 (包括在內)。 如有指定,這個間隔的時間戳記必須等於或晚於開始時間。 |
end_time |
選用設定。排除時段的排除範圍結束。 如有指定,這個間隔的時間戳記必須早於結束時間。 |
PhoneNumber
代表電話號碼的物件,適合做為 API 線格式。
此表示法:
不應用於特定地區的電話號碼格式,例如「+1 (650) 253-0000 分機 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()); }
欄位 | |
---|---|
extension |
電話號碼的額外資訊。ITU 建議項目並未標準化,但可定義為一系列長度上限為 40 位數的數字。除了數字以外,其他一些撥號字元 (例如「,」(表示等待) 或「#」) 可儲存在這裡。 請注意,由於目前沒有任何地區使用包含短代碼的額外資訊,因此這個欄位通常只能搭配 E.164 號碼一起設定。系統會將此編號與 E.164 號碼分開保留,以便日後支援短程式碼延伸。 |
聯集欄位 kind 。必要欄位。可以是一般號碼或短碼。我們日後可能會將新欄位加入以下其中一個欄位,因此用戶端應該忽略無法對任何欄位進行編碼時的電話號碼。kind 只能是下列其中一項: |
|
e164_number |
以開頭加號 (「+」) 表示的電話號碼,後面接著採用寬鬆 ITU E.164 格式的電話號碼,該格式由國家/地區代碼 (1 至 3 位數字) 和訂閱者號碼組成,且沒有額外的空格或格式,例如:- 正確:「+15552220123」- 錯誤:「+1 (555) 222-01234 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
代表簡短代碼的物件,這類代碼通常比一般電話號碼短許多,可用於 MMS 和 SMS 系統中的訊息,以及縮寫電話 (例如「輸入 611 簡訊即可查看方案剩餘分鐘數)。
只有特定區域可使用這組短碼,且無法跨國家/地區撥號。因此,同樣的簡短代碼可能在不同地區,適用不同的用量和價格,例如美國和加拿大。
欄位 | |
---|---|
region_code |
必要欄位。地點的 BCP-47 區碼,可用於呼叫這個短碼,例如「US」和「BB」。 參考資料:- http://www.unicode.org/reports/tr35/#unicode_region_subtag |
number |
必要欄位。短碼數字,不含前置加號 (「+」) 或國家/地區代碼,例如「611」。 |
PostalAddress
表示郵寄地址,如郵政快遞或付款地址。如果是郵寄地址,郵政服務可將貨品寄送到場所、郵政信箱或類似位置。此表示法並不適用於建立地理位置 (街道、鄉鎮或山區) 的模型。
在一般使用情況下,系統會根據處理作業的類型,以使用者輸入或匯入現有資料的方式來建立地址。
地址輸入/編輯的建議:- 使用支援國際化的地址小工具 (例如 https://github.com/google/libaddressinput) - 在使用者使用該欄位的國家/地區外,不應向使用者顯示用於輸入或編輯欄位的 UI 元素。
如要進一步瞭解如何使用這個結構定義,請參閱:https://support.google.com/business/answer/6397478
欄位 | |
---|---|
revision |
所有新的修訂版本都必須能夠與舊的修訂版本回溯相容。 |
region_code |
必要欄位。地址所在國家/地區的 CLDR 地區代碼。這個代碼絕非透過推測而得出,並且是由使用者自行確保該值正確無誤。詳情請參閱 https://cldr.unicode.org/ 和 https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html。例如:瑞士的地區代碼為「CH」。 |
language_code |
選用設定。這個地址內容的 BCP-47 語言代碼 (如果已知)。通常是輸入表單的 UI 語言,或是符合地址的國家/地區所用的其中一個語言,或是使用音譯的對應項目。這個欄位可能會影響某些國家/地區的格式設定,但是不會影響資料的正確性,也絕不會影響任何驗證或其他非格式的相關作業。 如果不知道這個值為何,則應省略該值 (而非指定可能不正確的預設值)。 例如:「zh-Hant」、「ja」、「ja-Latn」、「en」。 |
postal_code |
選用設定。地址的郵遞區號。並非所有國家/地區都使用郵遞區號或要求必須填寫郵遞區號,不過在使用郵遞區號時,可能會對地址其他部分觸發額外的驗證作業 (例如美國對州/郵遞區號的驗證)。 |
sorting_code |
選用設定。國家/地區專屬的其他分類代碼。大多數國家/地區並不使用這個代碼。在使用分類代碼的國家/地區中,這個值為與「CEDEX」相似的字串,後面選擇性加上一個數字 (例如「CEDEX 7」),或是只有單一數字,並用來表示「區段代碼」(牙買加)、「寄送區域指示碼」(馬拉威) 或「郵局指示碼」(如象牙海岸)。 |
administrative_area |
選用設定。最高行政區,用於國家/地區的郵遞地址。例如,此值可以是州、省或縣。以西班牙為例來具體說明,此欄位的值為省,而非自治區 (例如「巴塞隆納」省,而不是「加泰隆尼亞」自治區)。許多國家/地區的郵寄地址並沒有使用行政區。例如,就瑞士而言,該欄位應該留空不填。 |
locality |
選用設定。一般是指地址的縣市/鄉鎮部分。例如:美國城市、義大利市鎮、英國郵鎮。如為未明確定義縣市或其縣市不適用此結構的地區,請將 locality 留白,改用 address_lines。 |
sublocality |
選用設定。地址的縣市以下行政區,例如社區、自治市鎮和區等。 |
address_lines[] |
非結構化的地址行,說明地址的低層級項目。 由於 address_lines 中的值不會有類型資訊,而且有時在單一欄位中可能會包含多個值 (例如「Austin, TX」),因此地址行的順序務必要明確。地址行的順序應為該地址所在國家/地區的「信封書寫順序」。在信封書寫順序可能不盡相同的地區 (如日本),可使用 address_language 讓地址更明確 (例如「ja」表示由大到小的排序,而「ja-Latn」或「en」則表示由小到大)。如此一來,您便可以根據語言來選取明確度最高的地址行。 地址允許的最小結構表示法是包含一個 region_code,並將其餘所有資訊放置在 address_lines 中。您可以在幾乎不使用地理定位的情况下,設定這類地址的格式,但至少在地址局部解析完畢之前,您無法對地址的任何組成部分進行語意推論。 如要處理完全非結構化的地址,我們建議您只建立包含 region_code 和 address_lines 的地址,並使用地理定位來進行 (而非猜測地址的哪些部分應該是縣市還是行政區)。 |
recipients[] |
選用設定。地址的收件人。在某些情況下,這個欄位可能會包含多行資訊。舉例來說,此欄位可能包含「代收者」資訊。 |
organization |
選用設定。地址中的機構名稱。 |
TimeOfDay
代表一天中的時間。日期和時區並不需要指定,或是在其他位置上指定。API 可選擇允許閏秒。相關類型為 google.type.Date
和 google.protobuf.Timestamp
。
欄位 | |
---|---|
hours |
一天的營業時間,以 24 小時製表示。值應介於 0 到 23 之間。API 可選擇允許使用「24:00:00」這類的值來表示營業打烊時間等情況。 |
minutes |
一天內的分鐘數。值必須介於 0 到 59 之間。 |
seconds |
時間的秒數。正常情況下,值必須介於 0 到 59 之間。如果 API 允許閏秒,則可允許值為 60。 |
nanos |
秒數的小數,以奈秒表示。值必須介於 0 到 999,999,999 之間。 |
TimeZone
代表 IANA 時區資料庫中的時區。
欄位 | |
---|---|
id |
IANA 時區資料庫時區,例如「America/New_York」。 |
version |
選用設定。IANA 時區資料庫版本號碼,例如「2019a」。 |