מייצג זמן אזרחי (או זמן פיזי).
סוג זה יכול לייצג זמן אזרחי בכמה דרכים אפשריות:
- כאשר utcOffset מוגדר ו-timeZone לא מוגדר: שעה אזרחית ביום קלנדרי עם הבדל זמן ספציפי מ-UTC.
- כש-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 |
שדות | |
---|---|
year |
אופציונלי. השנה. חייב להיות בין 1 ל-9999, או בין 0 אם מציינים תאריך ושעה ללא שנה. |
month |
אופציונלי. החודש בשנה. חייב להיות בין 1 ל-12, או 0 אם מציינים תאריך ושעה ללא חודש. |
day |
אופציונלי. היום בחודש. חייב להיות בין 1 ל-31 ותקף לשנה ולחודש, או 0 אם מציינים תאריך ושעה ללא יום. |
hours |
אופציונלי. שעות ביום בפורמט של 24 שעות. המספר צריך להיות בין 0 ל-23, ברירת המחדל היא 0 (חצות). ממשק API עשוי לבחור לאפשר את הערך '24:00:00' לתרחישים כמו שעת סגירה של עסק. |
minutes |
אופציונלי. דקות ביום. המספר צריך להיות בין 0 ל-59, ברירת המחדל היא 0. |
seconds |
אופציונלי. שניות ספורות של הזמן. בדרך כלל חייב להיות בין 0 ל-59, ברירת המחדל היא 0. ממשק API עשוי לאפשר את הערך 60 אם הוא מאפשר שניות מעוברות. |
nanos |
אופציונלי. מקטעים של שניות בננו-שניות. הערך חייב להיות בין 0 ל-999,999,999, ברירת המחדל היא 0. |
שדה איחוד time_offset . אופציונלי. המדיניות מציינת את הבדלי הזמן לפי UTC או את אזור הזמן של TimeTime. כדאי לבחור בקפידה ביניהם, מפני שהנתונים של אזור הזמן עשויים להשתנות בעתיד (למשל, מדינה משנה את תאריכי ההתחלה והסיום של שעון הקיץ, וטווחי התאריכים הבאים בטווח התאריכים הזה כבר אוחסנו). אם יושמט, ה-DateTime ייחשב כזמן מקומי. time_offset יכול להיות רק אחד מהבאים: |
|
utcOffset |
הסטה משעון UTC. משך הזמן צריך להיות שניות שלמות, בין 18- ל-+18 שעות. לדוגמה, היסט של UTC בגובה -4:00 יוצג כ-{ seconds: -14400 }. משך זמן בשניות עם עד תשע ספרות עשרוניות, המסתיים ב-' |
timeZone |
אזור זמן. |
TimeZone
מייצג אזור זמן ממסד הנתונים של אזור הזמן IANA.
ייצוג JSON |
---|
{ "id": string, "version": string } |
שדות | |
---|---|
id |
אזור הזמן במסד הנתונים של IANA Time Zone, למשל "America/New_York". |
version |
אופציונלי. מספר גרסה של מסד הנתונים של אזור הזמן ב-IANA, למשל "2019a". |