Package google.type

אינדקס

תאריך

מייצג תאריך קלנדרי מלא או חלקי, כמו יום הולדת. השעה ביום ואזור הזמן מצוינים במקום אחר או שהם לא חשובים. התאריך מתייחס ליומן הגרגוריאני. הערך הזה יכול לייצג אחת מהאפשרויות הבאות:

  • תאריך מלא, עם ערכים שאינם אפס לשנה, לחודש וליום.
  • חודש ויום, עם אפס בשנה (לדוגמה, יום נישואין).
  • שנה ללא חודש ויום.
  • שנה וחודש, עם יום אפס (לדוגמה, תאריך תפוגת תוקף של כרטיס אשראי).

סוגים קשורים:

שדות
year

int32

השנה של התאריך. חייב להיות בין 1 ל-9999, או 0 כדי לציין תאריך ללא שנה.
month

int32

החודש בשנה. הערך צריך להיות בין 1 ל-12, או 0 כדי לציין שנה ללא חודש ויום.
day

int32

היום בחודש. הערך חייב להיות בין 1 ל-31 ותקף לשנה ולחודש, או 0 כדי לציין שנה בלבד או שנה וחודש שבהם היום לא רלוונטי.

DayOfWeek

מייצג יום בשבוע.

טיפוסים בני מנייה (enum)
DAY_OF_WEEK_UNSPECIFIED היום בשבוע לא צוין.
MONDAY שני
TUESDAY שלישי
WEDNESDAY רביעי
THURSDAY חמישי
FRIDAY שישי
SATURDAY שבת
SUNDAY ראשון

מרווח

מייצג מרווח זמן, שמקודד כחותמת זמן להתחלה (כולל) וכחותמת זמן לסיום (לא כולל).

ההתחלה חייבת להיות קטנה מסיום או שווה לו. כשההתחלה שווה לסיום, מרווח הזמן ריק (לא מתאים לשום זמן). אם לא מציינים את תחילת האירוע ואת סיום האירוע, מרווח הזמן תואם לכל זמן.

שדות
start_time

Timestamp

אופציונלי. תחילת המרווח, כולל.

אם יצוין תאריך חותמת זמן שתואמת למרווח הזמן הזה, הוא יצטרך להיות זהה לתאריך ההתחלה או מאוחר ממנו.
end_time

Timestamp

אופציונלי. סיום המרווח, בלעדי.

אם יצוין טווח זמן, חותמת הזמן שתתאים לטווח הזה תצטרך להיות לפני הסיום.

מספר טלפון

אובייקט שמייצג מספר טלפון, מתאים כפורמט של API.

הייצוג הזה:

  • אסור להשתמש בהם לפורמט ספציפי לאזור גיאוגרפי של מספר טלפון, למשל '‎+1 (650) 253-0000 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 ספרות) ומספר המנוי, ללא רווחים או עיצוב נוספים. לדוגמה: - נכון: ‎+15552220123‎ - שגוי: ‎+1 (555) 222-01234 x123‎.

פורמט E.164 של ITU מגביל את מספר הטלפון ל-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. - אסור להציג למשתמשים רכיבי ממשק משתמש להזנה או לעריכה של שדות מחוץ למדינות שבהן השדה הזה נמצא בשימוש.

הנחיות נוספות לשימוש בסכימה הזו זמינות בכתובת: 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 של התוכן בכתובת הזו (אם ידוע). לרוב זו שפת ממשק המשתמש של טופס הקלט, או שהיא אמורה להתאים לאחת מהשפות שבהן נעשה שימוש במדינה או באזור של הכתובת, או לשמות המקבילים שלהן בתעתיק. הדבר עשוי להשפיע על הפורמט במדינות מסוימות, אבל הוא לא קריטי לנכונות הנתונים, ולעולם לא ישפיע על תיקוף או על פעולות אחרות שלא קשורות לפורמט.

אם הערך הזה לא ידוע, צריך להשמיט אותו (במקום לציין ערך ברירת מחדל שעלול להיות שגוי).

דוגמאות: 'zh-Hant',‏ 'ja',‏ 'ja-Latn',‏ 'en'.
postal_code

string

אופציונלי. המיקוד של הכתובת. לא בכל המדינות נעשה שימוש במיקוד או נדרש להוסיף מיקוד, אבל במדינות שבהן נעשה שימוש במיקוד, הוא עשוי להפעיל אימות נוסף של חלקים אחרים בכתובת (לדוגמה, אימות של מדינה או מיקוד בארה"ב).
sorting_code

string

אופציונלי. קוד מיון נוסף, ספציפי למדינה. ברוב האזורים לא נעשה שימוש באפשרות הזו. במקרים שבהם הוא משמש, הערך הוא מחרוזת כמו 'CEDEX', אחריה יכול להופיע מספר (לדוגמה, 'CEDEX 7'), או רק מספר לבד, שמייצג את 'קוד התחום' (ג'מייקה), 'מחוון אזור המסירה' (מלווי) או 'מחוון של סניף דואר' (לדוגמה, קוט ד'יורו).
administrative_area

string

אופציונלי. הרמה המנהלית הגבוהה ביותר שמשמשת לכתובות דואר של מדינה או אזור. לדוגמה, יכול להיות שמדובר במדינה, במחוז, בפרובינציה או במחוז. בספרד, הפרמטר הזה מייצג את המחוז ולא את הקהילה האוטונומית (לדוגמה, 'Barcelona' ולא 'Catalonia'). במדינות רבות לא נהוג לציין אזור אדמיניסטרטיבי בכתובות דואר. לדוגמה, בשוויץ לא צריך לאכלס את השדה הזה.
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'.