הדגמה של פעילויות כלל המכשירים בארגון לקילומטר הראשון והאחרון של המשלוחים Fleet Engine Deliveries API. אפשר להשתמש ב-API הזה באמצעות Driver SDK ל-Android ו-iOS, או ישירות באמצעות קריאות HTTP REST או gRPC.
הגדרה ראשונית
אתם מגדירים את Fleet Engine Deliveries API במסוף Google Cloud.
מידע על השלבים שצריך לבצע במסוף ואיך יוצרים אסימון רשת מבוסס JSON להרשאה: אימות והרשאה.
פרטים על השימוש במסוף אפשר למצוא משאבי עזרה במסוף Google Cloud.
אימות ההגדרה
אחרי שיוצרים חשבונות שירות, צריך לוודא שההגדרה הושלמה ואפשר ליצור רכב משלוח. המערכת מאמתת את ההגדרה מיד מבטיח שטיפלת בבעיות נפוצות הקשורות להרשאות שעלולות להתעורר כאשר בתהליך ההגדרה של הפרויקט. יש שתי דרכים לאמת את ההגדרות:
בודקים שני חלקים עיקריים בהגדרה: חתימה על אסימוני הרשאה ושליחה של תקופת ניסיון ליצירת כלי רכב
gcloud
כלי שורת הפקודה. עבור פרטים נוספים זמינים במאמר אימות ההגדרה מותאמת אישית.בדיקת ההגדרה באמצעות סקריפטים לדוגמה של אימות ב-Fleet Engine.
ספריות לקוח
כדי ליהנות מחוויית פיתוח טובה יותר ב-gRPC או ב-REST גולמיים, ספריות לקוח בכמה שפות תכנות נפוצות. עבור ההוראות לקבלת ספריות לקוח עבור אפליקציית השרת שלכם: ספריות לקוח.
בדוגמאות של Java בתיעוד הזה, ההנחה היא שאתם מכירים את gRPC.
מבני נתונים
ב-Fleet Engine Deliveries API נעשה שימוש בשני מבני נתונים כדי לבנות מודל של האיסוף והמסירה. של משלוחים:
- רכב המסירה שמשמש להובלת המשלוח.
- המשימות שקשורות לאיסוף ולמשלוח.
אתם יכולים גם להשתמש במשימות כדי לבנות מודלים של הפסקות עצירה לנהגים ועצירות מתוזמנות. במהלך היום.
רכבי משלוח
רכבי משלוחים מעבירים משלוחים מתחנה ליעד משלוחים, וממיקום איסוף אל התחנה. במקרים מסוימים, הן עשויות גם לשנע משלוח ישירות מנקודת האיסוף אל יעד המשלוח.
שימוש ב-Driver SDK כדי ליצור אובייקט DeliveryVehicle
ב-Fleet Engine
ולשלוח עדכוני מיקום למעקב אחרי משלוחים ואחרי הציפיות.
DeliveryVehicle
אובייקטים.
Tasks
אתם מקצים משימות לפעולות שהרכב מבצע במהלך היום. סוג הפעולה:
- לאיסוף ומשלוחים, צריך להקצות משימות של משלוח.
- בתקופות שבהן הנהגים לא זמינים, כמו הפסקות נדרשות, מקצים משימות של חוסר זמינות.
- למשימות שלא קשורות לנהיגה בתיבות בענן או במיקומים של לקוחות, צריך להקצות משימות מתוזמנות עם עצירה
לכל משימה שמקצים מזהה צריך להיות מזהה ייחודי, אבל לכל משימה אפשר להקצות את אותו מזהה המזהה לצורכי מעקב. כש-Fleet Engine מחשב את זמן ההגעה המשוער לכל משימה, הוא משתמש בכל המשימות ובסדר שבו הם מתכננים לבצע הערכות. מידע נוסף על מזהי משימות זמין כאן הנחיות למזהה המשימה.
כדי ליצור משימות ב-Fleet Engine, אפשר להשתמש במנהל המשימות של Driver SDK.
משימות משלוח
ליצור משימות משלוח גם לאיסוף וגם למסירה של משלוח כוללים את הפרטים הבאים:
- המיקום של האיסוף או של המשלוח.
- מספר או מזהה למעקב.
- זמן השהיה כדי לקחת בחשבון את הזמן הנוסף להשלמת המשימה, לחניה או ללכת למיקום המסירה.
- מזהה משימה ייחודי. כדאי לעיין בהנחיות למזהה המשימה.
אפשר למצוא מידע נוסף בנושאים הבאים:
Android
iOS
משימות של חוסר זמינות
משימות של חוסר זמינות כוללות תקופות שבהן הרכב לא זמין באיסוף עצמי או במסירה, למשל הפסקות לתדלוק ברכב או בנהג הפסקות למנוחה.
יוצרים משימת אי-זמינות עם הפרטים הבאים:
- משך ההפסקה.
- אפשר גם לבחור את מיקום ההפסקה. לא חובה לספק אבל המיקום הזה מספק חלונות זמן הגעה משוערים מדויקים יותר במהלך היום.
אפשר למצוא מידע נוסף בנושאים הבאים:
Android
iOS
משימות עם עצירה מתוזמנת
אפשר ליצור משימות מתוזמנות של עצירות כדי לבנות מודל של התחנות שנדרשות לרכב למשלוחים ליצור. לדוגמה, אפשר ליצור משימה מתוזמנת של הפסקה בין פגישות תחנת איסוף במיקום ספציפי, ללא קשר למשלוחים אחרים או באיסוף עצמי באותו מיקום. אפשר גם ליצור משימות מתוזמנות עם עצירות ביניים קולקציות מתיבות איסוף או אל דגמי העברות של כלי רכב או עוצרת במרכזי שירות ובנקודות שירות.
אפשר למצוא מידע נוסף בנושאים הבאים:
Android
iOS
הנחיות בנושא מזהה המשימה
כשיוצרים את מזהי המשימות, צריך לפעול לפי הנחיות התוכן והפורמט הבאות:
- יצירת מזהי משימות ייחודיים
- אסור לחשוף פרטים אישיים מזהים (PII) או ניקוי נתוני הטקסט.
- צריך להשתמש במחרוזות Unicode חוקיות.
- אפשר להזין עד 64 תווים.
- אין לכלול אף אחד מתווי ASCII הבאים: "/", ":", "\", "?" או "#".
- יש לבצע נירמול בהתאם לטופס הנירמול של Unicode C.
דוגמאות למזהי משימות טובים:
- 566c33d9-2a31-4b6a-9cd4-80ba1a0c643b
- e4708eabcfa39bf2767c9546c9273f747b4626e8cc44e9630d50f6d129013d38
- NTA1YTliYWNkYmViMTI0ZmMzMWFmOWY2NzNkM2Jk
בטבלה הבאה מוצגות דוגמאות למזהי משימות שאינם נתמכים:
מזהי משימות לא נתמכים | סיבה |
---|---|
8/31/2019-20:48-46.70746,-130.10807,-85.17909,61.33680 | מפירה את דרישות המדיניות בנושא פרטים אישיים מזהים (PII) ותווים: פסיקים, נקודות, נקודתיים ולוכסנים. |
JohnDoe-577b484da26f-Cupertino-SantaCruz | מפירה את הדרישות בנושא פרטים אישיים מזהים (PII). |
4R0oXLToF"112 Summer Dr. East Hartford, CT06118"577b484da26f8a | מפירה את דרישות המדיניות בנושא פרטים אישיים מזהים ותווים: רווחים לבנים, פסיקים ומירכאות. מכילה יותר מ-64 תווים. |
מקורות מידע נוספים
כדי לראות את השדות הספציפיים שנכללים בכל נתונים
שלו, אפשר לעיין במשאבי העזרה של ה-API עבור DeliveryVehicle
(gRPC, REST)
ו-Task
(gRPC, REST).
חיי הרכב
האובייקט DeliveryVehicle
מייצג רכב עם אפשרות משלוח מייל ראשון או אחרון.
יוצרים אובייקט DeliveryVehicle
באמצעות:
- מזהה הפרויקט ב-Google Cloud שמכיל את חשבון השירות ששימשו לקריאה לממשקי ה-API של Fleet Engine.
- מזהה רכב בבעלות הלקוח.
צריך להשתמש במזהי רכב ייחודיים לכל רכב. אסור לעשות שימוש חוזר במזהה רכב אלא אם אין משימות פעילות ברכב המקורי.
Fleet Engine מוחק באופן אוטומטי DeliveryVehicle
אובייקטים שלא
עודכן באמצעות UpdateDeliveryVehicle
אחרי שבעה ימים. המומלצים
כדי שרכב זמין ב-Fleet Engine, הם צריכים לעדכן את המיקום שלו.
במרווחי זמן קבועים. עדכונים לרוב השדות האחרים בDeliveryVehicle
הישות גם תאריך את חייה, כל עוד ערך השדה החדש שונה
מהמכשיר הקיים.
כדי לראות אם קיים רכב:
- ביצוע שיחה אל
UpdateDeliveryVehicle
. - אם מופיעה שגיאת NOT_FOUND, צריך להתקשר למספר
CreateDeliveryVehicle
כדי ליצור מחדש את הרכב. אם השיחה מחזירה רכב, הוא עדיין זמין לעדכון.
מאפייני הרכב
הישות DeliveryVehicle
מכילה שדה חוזר של
DeliveryVehicleAttribute
. ה-API של ListDeliveryVehicles
כולל את השדה filter
שדה שיכול להגביל את התוצאות שהוחזרו DeliveryVehicle
ישויות לאלה עם
במאפיינים שצוינו. DeliveryVehicleAttribute
לא משפיע על Fleet Engine
בהתנהגות הניתוב.
אסור לכלול פרטים אישיים מזהים (PII) או מידע רגיש במאפיינים מכיוון ששדה זה עשוי להיות גלוי למשתמשים.
חיי משימה
אפשר ליצור, לעדכן משימות ולשלוח שאילתות ב-Fleet Engine באמצעות ממשקי gRPC או REST של Deliveries.
אובייקט Task
כולל שדה מצב למעקב אחר ההתקדמות שלו דרך
במחזור החיים שלו. הערכים יכולים לעבור מ'פתוח' ל'סגור'. משימות חדשות נוצרות
במצב Open, שמציין ש:
- המשימה עדיין לא הוקצתה לרכב משלוחים.
- רכב המסירה עדיין לא עבר את העצירה שהוקצתה למשימה.
הנחיות למשימה
אפשר להקצות משימה לרכב במצב 'פתוח' רק.
כדי לבטל משימה צריך להסיר אותה מרשימת העצירות. למצב 'סגור' באופן אוטומטי.
כשהרכב של המשימה מסיים את עצירת הרכב במשימה:
מעדכנים את שדה התוצאה של המשימה לאפשרות 'דיווח' או 'נכשל'.
מציינים את חותמת הזמן של האירוע.
לאחר מכן, ספריית ה-JavaScript Fleet Tracking מציינת את תוצאת המשימה סטטוס המשימה יוגדר כ'סגור' באופן אוטומטי. מידע נוסף זמין במאמר הבא: מעקב אחר כלל ה-Fleet באמצעות הספרייה של JavaScript Fleet Tracking
בדומה לכלי רכב, ב-Fleet Engine מוחקים משימות שלא עודכנו אחרי למשך שבעה ימים, ואם תנסו ליצור משימה עם מזהה שכבר קיים, הוא יחזיר שגיאה.
הערה: Fleet Engine לא תומך במחיקה מפורשת של משימה. השירות המשימות יימחקו אוטומטית אחרי שבעה ימים בלי לעדכן אותן. אם אתם רוצים לשמור נתוני משימות למשך יותר מ-7 ימים, עליכם ליישם את היכולת הזו בעצמכם.
מאפייני המשימה
הישות Task
מכילה שדה חוזר של
TaskAttribute
, שיכול להכיל ערך מאחד מ-3 הסוגים: מחרוזת, מספר
ובוליאני. ה-API ListTasks
כולל את השדה filter
שניתן להגביל את ההחזרה.
Task
ישויות עם המאפיינים שצוינו. מאפייני המשימה לא
להשפיע על התנהגות הניתוב של Fleet Engine.
אסור לכלול פרטים אישיים מזהים (PII) או פרטים רגישים אחרים מידע במאפיינים, כי יכול להיות שהמאפיינים האלה גלויים למשתמשים.
ניהול מחזור החיים של רכב ומשימה
תזכורת: המערכת הפנימית שלכם משמשת כמקור המהימן של הנתונים ממשק Fleet Engine Deliveryies מרחיב את הפעילות בשבילכם.
כדי לנהל את מחזורי החיים של הרכב והמשימות במערכת, צריך להשתמש ב-Fleet Engine Deliveries API כדי ליצור כלי רכב, לעדכן אותם ולעקוב אחר הביצועים שלהם, והמשימות שמשויכות אליהם.
במקביל, אפליקציית הנהג מתקשרת ישירות אל Fleet Engine כדי לעדכן את מיקום המכשיר ואת פרטי המסלול. המודל הזה מאפשר ל-Fleet Engine לנהל ביעילות מיקום בזמן אמת. היא שולחת את המיקום ישירות אל ספריית מעקב, שאפשר להשתמש בה כדי לעדכן את הצרכנים בסטטוס של ההזמנה.
לדוגמה, נניח שיש לכם את התרחיש הבא:
- נהג מתקרב לתחנת משלוחים. אפליקציית מנהל ההתקן שולחת את המיקום שלה אל מנוע Fleet.
- Fleet Engine שולח את מיקום המכשיר אל ספריית מעקב, שאפליקציית הצרכן משתמשת בה כדי להתריע בפני הצרכן מידת הקרבה של החבילה.
- אחרי שהנהג משלים את המשלוח, הוא לוחץ על ההודעה 'משלוח נמסר' ביישום של מנהל ההתקן.
- העמודה 'המשלוח נמסר' שולח את המידע למערכת הקצה העורפי שלכם שמבצע את שלבי האימות והאימות העסקיים הנדרשים.
- המערכת שלך מאשרת את המשימה כ דומים ומעדכנת את Fleet Engine באמצעות ממשק API לאספקה.
התרשים הבא ממחיש את התהליכים האלה ברמה כללית. כמו כן מציג את הקשר הסטנדרטי בין המערכת, הלקוח, ו-Fleet Engine.
ניהול אסימוני לקוח
עדכוני מיקום שמקורם באפליקציה של מנהל ההתקן ונשלחים ישירות ל-Fleet Engine נדרשים אסימוני הרשאה. זאת הגישה המומלצת לטיפול בעדכונים מהלקוח ל-Fleet Engine:
יוצרים את האסימון באמצעות משתמש נהיגה לא מהימן ב-Fleet Engine Delivery בחשבון שירות.
צריך לספק לאפליקציית מנהל ההתקן עם אסימון בהיקף מוגבל. ההיקף הזה מאפשרת לעדכן רק את מיקום המכשיר ב-Fleet Engine.
הגישה הזו מבטיחה ששיחות שמקורן במכשירים ניידים, יש להביא בחשבון בסביבות עם אמון נמוך--פועלים לפי העיקרון של הרשאות מינימליות.
תפקידים אחרים של חשבון שירות
אם במקום זאת ברצונך לאשר לאפליקציות לנהגים לבצע ב-Fleet Engine מתבצעים עדכונים, מעבר לאלה שמוגבלים לתפקיד 'נהג/ת לא מהימן'. למשל, כדי לבצע עדכונים מסוימים במשימות, תוכלו להשתמש בתפקיד 'נהג מהימן'. עבור מידע על מודל שמשתמש בתפקיד 'נהג מהימן': דגם של מנהל התקן מהימן.
מידע נוסף על השימושים בתפקידי התקנים מהימנים או לא מהימנים זמין במאמר הגדרת פרויקט בענן.
בניית מודל של יום עבודה
בטבלה הבאה מתואר איך יום העבודה של נהגים שנוסעים מייל ראשון או אחרון. יכול להיראות כמו חברת משלוחים ולוגיסטיקה. החברה שלך עשויה שונים בפרטים עדיין, אבל אפשר לראות איך אפשר לבנות מודל של יום עבודה.
שעה | פעילות | בניית מודלים |
---|---|---|
תוך 24 שעות מתחילת היום | הסדרן מקצה משלוחים לרכבים או למסלולים למשלוחים. | אפשר ליצור משימות למשלוחי משלוחים, לאיסוף, להפסקות ולאיסוף עצמי
אחרים ב-Fleet Engine. לדוגמה, אפשר ליצור
משימת איסוף משלוח,
משימה של מסירת משלוחים,
חוסר זמינות מתוזמן, או
עצירה מתוזמנת.
הקצאת משימות לרכב אחרי קבוצת חבילות למשלוח והסדר שבו יש לשלוח אותן הם סופיים. |
תחילת היום | הנהג מתחיל את היום בתחנה בכניסה לאפליקציית Drive. | מפעילים את Delivery Driver API. יוצרים את הרכב למשלוח ב-Fleet Engine לפי הצורך. |
נהג טוען את המשלוחים לרכב המשלוחים וסורק את המשלוחים. | אם משימות של משלוחים לא נוצרו מראש, ליצור משימות של משלוחי משלוח בזמן הסריקה. | |
הנהג/ת מאשר/ת את הסדר של המשימות לביצוע. | אם הם לא נוצרו מראש, אפשר ליצור אותם משימות לאיסוף משלוחים, חוסר זמינות מתוזמן, וגם תחנות מתוכננות. | |
הנהג עוזב את התחנה ומתחייב למספר המשימות הבא הושלמו. | להקצות את כל המשימות או קבוצת משנה של משימות לרכב על ידי הגדרת סדר ההשלמה שלהם. | |
הנהג מבצע משלוח. | אחרי שמגיעים לתחנת המשלוח, צריך לבצע פעולות שקשורות לכלי רכב שמגיע בעצירה. אחרי מסירת המשלוח, סוגרים את משימת העברה, ואם רוצים, סטטוס משלוח של חנות ומטא-נתונים נוספים. אחרי שתשלימו את כל המשימות באותה תחנה ולפני כן להתחיל לנסוע לתחנה הבאה, לבצע פעולות שקשורות אל הרכב עומד בעצירה וכלי הרכב בדרך לתחנה הבאה. | |
הנהג/ת פוגש/ת רכב הזנה כדי להעביר משלוחים נוספים לרכב המשלוחים. | נקודת המפגש למעבר בין כלי רכב עם אספקת מזון לכלי משלוח
צריך ליצור מודל של עצירה מתוזמנת.
אחרי העברה וסריקה של המשלוחים, יוצרים משימות מסירה אם הם עדיין לא נוצרו. מעדכנים את השלמת המשימה לסדר באמצעות הקצאת משימות לרכב ולעדכן את סדר המשימות. |
|
הנהג מקבל הודעה על בקשת איסוף. | אחרי שתאשרו את בקשת האיסוף, ליצור משימה לאיסוף משלוח. מעדכנים את ביצוע המשימה לסדר באמצעות הקצאת משימות לרכב ולעדכן את סדר המשימות. | |
צהריים | הנהג יוצא להפסקת צהריים. | אם מיקום משויך למשימה של חוסר זמינות, צריך להתייחס אליו כמו
בכל משימה אחרת. ביצוע פעולות שקשורות לרכב
הגעה לעצירה,
הרכב עומד בעצירה
וכלי הרכב בדרך לתחנה הבאה.
אחרת, לא יהיה צורך בפעולה נוספת עד סיום ההפסקה. מסירים את המשימה על ידי אישור המשימות הבאות ואת המשימות שנותרו, וגם לעדכן את סדר המשימות. |
נהג אוסף משלוח. | התכנון הזה הוא בדיוק כמו תחנת משלוח. ביצוע פעולות שקשורות לכלי רכב שמגיע בעצירה ולסגור משימה, ואם רוצים, אחסון של סטטוס המשלוח ומטא-פרטים נוספים. אחרי שמשלימים את כל המשימות בעצירה ולפני תחילת הנסיעה עד העצירה הבאה, ביצוע פעולות שקשורות לכלי רכב בהשלמה של עצירה וכלי הרכב בדרך לתחנה הבאה. הערה: כדי להבטיח שהחיוב יהיה נכון, לכל איסוףים חייב להיות משימת מסירה. אם האיסוף מיועד למשלוח למיקום אחר של הנהג באותו יום, אנחנו ממליצים ליצור מודל של משימת ההעברה כך כל משימת העברה אחרת במסלול. אם הנהג מביא את האיסוף בחזרה לתחנה, מומלץ ליצור משימת משלוח בתחנה היעד. | |
הנהג/ת עוצר/ת את המשלוח/ים כדי לאסוף את המשלוחים מתיבת הדואר הנכנס. | המודל הזה מחושב לפי מודל של כל תחנת איסוף אחרת. ביצוע פעולות שקשורות לכלי רכב שמגיע בעצירה וסגירת משימה. לאחר השלמת התהליך את כל המשימות שבעצירה ומתחילים לנסוע לתחנה הבאה, ביצוע פעולות שקשורות לכלי רכב עוצר עצירה וכלי הרכב בדרך לתחנה הבאה. | |
הנהג מקבל הודעה על כך שמשלוח מופנה למיקום חלופי. | צריך להגדיר את הסטטוס של משימת מסירת המשלוח המקורית ל-הושלם וליצור אירוע חדש משימה לאספקת משלוח למיקום המשלוח החדש. לקבלת מידע נוסף, למידע נוסף, ראו ניתוב מחדש של משלוח. | |
הנהג ניסה למסור חבילה אבל לא ניתן היה למסור אותה. | המודל הזה מחושב באופן דומה לעצירת מסירה מוצלחת, כמשימה שהושלמה. ביצוע פעולות שקשורות אל כלי רכב שמגיע בעצירה. אחרי אם לא מסירת את המשלוח, לסגור את המשימה, ואם רוצים, סטטוס משלוח של חנות ומטא-נתונים נוספים. אחרי שמשלימים את כל המשימות בעצירה ולפני תחילת הנסיעה עד העצירה הבאה, ביצוע פעולות שקשורות לכלי רכב בהשלמה של עצירה וכלי הרכב בדרך לתחנה הבאה. | |
הנהג/ת קיבל/ה הודעה לשמור (לא למסור) משלוח. | אחרי שההתראה תתקבל ותאושר, להגדיר את סטטוס המשימה כ'הושלם'. | |
הנהג/ת קיבל/ה הודעה למסור משלוח מסוים בהמשך, וההזמנה משתנה בהתאם להתחייבות. | מעדכנים את סדר המשימות. | |
הנהג בוחר לשלוח משלוח שלא היה תקין. | מעדכנים את סדר המשימות ואז ממשיכים כרגיל. | |
הנהג/ת שולח/ת כמה משלוחים למיקום אחד. | המודל הזה מחושב באופן דומה למועד של עצירת משלוח אחת. אחרי שמגיעים לתחנה, מבצעים פעולות שקשורות כלי רכב שמגיע בעצירה. אחרי מסירת כל משלוח, צריך לסגור כל משימה ובאופן אופציונלי, אפשר לציין גם סטטוס משלוח בחנות ומטא-נתונים נוספים. אחרי שמשלימים את כל המשימות בעצירה ולפני תחילת הנסיעה עד העצירה הבאה, ביצוע פעולות שקשורות לכלי רכב בהשלמה של עצירה וכלי הרכב בדרך לתחנה הבאה. | |
סוף יום | הנהג חוזר לתחנת הרכבת. | אם הנהג חוזר לתחנת היעד והמשלוחים נאספים בזמן עליכם גם ליצור ולסגור כל חבילה כמשימת מסירה כדי לוודא שהחיוב נכון. אפשר לעשות זאת באמצעות בניית מודל של המאגר כמו תחנת משלוח אחרת. אם התחנה לא משמשת כעצירת משלוח, עדיין יכול להיות שתהיה לך אפשרות לעשות זאת לבנות את התחנה כעצירה מתוזמנת. יצירת מודל של התחנה מאפשרת לנהגים לראות את המסלול בחזרה לתחנת הרכבת ולהציג מידע על הזמן המשוער שלהם לקראת ההגעה. |
איך פועלים עדכוני המיקום
כדי ליהנות מהביצועים הטובים ביותר עם Fleet Engine, מומלץ לספק סטרימינג של רכב עדכוני מיקום. אפשר לספק את העדכונים האלה באחת מהדרכים הבאות:
- שימוש ב-Driver SDK – Android, iOS -- האפשרות הפשוטה ביותר.
- שימוש בקוד מותאם אישית – שימושי אם מיקומים ממסר דרך הקצה העורפי, או אם אתם משתמשים במכשירים אחרים שהם לא Android או iOS.
ללא קשר לאופן שבו תספקו עדכונים של מיקום הרכבים, הקצה העורפי שלכם הוא אחראי לעדכון Fleet Engine כשרכב מסירה בדרך לעצירה (כולל התחנה) ובזמן הגעה לעצירה. Fleet Engine לא מזהה את האירועים האלה באופן אוטומטי.
תחנות משלוחים ומקומות למשלוחים
עצירת רכב היא המקום שבו רכב משלוח משלים משימת משלוח או משימה אחרת. היא נקודת גישה כמו תחנת עגינה או מיקום שנתפס בכביש.
יעד המשלוח הוא המיקום שאליו נשלח המשלוח או לאסוף אותו. יכול להיות שיהיה צריך הליכה מסוימת כדי להגיע ליעד המשלוח וממנו מתחנת הרכב.
לדוגמה, כשנהג שולח משלוח לחנות בקניון, רכב המשלוחים עוצר בחניון של מרכז הקניות ליד הכניסה הקרובה ביותר לחנות. זוהי העצירה של הרכב. הנהג/ת ואז הולך מתחנת הרכב אל המיקום בתוך הקניון שהחנות ממוקמת בו. זה יעד המשלוח.
כדי ליהנות מחוויית המעקב הטובה ביותר אחרי המשלוח עבור המשתמשים, כדאי לחשוב איך משימות משלוח מוקצות לתחנות של רכבים, וצריך לזכור שמספר שאר עצירות הרכב למשימות המשלוח מדווחות למשתמש כדי לעזור לו לראות את התקדמות המשלוח.
לדוגמה, אם נהג מבצע הרבה משלוחים לבניין משרדים אחד, כדאי להקצות את כל משימות המסירה לעצירה אחת ברכב. אם המיקום שכל משימת מסירה מוקצית לתחנת רכב משלה, המשלוח שלכם חוויית המעקב תועיל פחות למשתמשים שלך, כי המעקב זמינה אחרי שהרכב נמצא בטווח של מספר מוגבל של תחנות לפני היעד שלו. אם יש לכם הרבה עצירות ביניים בזמן קצר, לא בטוח למשתמש נדרש זמן כדי לעקוב אחר התקדמות המסירה.
שימוש בערכות SDK לנייד
לפני שמבצעים קריאות ל-Driver SDK, חשוב לאתחל אותו.
אתחול ממשק ה-API של מנהל התקן המסירה
לפני שמפעילים את Delivery Driver API ב-Driver SDK, צריך לוודא כדי לאתחל את ה-SDK לניווט. לאחר מכן מאתחלים את Delivery Driver API כפי שמוצג בדוגמה הבאה:
static final String PROVIDER_ID = "provider-1234";
static final String VEHICLE_ID = "vehicle-8241890";
NavigationApi.getNavigator(
this, // Activity.
new NavigatorListener() {
@Override
public void onNavigatorReady(Navigator navigator) {
DeliveryDriverApi.createInstance(DriverContext.builder(getApplication())
.setNavigator(navigator)
.setProviderId(PROVIDER_ID)
.setVehicleId(VEHICLE_ID)
.setAuthTokenFactory((context) -> "JWT") // AuthTokenFactory returns JWT for call context.
.setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(getApplication()))
.setNavigationTransactionRecorder(NavigationApi.getNavigationTransactionRecorder(getApplication()))
.setStatusListener((statusLevel,statusCode,statusMsg) -> // Optional, surfaces polling errors.
Log.d("TAG", String.format("New status update. %s, %s, %s", statusLevel, statusCode, statusMsg)))
.build));
}
@Override
public void onError(int errorCode) {
Log.e("TAG", String.format("Error loading Navigator instance: %s", errorCode));
}
});
תרחישים לדוגמה
בקטע הזה נסביר איך להשתמש ב-Deliveries API כדי לבנות מודלים של תרחישים נפוצים לדוגמה.
מזהי ישויות ייחודיים
הפורמט והערך של מזהי הישויות הייחודיים שמשמשים בקריאות REST הם אטומים ל-Fleet Engine. מומלץ להימנע משימוש בהוספה אוטומטית של מזהים, ולוודא המזהה לא מכיל פרטים אישיים מזהים (PII), כמו מספר הטלפון של הנהג.
יצירת רכב
אפשר ליצור כלי רכב מתוך Driver SDK או מסביבת שרת באמצעות gRPC או REST.
gRPC
כדי ליצור רכב חדש, צריך לבצע קריאה של CreateDeliveryVehicle
ל-Fleet Engine.
צריך להשתמש באובייקט CreateDeliveryVehicleRequest
כדי להגדיר את המאפיינים של
רכב המשלוחים החדש. שימו לב שכל ערך שצוין בשדה Name
המערכת מתעלמת מההנחיות של API עבור מזהים שצוינו על ידי המשתמש.
עליכם להשתמש בשדה DeliveryVehicleId
כדי להגדיר את מזהה הרכב.
כשיוצרים DeliveryVehicle
, אפשר לציין את השדות הבאים:
- מאפיינים
- LastLocation
- סוג
לא מגדירים שדות אחרים. אם כן, Fleet Engine יחזיר שגיאה
מאחר שהשדות האלה הם לקריאה בלבד או שאפשר לעדכן אותם רק באמצעות קריאה ל
UpdateDeliveryVehicle
כדי ליצור רכב בלי להגדיר שדות אופציונליים, אפשר להשאיר את
השדה DeliveryVehicle
לא הוגדר בCreateDeliveryVehicleRequest
.
הדוגמה הבאה מראה איך להשתמש ספריית Java gRPC כדי ליצור כלי רכב:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890"; // Avoid auto-incrementing IDs.
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String parent = "providers/" + PROJECT_ID;
DeliveryVehicle vehicle = DeliveryVehicle.newBuilder()
.addAttributes(DeliveryVehicleAttribute.newBuilder()
.setKey("route_number").setValue("1")) // Opaque to the Fleet Engine
.build();
// Vehicle request
CreateDeliveryVehicleRequest createVehicleRequest =
CreateDeliveryVehicleRequest.newBuilder() // No need for the header
.setParent(parent)
.setDeliveryVehicleId(VEHICLE_ID) // Vehicle ID assigned by the Provider
.setDeliveryVehicle(vehicle)
.build();
// Error handling
// If Fleet Engine does not have vehicle with that ID and the credentials of the
// requestor pass, the service creates the vehicle successfully.
try {
DeliveryVehicle createdVehicle =
deliveryService.createDeliveryVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
כדי ליצור רכב מסביבת שרת, צריך לבצע קריאה ל-HTTP REST
אל CreateDeliveryVehicle
:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles?deliveryVehicleId=<id>
<id> הוא מזהה ייחודי של רכב משלוח בארגון שלכם.
כותרת הבקשה חייבת להכיל שדה Authorization עם הערך האסימון <token>, כאשר <token> הוא אסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
גוף ה-POST מייצג את הישות DeliveryVehicle
שיש ליצור. אפשר לציין
השדות האופציונליים הבאים:
- מאפיינים
- lastLocation
- סוג
פקודת curl
לדוגמה:
# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"attributes": [{"key": "model", "value": "sedan"}],
"lastLocation": {"location": {"latitude": 12.1, "longitude": 14.5}}
}
EOM
בכל הנחיות API, המערכת של Fleet Engine מתעלם מהשדה name
של הישות DeliveryVehicle
לגבי מזהים שצוינו על ידי המשתמש.
לא מגדירים שדות אחרים. אם כן, Fleet Engine יחזיר שגיאה
מאחר שהשדות האלה הם לקריאה בלבד או שאפשר לעדכן אותם רק באמצעות קריאה ל
UpdateDeliveryVehicle
כדי ליצור רכב בלי להגדיר שדות, צריך להשאיר את גוף ה-POST
הבקשה ריקה. לאחר מכן, הרכב החדש שולף מזהה רכב
deliveryVehicleId
בכתובת ה-URL של POST.
פקודת curl
לדוגמה:
# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}"
יצירת משימה לאיסוף משלוח
אפשר ליצור משימה לאיסוף משלוח דרך SDK של מנהל התקן או מסביבת שרת עם gRPC או REST.
gRPC
הדוגמה הבאה מראה איך להשתמש ספריית Java gRPC כדי ליצור משימה לאיסוף משלוח:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.PICKUP)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
.addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
.addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have a task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
כדי ליצור משימה של איסוף משלוח מסביבת שרת, צריך לבצע קריאה ל-HTTP REST
אל CreateTask
:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> הוא מזהה ייחודי של המשימה. זה לא יכול להיות מספר המעקב למשלוח. אם אין מזהי משימות במערכת, אפשר ליצור מזהה ייחודי אוניברסלי (UUID).
כותרת הבקשה חייבת להכיל שדה Authorization עם הערך האסימון <token>, כאשר <token> הוא אסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
גוף הבקשה חייב להכיל ישות Task
:
שדות חובה:
שדה ערך סוג Type.PICKUP הסמוי הסופי State.OPEN trackingId המספר או המזהה שמשמשים אותך למעקב אחרי משלוח. plannedLocation המיקום שבו צריך להשלים את המשימה, במקרה הזה המיקום לאיסוף המשלוח. taskDuration משך הזמן הצפוי (בשניות) הנדרש לאיסוף המשלוח. במיקום האיסוף. שדות אופציונליים:
שדה ערך targetTimeWindow חלון הזמן שבמהלכו צריך להשלים את המשימה. זה לא משפיעה על התנהגות הניתוב. מאפיינים רשימה של מאפיינים מותאמים אישית למשימה. לכל מאפיין צריך להיות מפתח ייחודי.
המערכת מתעלמת מכל שאר השדות בישות במהלך היצירה. זריקה של מנוע Fleet
חריגים אם הבקשה כוללת deliveryVehicleId
שהוקצה. אתם מקצים
משימות באמצעות UpdateDeliveryVehicleRequest
. מידע נוסף זמין במאמר הבא:
מקצים משימות לרכב ו-UpdateDeliveryVehicleRequest.
פקודת curl
לדוגמה:
# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "PICKUP",
"state": "OPEN",
"trackingId": "${TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s",
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
יצירת משימה של מסירת משלוח
יוצרים משימה של שליחת משלוח דרך SDK של מנהל התקן או מסביבת שרת עם gRPC או REST.
gRPC
הדוגמה הבאה מראה איך להשתמש ספריית Java gRPC כדי ליצור משימה של מסירת משלוח:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.DELIVERY)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
.addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
.addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
כדי ליצור משימת מסירת משלוח מסביבת שרת באמצעות gRPC או REST, צריך ליצור קריאת HTTP REST
אל CreateTask
:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> הוא מזהה ייחודי של המשימה. זה לא יכול להיות מספר המעקב למשלוח. אם אין מזהי משימות במערכת, אפשר ליצור מזהה ייחודי אוניברסלי (UUID).
כותרת הבקשה חייבת להכיל שדה Authorization עם הערך האסימון <token>, כאשר <token> הוא אסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
גוף הבקשה חייב להכיל ישות Task
:
שדות חובה:
שדה ערך סוג Type.DELIVERY הסמוי הסופי State.OPEN trackingId המספר או המזהה שמשמשים אותך למעקב אחרי משלוח. plannedLocation המיקום שבו צריך להשלים את המשימה, במקרה הזה המיקום של המשלוח. taskDuration הזמן הצפוי בשניות עד למסירת המשלוח במיקום המשלוח. שדות אופציונליים:
שדה ערך targetTimeWindow חלון הזמן שבמהלכו צריך להשלים את המשימה. זה לא משפיעה על התנהגות הניתוב. מאפיינים רשימה של מאפיינים מותאמים אישית למשימה. לכל מאפיין צריך להיות מפתח ייחודי.
המערכת מתעלמת מכל שאר השדות בישות במהלך היצירה. זריקה של מנוע Fleet
חריגים אם הבקשה כוללת deliveryVehicleId שהוקצה. אתם מקצים
משימות באמצעות UpdateDeliveryVehicleRequest
. מידע נוסף זמין במאמר הבא:
מקצים משימות לרכב ו-UpdateDeliveryVehicleRequest.
פקודת curl
לדוגמה:
# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "DELIVERY",
"state": "OPEN",
"trackingId": "${TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s",
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
יצירת משימות באצווה
אפשר ליצור קבוצת משימות מסביבת שרת באמצעות gRPC או REST.
gRPC
הדוגמה הבאה מראה איך להשתמש ספריית Java gRPC ליצור שתי משימות, אחת למשלוח והשנייה לאיסוף באותו מקום. location:
static final String PROJECT_ID = "my-delivery-co-gcp-project"; DeliveryServiceBlockingStub deliveryService = DeliveryServiceGrpc.newBlockingStub(channel); // Delivery Task settings Task deliveryTask = Task.newBuilder() .setType(Task.Type.DELIVERY) .setState(Task.State.OPEN) .setTrackingId("delivery-tracking-id") .setPlannedLocation( // Grand Indonesia East Mall LocationInfo.newBuilder().setPoint( LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826))) .setTaskDuration( Duration.newBuilder().setSeconds(2 * 60)) .build(); // Delivery Task request CreateTaskRequest createDeliveryTaskRequest = CreateTaskRequest.newBuilder() // No need for the header or parent fields .setTaskId("task-8312508") // Task ID assigned by the Provider .setTask(deliveryTask) // Initial state .build(); // Pickup Task settings Task pickupTask = Task.newBuilder() .setType(Task.Type.PICKUP) .setState(Task.State.OPEN) .setTrackingId("pickup-tracking-id") .setPlannedLocation( // Grand Indonesia East Mall LocationInfo.newBuilder().setPoint( LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826))) .setTaskDuration( Duration.newBuilder().setSeconds(2 * 60)) .build(); // Pickup Task request CreateTaskRequest createPickupTaskRequest = CreateTaskRequest.newBuilder() // No need for the header or parent fields .setTaskId("task-8241890") // Task ID assigned by the Provider .setTask(pickupTask) // Initial state .build(); // Batch Create Tasks settings String parent = "providers/" + PROJECT_ID; // Batch Create Tasks request BatchCreateTasksRequest batchCreateTasksRequest = BatchCreateTasksRequest.newBuilder() .setParent(parent) .addRequests(createDeliveryTaskRequest) .addRequests(createPickupTaskRequest) .build(); // Error handling // If Fleet Engine does not have any task(s) with these task ID(s) and the // credentials of the requestor pass, the service creates the task(s) // successfully. try { BatchCreateTasksResponse createdTasks = deliveryService.batchCreateTasks( batchCreateTasksRequest); } catch (StatusRuntimeException e) { Status s = e.getStatus(); switch (s.getCode()) { case ALREADY_EXISTS: break; case PERMISSION_DENIED: break; } return; }
REST
כדי ליצור משימה של משלוחים ואיסוף עצמי מסביבת שרת, צריך להזין
קריאה ל-BatchCreateTasks
ב-REST ב-HTTP:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks:batchCreate
כותרת הבקשה חייבת להכיל שדה הרשאה עם הערך הנושא <token>, כאשר <token> הוא האסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
גוף הבקשה חייב להכיל ישות BatchCreateTasksRequest
:
שדות חובה:
שדה ערך בקשות מערך< CreateTasksRequest
>שדות אופציונליים:
שדה ערך כותרת `DeliveryRequestHeader`
כל רכיב CreateTasksRequest
ב-requests
חייב לעבור אותו אימות
כללי כבקשת CreateTask
, מלבד העובדה שparent
ו-header
הם אופציונליים. אם מגדירים אותן, הן צריכות להיות זהות ל-
השדות המתאימים ברמה העליונה BatchCreateTasksRequest
. צפייה
ליצור משימה לאיסוף משלוח.
יצירת משימה של מסירת משלוח
כללי אימות ספציפיים לכל אחד מהם.
מידע נוסף זמין במסמכי העזרה של ה-API עבור BatchCreateTasks
.
(gRPC, REST).
פקודת curl
לדוגמה:
# Set $JWT, $PROJECT_ID, $DELIVERY_TRACKING_ID, $DELIVERY_TASK_ID,
# $PICKUP_TRACKING_ID, and $PICKUP_TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks:batchCreate" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"requests" : [
{
"taskId": "${DELIVERY_TASK_ID}",
"task" : {
"type": "DELIVERY",
"state": "OPEN",
"trackingId": "${DELIVERY_TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s"
}
},
{
"taskId": "${PICKUP_TASK_ID}",
"task" : {
"type": "PICKUP",
"state": "OPEN",
"trackingId": "${PICKUP_TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s"
}
}
]
}
EOM
חוסר זמינות מתוזמן
אפשר ליצור משימה שמציינת חוסר זמינות (לדוגמה, עבור הנהג/ת הפסקות או תדלוק Driver SDK, או מסביבת שרת עם gRPC או REST. משימה מתוזמנת מסוג אי-זמינות לא יכולה לכלול מזהה לצורכי מעקב. אפשר גם לציין מיקום.
gRPC
הדוגמה הבאה מראה איך להשתמש ספריית Java gRPC כדי ליצור משימת אי-זמינות:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.UNAVAILABLE)
.setState(Task.State.OPEN)
.setTaskDuration(
Duration.newBuilder().setSeconds(60 * 60)) // 1hr break
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
כדי ליצור משימת unavailability מסביבת שרת, צריך לבצע קריאה ל-HTTP REST
אל CreateTask
:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> הוא מזהה ייחודי של המשימה. אחרת אם יש במערכת מזהי משימה, אפשר ליצור מזהה משימה מזהה (UUID).
כותרת הבקשה חייבת להכיל שדה Authorization עם הערך האסימון <token>, כאשר <token> הוא אסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
גוף הבקשה חייב להכיל ישות Task
:
שדות חובה:
שדה ערך סוג Type.UNAVAILABLE הסמוי הסופי State.OPEN taskDuration משך ההפסקה בשניות. שדות אופציונליים:
שדה ערך plannedLocation מיקום ההפסקה, אם היא צריכה להתבצע במיקום ספציפי.
המערכת מתעלמת מכל שאר השדות בישות במהלך היצירה. זריקה של מנוע Fleet
חריגים אם הבקשה כוללת deliveryVehicleId שהוקצה. אתם מקצים
משימות באמצעות UpdateDeliveryVehicleRequest
. מידע נוסף זמין במאמר הבא:
מקצים משימות לרכב ו-UpdateDeliveryVehicleRequest.
פקודת curl
לדוגמה:
# Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "UNAVAILABLE",
"state": "OPEN",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "300s"
}
EOM
תחנות מתוכננות
אפשר ליצור משימה של עצירה מתוזמנת Driver SDK, או מסביבת שרת עם gRPC או REST. משימה של עצירה מתוזמנת לא יכולה לכלול מעקב ID.
gRPC
הדוגמה הבאה מראה איך להשתמש ספריית Java gRPC כדי ליצור משימה של עצירה מתוזמנת:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.SCHEDULED_STOP)
.setState(Task.State.OPEN)
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent)
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTrip(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
כדי ליצור משימה של עצירה מתוזמנת מסביבת שרת, צריך ליצור קריאה ל-HTTP REST
אל CreateTask
:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> הוא מזהה ייחודי של המשימה. אם אין לך במערכת שלכם, אפשר ליצור מזהה ייחודי אוניברסלי (UUID).
כותרת הבקשה חייבת להכיל שדה Authorization עם הערך האסימון <token>, כאשר <token> הוא אסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
גוף הבקשה חייב להכיל ישות Task
:
שדות חובה:
שדה ערך סוג Type.SCHEDULED_STOP הסמוי הסופי State.OPEN plannedLocation מיקום העצירה. taskDuration משך העצירה הצפוי בשניות. שדות אופציונליים:
- ללא
המערכת מתעלמת מכל שאר השדות בישות במהלך היצירה. זריקה של מנוע Fleet
חריגים אם הבקשה כוללת deliveryVehicleId שהוקצה. אתם מקצים
משימות באמצעות UpdateDeliveryVehicleRequest
. מידע נוסף זמין במאמר הבא:
מקצים משימות לרכב ו-UpdateDeliveryVehicleRequest.
פקודת curl
לדוגמה:
# Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "SCHEDULED_STOP",
"state": "OPEN",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "600s"
}
EOM
הגדרת חלון זמן ליעד
חלון הזמן ליעד הוא TimeWindow שבמהלכם צריך להשלים את המשימה. לדוגמה, אם תמסור את חלון זמן האספקה אל נמעני המסירה, אפשר להשתמש בזמן היעד של המשימה כדי לתעד את חלון הזמן הזה וליצור התראות או לנתח את הנתונים לאחר הנסיעה. הביצועים באמצעות השדה.
חלון הזמן ליעד מורכב משעת התחלה ומשעת סיום, ואפשר להגדיר אותו בכל סוג של משימה. חלון הזמן ליעד לא משפיע על המסלול או התנהגות המשתמשים.
gRPC
הדוגמה הבאה מראה איך להשתמש ספריית Java gRPC כדי להגדיר חלון זמן למשימה:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("targetTimeWindow"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
כדי להגדיר חלון זמן למשימה באמצעות HTTP, קוראים לפונקציה UpdateTask
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow`
<id> הוא מזהה ייחודי של המשימה.
כותרת הבקשה חייבת להכיל שדה Authorization עם הערך האסימון <token>, כאשר <token> הוא אסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
גוף הבקשה חייב להכיל ישות Task
:
שדות חובה:
שדה ערך targetTimeWindow חלון הזמן שבמהלכו צריך להשלים את המשימה. ההגדרה הזו אין השפעה על התנהגות הניתוב שדות אופציונליים:
- ללא
המערכת תתעלם מכל השדות האחרים בישות במהלך העדכון.
פקודת curl
לדוגמה:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=targetTimeWindow" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
קביעת הגדרות חשיפה למעקב אחר משימות
החשיפה של הנתונים בספריית 'מעקב אחר משלוחים' והנתונים האלה
אפשר לשלוט בחזרה משיחה אל GetTaskTrackingInfo
בכל משימה
באמצעות הגדרה
TaskTrackingViewConfig
במשימה. צפייה
משימות פעילות ברכב
אפשר לקבל מידע נוסף. ניתן לעשות זאת במהלך יצירה או עדכון של
למשימה הזו. דוגמה לעדכון המשימה באמצעות ההגדרה הזאת:
gRPC
הדוגמה הבאה מראה איך להשתמש ספריית Java gRPC כדי לקבוע את התצורה של תצוגת מעקב המשימה:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTaskTrackingViewConfig(
TaskTrackingViewConfig.newBuilder()
.setRoutePolylinePointsVisibility(
VisibilityOption.newBuilder().setRemainingStopCountThreshold(3))
.setEstimatedArrivalTimeVisibility(
VisibilityOption.newBuilder().remainingDrivingDistanceMetersThreshold(5000))
.setRemainingStopCountVisibility(
VisibilityOption.newBuilder().setNever(true)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("taskTrackingViewConfig"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
כדי להגדיר את חלון התצורה של תצוגת המעקב באמצעות HTTP, קוראים לפונקציה UpdateTask
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskTrackingViewConfig`
<id> הוא מזהה ייחודי של המשימה.
כותרת הבקשה חייבת להכיל שדה Authorization עם הערך האסימון <token>, כאשר <token> הוא אסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
גוף הבקשה חייב להכיל ישות Task
:
שדות חובה:
שדה ערך taskTrackingViewConfig התצורה של מעקב אחר משימות שמציינת אילו רכיבי נתונים גלויות למשתמשי הקצה ובאילו נסיבות. שדות אופציונליים:
- ללא
המערכת תתעלם מכל השדות האחרים בישות במהלך העדכון.
פקודת curl
לדוגמה:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskTrackingViewConfig" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"taskTrackingViewConfig": {
"routePolylinePointsVisibility": {
"remainingStopCountThreshold": 3
},
"estimatedArrivalTimeVisibility": {
"remainingDrivingDistanceMetersThreshold": 5000
},
"remainingStopCountVisibility": {
"never": true
}
}
}
EOM
הקצאת משימות לרכב
אתם מקצים משימות לרכב משלוחים על ידי עדכון סדר המשימות לרכב. סדר המשימות של רכב נקבע מהרשימה של עצירות ברכב, וניתן להקצות משימה אחת או יותר לכל עצירה ברכב. פרטים נוספים זמינים במאמר מעדכנים את סדר המשימות.
כדי לשנות משלוח מרכב אחד לרכב אחר, צריך לסגור את המשימה המקורית ואז ליצור אותו מחדש לפני שמקצים לו את הרכב החדש. אם מעדכנים את המשימה בתהליך ההגדרה של משימה שכבר הוקצתה תקבלו את הודעת השגיאה הזאת ברכב אחר.
עדכון סדר המשימות
אתם יכולים לעדכן את המשימות של ההזמנה שהוקצו לרכב, מתבצעות מכל אחת מהאפשרויות הבאות: ה Driver SDK, או בסביבת השרת. אל תשתמשו בשתי השיטות כדי להימנע ושומרים על מקור מהימן אחד.
כשמעדכנים את סדר המשימות של רכב, מתבצעות גם הפעולות הבאות:
- הקצאת משימות חדשות לרכב.
- הלחצן סוגר את כל המשימות שהוקצו לרכב בעבר, אבל לא הוקצו לו בסדר המעודכן.
כדי לשנות משלוח מרכב אחד לאחר, לסגור את המשימה המקורית ואז ליצור אותו מחדש לפני שמקצים לו את הרכב החדש. אם מעדכנים את המשימה בתהליך ההגדרה של משימה שכבר הוקצתה תקבלו את הודעת השגיאה הזאת ברכב אחר.
אתם יכולים לעדכן את סדר המשימות מתי שתרצו.
gRPC
הדוגמה הבאה מראה איך להשתמש ספריית Java gRPC כדי לעדכן את סדר המשימות ברכב:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
static final String TASK1_ID = "task-756390";
static final String TASK2_ID = "task-849263";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 1st stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.NEW)))
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
כדי לעדכן את סדר המשימות ברכב מסביבת שרת, צריך לבצע הפעלת HTTP REST
אל UpdateDeliveryVehicle
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id> הוא מזהה ייחודי של רכב משלוח בארגון שלך שעבורו אתם מתכוונים לעדכן את סדר המשימות. זה המזהה שציינת כשיצרת את הרכב.
כותרת הבקשה חייבת להכיל שדה Authorization עם הערך האסימון <token>, כאשר <token> הוא אסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
גוף הבקשה חייב להכיל ישות DeliveryVehicle
:
שדות חובה:
שדה ערך remainingVehicleJourneySegments רשימה של מקטעי המסלול למשימות לפי הסדר שבו צריך לבצע אותן. המשימה הראשונה ברשימה מבוצעת ראשונה. remainingVehicleJourneySegments[i].stop העצירה של משימה i ברשימה. remainingVehicleJourneySegments[i].stop.plannedLocation המיקום המתוכנן של העצירה. remainingVehicleJourneySegments[i].stop.tasks רשימת משימות שצריך לבצע בתחנה הזו של הרכב. remainingVehicleJourneySegments[i].stop.state State.NEW שדות אופציונליים:
- ללא
המערכת תתעלם מכל השדות האחרים בישות במהלך העדכון.
פקודת curl
לדוגמה:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
הרכב בדרך לתחנה הבאה
חובה להודיע למנוע בכלל בעת יציאה של כלי רכב מעצירה או בהפעלה ניווט. אפשר להודיע ל-Fleet Engine דרך Driver SDK, או מסביבת שרת עם gRPC או REST. אין להשתמש בשתי השיטות כדי להימנע ממרוץ תהליכים ולשמור על מקור מהימן אחד.
gRPC
הדוגמה הבאה מראה איך להשתמש ספריית Java gRPC כדי להודיע ל-Fleet Engine שרכב נמצא בדרך לתחנה הבאה שלו.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// Next stop marked as ENROUTE
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 1st stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.ENROUTE)))
// All other stops marked as NEW
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
כדי להודיע ל-Fleet Engine שרכב נמצא בדרך לתחנה הבאה שלו מ
בסביבת השרת, מבצעים קריאת HTTP REST ל-UpdateDeliveryVehicle
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id> הוא מזהה ייחודי של רכב המסירה בארגון שלך שעבורו אתם מתכוונים לעדכן את סדר המשימות. זה המזהה שציינת כשיצרת את הרכב.
כותרת הבקשה חייבת להכיל שדה Authorization עם הערך האסימון <token>, כאשר <token> הוא אסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
גוף הבקשה חייב להכיל ישות DeliveryVehicle
:
שדה חובה:
שדה ערך remainingVehicleJourneySegments רשימת העצירות הנותרות של הרכבים, ומדינת היעד שלהן מסומנת כ-State.NEW. המצב של התחנה הראשונה ברשימה צריך להיות מסומן כ-State.ENROUTE. שדות אופציונליים:
- ללא
המערכת מתעלמת מכל שאר השדות בישות עבור ההתראה.
פקודת curl
לדוגמה:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "ENROUTE",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
עדכון מיקום הרכב
אם אתם לא משתמשים ב-Driver SDK כדי לעדכן את מיקום הרכב, אתם יכולים ליצור שיחה ישירה ל-Fleet Engine עם מיקום הרכב. לכל רכב פעיל, המערכות של Fleet Engine מצפה לעדכון מיקום לפחות פעם בדקה, ולכל היותר פעם ב-5 שניות.
gRPC
הדוגמה הבאה מראה איך להשתמש ספריית Java gRPC כדי לעדכן את מיקום הרכב ב-Fleet Engine:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle myDeliveryVehicle = DeliveryVehicle.newBuilder()
.setLastLocation(DeliveryVehicleLocation.newBuilder()
.setSupplementalLocation(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863))
.setSupplementalLocationTime(now())
.setSupplementalLocationSensor(DeliveryVehicleLocationSensor.CUSTOMER_SUPPLIED_LOCATION)
.setSupplementalLocationAccuracy(DoubleValue.of(15.0))) // Optional
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(myDeliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("last_location"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
כדי לעדכן את מיקום הרכב ב-Fleet Engine באמצעות HTTP REST, צריך לבצע קריאה ל
UpdateDeliveryVehicle
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=last_location`
<id> הוא מזהה ייחודי של רכב המשלוח של כלל המכשירים בארגון או שאתם מתכוונים לעדכן את המיקום. זה המזהה שציינת כשיצרת את הרכב.
כותרת הבקשה חייבת להכיל שדה Authorization עם הערך האסימון <token>, כאשר <token> הוא אסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
גוף הבקשה חייב להכיל ישות DeliveryVehicle
:
שדה חובה:
שדה ערך lastLocation.supplementalLocation המיקום של הרכב. lastLocation.supplementalLocationTime חותמת הזמן הידועה האחרונה שבה היה הרכב במיקום הזה. lastLocation.supplementalLocationSensor יש לאכלס אותו ב-CUSTOMER_SUPPLIED_LOCATION. שדות אופציונליים:
שדה ערך lastLocation.supplementalLocationAccuracy הדיוק של המיקום שסופק, במטרים.
פקודת curl
לדוגמה:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"lastLocation": {
"supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
"supplementalLocationTime": "$(date -u --iso-8601=seconds)",
"supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
"supplementalLocationAccuracy": 15
}
}
EOM
רכב מגיע בעצירה
יש ליידע את ה-Fleet Engine כשרכב מגיע לעצירה. אפשר לשלוח הודעה Fleet Engine Driver SDK, או מסביבת שרת עם gRPC או REST. אין להשתמש בשתי השיטות כדי להימנע ממרוץ תהליכים ולשמור על מקור מהימן אחד.
gRPC
הדוגמה הבאה מראה איך להשתמש ספריית Java gRPC כדי להודיע ל-Fleet Engine שרכב הגיע לעצירה:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// Marking the arrival at stop.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.ARRIVED)))
// All other remaining stops marked as NEW.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW))) // Remaining stops must be NEW.
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
כדי להודיע ל-Fleet Engine על הגעה של רכב לעצירה מסביבת שרת:
שליחת קריאה של HTTP REST ל-UpdateDeliveryVehicle
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id> הוא מזהה ייחודי של רכב המסירה בארגון שלך שעבורו אתם מתכוונים לעדכן את סדר המשימות. זה המזהה שציינת כשיצרת את הרכב.
כותרת הבקשה חייבת להכיל שדה Authorization עם הערך האסימון <token>, כאשר <token> הוא אסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
גוף הבקשה חייב להכיל ישות DeliveryVehicle
:
שדות חובה:
שדה ערך remainingVehicleJourneySegments התחנה שאליה הגעתם והמצב שלה מוגדר כ-State.ARRIVED, ולאחר מכן רשימה של תחנות העצירה הנותרות עם הכיתוב State.NEW. שדות אופציונליים:
- ללא
המערכת תתעלם מכל השדות האחרים בישות במהלך העדכון.
פקודת curl
לדוגמה:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "ARRIVED",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
הרכב עומד בעצירה
חובה להודיע למנוע בכלל בעת עצירה של כלי רכב. הדבר גורם כל המשימות שמשויכות לעצירה יועברו למצב 'סגור'. אפשר יודיעו ל-Fleet Engine Driver SDK, או מסביבת שרת עם gRPC או REST. אין להשתמש בשתי השיטות כדי להימנע ממרוץ תהליכים וגם כדי לשמור על מקור מהימן אחד.
gRPC
הדוגמה הבאה מראה איך להשתמש ספריית Java gRPC כדי להודיע ל-Fleet Engine שרכב השלים עצירה.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// This stop has been completed and is commented out to indicate it
// should be removed from the list of vehicle journey segments.
// .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
// .setStop(VehicleStop.newBuilder()
// .setPlannedLocation(LocationInfo.newBuilder()
// .setPoint(LatLng.newBuilder()
// .setLatitude(37.7749)
// .setLongitude(122.4194)))
// .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
// .setState(VehicleStop.State.ARRIVED)))
// All other remaining stops marked as NEW.
// The next stop could be marked as ENROUTE if the vehicle has begun
// its journey to the next stop.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // Next stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // no need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
כדי להודיע ל-Fleet Engine לגבי השלמה של עצירה בסביבת שרת:
שליחת קריאה של HTTP REST ל-UpdateDeliveryVehicle
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments`
<id> הוא מזהה ייחודי של רכב המסירה בארגון שלך שעבורו אתם מתכוונים לעדכן את סדר המשימות. זה המזהה שציינת כשיצרת את הרכב.
כותרת הבקשה חייבת להכיל שדה Authorization עם הערך האסימון <token>, כאשר <token> הוא אסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
גוף הבקשה חייב להכיל ישות DeliveryVehicle
:
שדות חובה:
שדה ערך remaining_vehicle_journey_segments התחנה שהשלמת לא אמורה להופיע יותר ברשימה של שאר עצירות הרכב. שדות אופציונליים:
- ללא
המערכת תתעלם מכל השדות האחרים בישות במהלך העדכון.
פקודת curl
לדוגמה:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
עדכון משימה
רוב שדות המשימה לא ניתנים לשינוי. אבל אפשר לשנות את המצב, תוצאת המשימה, זמן התוצאה של המשימה, המיקום של התוצאה של המשימה ומאפיינים לפי מעדכן ישירות את ישות המשימה. לדוגמה, במקרים שבהם למשימה לא הוקצתה לרכב, אפשר לסגור את המשימה על ידי עדכון את המצב הישיר.
gRPC
REST
דוגמה לעדכון משימה באמצעות REST
סגירת משימה
כדי לסגור משימה שהוקצתה לרכב, צריך לשלוח התראה ל-Fleet Engine. שהרכב סיים את העצירה שבה המשימה מתבצעת או להסיר אותו מרשימת תחנות העצירה. כדי לעשות את זה, אפשר להגדיר הרכב שנותר נעצר בדיוק כמו כשמעדכנים את סדר המשימות לרכב.
אם למשימה עדיין לא הוקצה רכב וצריך לסגור אותה, מעדכנים את המשימה למצב 'סגור'. עם זאת, אי אפשר לפתוח מחדש משימה שסגרה.
סגירה של משימה לא מצביעה על הצלחה או כישלון. הוא מציין כבר לא נחשבת בתהליך ביצוע. כדי לעקוב אחרי כלל המכשירים בארגון, חשוב לציין את התוצאה בפועל של המשימה, כדי יכולה להיות מוצגת.
gRPC
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setState(Task.State.CLOSED) // You can only directly CLOSE a
.build(); // task that is NOT assigned to a vehicle.
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("state"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
כדי לסמן משימה כ'סגורה' מסביבת שרת, צריך לבצע קריאת HTTP REST ל-
UpdateTask
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=state`
<id> הוא מזהה ייחודי של המשימה.
כותרת הבקשה חייבת להכיל שדה Authorization עם הערך האסימון <token>, כאשר <token> הוא אסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
צריך לכלול ישות Task
בגוף הבקשה:
שדות חובה:
שדה ערך הסמוי הסופי State.CLOSED שדות אופציונליים:
שדה ערך taskOutcome תוצאה.דיווח או שהתקבלו.נכשל taskOutcomeTime השעה שבה המשימה הושלמה. taskOutcomeLocation המיקום שבו המשימה הושלמה. כברירת מחדל, ה-Fleet Engine מוגדר כך למיקום הרכב האחרון, אלא אם הספק שינה זאת באופן ידני.
המערכת תתעלם מכל השדות האחרים בישות במהלך העדכון.
פקודת curl
לדוגמה:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=state,taskOutcome,taskOutcomeTime" \ -H "Content-type: application/json" \ -H "Authorization: Bearer ${JWT}" \ --data-binary @- << EOM { "state": "CLOSED", "taskOutcome": "SUCCEEDED", "taskOutcomeTime": "$(date -u --iso-8601=seconds)" } EOM
מגדירים את תוצאת המשימה ואת המיקום שלה
סגירת משימה לא מצביעה על הצלחה או כישלון, אלא מציינת המשימה כבר לא תיחשב בתהליך. כדי לעקוב אחרי כלל המכשירים בארגון, חשוב לציין את התוצאה בפועל של המשימה, הצגה של תוצאות המשלוח ושיש חיוב מתאים עבור השירותים. אחרי שמגדירים את המשימה, אי אפשר לשנות אותה. אבל אפשר לשנות את הזמן של תוצאת המשימה והמיקום שבו היא הושגה אחרי שהם הוגדרו.
אם המשימות הן במצב 'סגור', אפשר להגדיר אותן לאחת מהאפשרויות הבאות: {2}נפוצה או נכשלה. Fleet Engine גובה רק משימות מסירה במצב של קריטריונים.
כשמסמנים תוצאה של משימה, Fleet Engine ממלא באופן אוטומטי את המיקום של תוצאת המשימה עם המיקום הידוע האחרון של הרכב. אפשר לשנות את ההתנהגות הזו.
gRPC
אפשר לבחור את המיקום של תוצאת המשימה כשקובעים את התוצאה הרצויה. הגדרת המיקום מונעת מ-Fleet Engine להגדיר אותו לברירת המחדל מיקום הרכב. אפשר גם להחליף את מיקום התוצאה של המשימה ב-Fleet Engine שתגדירו במועד מאוחר יותר. Fleet Engine אף פעם לא מחליף מיקום של תוצאת משימה שמספקים. אי אפשר להגדיר את מיקום התוצאה של המשימה שלא הוגדרה לו תוצאת משימה. אתם יכולים להגדיר את שתי תוצאות המשימה ומיקום התוצאה של המשימה באותה בקשה.
הדוגמה הבאה מראה איך להשתמש ספריית Java gRPC כדי להגדיר תוצאת משימה לצורך פילוח, ולהגדיר את המיקום שבו המשימה בוצעה הושלם:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTaskOutcome(TaskOutcome.SUCCEEDED)
.setTaskOutcomeTime(now())
.setTaskOutcomeLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("task_outcome", "task_outcome_time", "task_outcome_location"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
כדי לסמן שמשימה בוצעה מסביבת שרת:
שליחת קריאה של HTTP REST ל-UpdateTask
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation`
<id> הוא מזהה ייחודי של המשימה.
כותרת הבקשה חייבת להכיל שדה Authorization עם הערך האסימון <token>, כאשר <token> הוא אסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
גוף הבקשה חייב להכיל ישות Task
:
שדות חובה:
שדה ערך taskOutcome תוצאה.דיווח או שהתקבלו.נכשל שדות אופציונליים:
שדה ערך taskOutcomeLocation המיקום שבו המשימה הושלמה. אם המדיניות לא מוגדרת, Fleet Engine ברירת המחדל היא מיקום הרכב האחרון. taskOutcomeTime חותמת הזמן של מועד השלמת המשימה.
המערכת תתעלם מכל השדות האחרים בישות במהלך העדכון.
פקודת curl
לדוגמה:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"taskOutcome": "SUCCEEDED",
"taskOutcomeTime": "$(date -u --iso-8601=seconds)",
"taskOutcomeLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
}
}
EOM
ניתוב מחדש של משלוח
אחרי שיוצרים משימת משלוח, אי אפשר לשנות את המיקום המתוכנן שלה. כדי לנתב מחדש משלוח, צריך לסגור את משימת המשלוח בלי להגדיר תוצאה, ואז ליצור משימה חדשה עם המיקום המתוכנן המעודכן. אחרי שיוצרים את המשימה החדשה, מקצים את המשימה לאותו כלי רכב. לקבלת מידע נוסף מידע נוסף זמין בקטע סגירה של משימת המשלוח מקצים את המשימה.
משתמשים ברכבי הזנה וכלי משלוח
אם אתם משתמשים ברכבים באמצעות מנגנון הזנה בהובלת משלוחים לרכבי הובלה במהלך היום, לבנות מודל של העברת המשלוחים כמשימה מתוזמנת של עצירה לרכב המשלוח. כדי להבטיח מעקב מדויק אחר מיקום, מקצים רק משימה של מסירת משלוח של משלוח שהועבר אחרי שהוא נטען רכב מסירה. מידע נוסף זמין במאמר בנושא עצירה מתוזמנת.
סטטוס משלוח של חנות ומטא-נתונים נוספים
כשמשימת משלוח מסתיימת, מצב המשימה והתוצאה מתועדים. במשימה. עם זאת, ייתכן שתרצו לעדכן מטא-פרטים אחרים ספציפי למשלוח. כדי לאחסן מטא-נתונים אחרים שניתן הפניה מחוץ לשירות Fleet Engine, יש להשתמש בפרמטר tracking_id המשויך במשימה כמפתח בטבלה חיצונית.
מידע נוסף מופיע במאמר חיי המשימה.
חיפוש כלי רכב
אפשר לחפש כלי רכב Driver SDK, או מסביבת שרת עם gRPC או REST.
gRPC
הדוגמה הבאה מראה איך להשתמש ספריית Java gRPC כדי לחפש רכב:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle request
String name = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
GetDeliveryVehicleRequest getVehicleRequest = GetDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(name)
.build();
try {
DeliveryVehicle vehicle = deliveryService.getDeliveryVehicle(getVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
כדי לחפש רכב מסביבת שרת,
שליחת קריאה של HTTP REST ל-GetVehicle
:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<vehicleId>`
<id> הוא מזהה ייחודי של המשימה.
<vehicleId> הוא מזהה הרכב שצריך לחפש.
כותרת הבקשה חייבת להכיל שדה Authorization עם הערך האסימון <token>, כאשר <token> הוא אסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
גוף הבקשה חייב להיות ריק.
אם החיפוש יסתיים בהצלחה, גוף התגובה יכלול ישות של רכב.
פקודת curl
לדוגמה:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}"
חיפוש משימה
אפשר לחפש משימות בסביבת שרת באמצעות gRPC או REST. ה-SDK של מנהל התקן לא תמיכה בחיפוש משימה.
gRPC
הדוגמה הבאה מראה איך להשתמש ספריית Java gRPC כדי לחפש משימה:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8597549";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task request
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
GetTaskRequest getTaskRequest = GetTaskRequest.newBuilder() // No need for the header
.setName(taskName)
.build();
try {
Task task = deliveryService.getTask(getTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
כדי לחפש משימה בסביבת שרת:
שליחת קריאה של HTTP REST ל-GetTask
:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<taskId>`
<id> הוא מזהה ייחודי של המשימה.
<taskId> הוא המזהה של המשימה לחיפוש.
כותרת הבקשה חייבת להכיל שדה Authorization עם הערך האסימון <token>, כאשר <token> הוא אסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
גוף הבקשה חייב להיות ריק.
אם החיפוש יסתיים בהצלחה, גוף התגובה יכלול ישות משימה.
פקודת curl
לדוגמה:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}"
מחפשים מידע על משימת משלוח לפי המזהה לצורכי מעקב
אפשר לחפש מידע על המשימות של כלל המכשירים בארגון בדרכים הבאות: שלכל אחת מהן יש מטרה נפרדת:
- by a Task ID: משמש משתמשים כמו מפעילים של כלל המכשירים בארגון שיש להם גישה תצוגה מלאה של נתוני המשימה.
- על ידי מזהה מעקב: משמש את תוכנת הלקוח כדי לספק הגבלה מידע למשתמש קצה, למשל מתי החבילה צפויה להגיע בבית שלו.
בקטע הזה נסביר איך מחפשים פרטי משימה לפי מזהה לצורכי מעקב. אם רוצים כדי לחפש משימה לפי מזהה המשימה, אפשר לעבור למאמר חיפוש משימה.
כדי לחפש מידע לפי מזהה לצורכי מעקב, אפשר להשתמש באחת מהאפשרויות הבאות:
דרישות לחיפוש
פרטי המשלוח שסופקו על ידי מזהה לצורכי מעקב עומדים בכללי החשיפה צוין ב- שליטה בחשיפה של המיקומים שבמעקב
אפשר להשתמש ב-Fleet Engine כדי לחפש פרטי משלוח לפי מזהה לצורכי מעקב. הנהג/ת ערכת ה-SDK לא תומכת בחיפוש מידע לפי מזהה לצורכי מעקב. לביצוע זאת באמצעות Fleet מנוע, עליך להשתמש בשרת או בסביבת דפדפן.
השתמשו באסימון הצר ביותר שאפשר כדי להגביל את סיכוני האבטחה. לדוגמה, אם משתמשים באסימון הצרכן למשלוח, החזרת כל קריאות ל-API של Fleet Engine Deliveries רק מידע שרלוונטי למשתמש הקצה, כמו השולח או מקבל משלוח. כל שאר המידע בתשובות מושמט. מידע נוסף על אסימונים זמין במאמר יצירת אסימון רשת מבוסס JSON (JWT) להרשאה.
חיפושים ב-Java באמצעות gRPC
הדוגמה הבאה מראה איך להשתמש ספריית Java gRPC לחפש מידע על משימת משלוח לפי המזהה שלה לצורכי מעקב.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
GetTaskTrackingInfoRequest getTaskTrackingInfoRequest = GetTaskTrackingInfoRequest.newBuilder() // No need for the header
.setParent(parent)
.setTrackingId(TRACKING_ID)
.build();
try {
TaskTrackingInfo taskTrackingInfo = deliveryService.getTaskTrackingInfo(getTaskTrackingInfoRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
חיפושי מידע שמשתמשים ב-HTTP
כדי לחפש משימת משלוח מדפדפן, צריך לבצע קריאת HTTP REST אל
GetTaskTrackingInfo
:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/taskTrackingInfo/<tracking_id>`
<tracking_id> הוא המזהה לצורכי מעקב שמשויך למשימה.
כותרת הבקשה חייבת להכיל שדה Authorization עם הערך נושא <token>, כאשר <token> הוא האסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
אם החיפוש יסתיים בהצלחה, גוף התגובה יכלול taskTrackingInfo .
פקודת curl
לדוגמה:
# Set JWT, PROJECT_ID, and TRACKING_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/taskTrackingInfo/${TRACKING_ID}"
הצגת רשימת המשימות
אתם יכולים להציג רשימה של משימות משרת או מסביבת דפדפן. ה-SDK של מנהל התקן לא יצירת רשימה של משימות.
הצגת רשימה של משימות מבקשת גישה רחבה למשימות. הצגת רשימת המשימות מיועדת רק משתמשים מהימנים. שימוש באימות על ידי קריאה של כלל המסירה או בהעברה של משתמש על אסימונים כששולחים בקשות למשימות של רשימה.
במשימות שברשימה מצונזרים השדות הבאים:
- VehicleStop.planned_location
- VehicleStop.state
- VehicleStop.TaskInfo.taskId
אפשר לסנן את המשימות שברשימה לפי רוב מאפייני המשימות. בתחביר של שאילתות סינון: ראו AIP-160. ברשימה הבאה מוצגת משימה תקינה שבהם אפשר להשתמש לסינון:
- מאפיינים
- delivery_vehicle_id
- הסמוי הסופי
- planned_location
- task_duration
- task_outcome
- task_outcome_location
- task_outcome_location_source
- task_outcome_time
- tracking_id
- סוג
משתמשים בפורמטים הבאים של השדות, שמבוססים על הצעות לשיפור של Google API:
סוג שדה | פורמט | דוגמה |
---|---|---|
חותמת זמן | RFC-3339 | task_outcome_time = 2022-03-01T11:30:00-08:00 |
משך | מספר השניות ואחריהן s |
task_duration = 120s |
Enum | מחרוזת | state = CLOSED AND type = PICKUP |
מיקום | point.latitude וגם point.longitude |
planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0 |
לרשימה מלאה של שאילתות סינון אפשר לעיין ב-AIP-160 אופרטורים.
אם לא צוינה שאילתת סינון, כל המשימות יופיעו ברשימה.
רשימות של משימות מחולקות לדפים. אפשר לציין גודל דף בבקשות למשימות של רשימה. אם מצוין גודל הדף, מספר המשימות שהוחזרו לא יהיה גדול יותר מגודל הדף שצוין. אם לא מוגדר גודל דף, ברירת מחדל סבירה נעשה שימוש. אם גודל הדף המבוקש חורג מערך מקסימלי פנימי, ואז המערכת תשתמש במקסימום הפנימי.
רשימת משימות יכולה לכלול אסימון לקריאת דף התוצאות הבא. שימוש באסימון הדף עם בקשה שזהה אחרת לבקשה הקודמת בקשה לאחזר את הדף הבא של המשימות. מתי האסימון המוחזר של הדף ריקה, אין עוד משימות זמינות לאחזור.
gRPC
הדוגמה הבאה מראה איך להשתמש ספריית Java gRPC כדי להציג רשימת משימות עבור deliveryVehicleId ומאפיין משימה. מוצלח התשובה עדיין יכולה להיות ריקה. תגובה ריקה מציינת שאין משימות שמשויך ל-deliveryVehicleId שסופק.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
ListTasksRequest listTasksRequest = ListTasksRequest.newBuilder() // No need for the header
.setParent(parent)
.setFilter("delivery_vehicle_id = 123 AND attributes.foo = true")
.build();
try {
ListTasksResponse listTasksResponse = deliveryService.listTasks(listTasksRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
כדי להציג רשימת משימות מדפדפן, צריך לשלוח קריאה ל-HTTP REST ל-ListTasks
:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks`
כדי להחיל מסנן על המשימות שברשימה, צריך לכלול 'מסנן' פרמטר של כתובת אתר עם ערך של שאילתת סינון שמסומנת בתו בריחה (escape) של כתובת URL.
כותרת הבקשה חייבת להכיל שדה Authorization עם הערך האסימון <token>, כאשר <token> הוא אסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
אם החיפוש יסתיים בהצלחה, גוף התגובה יכיל נתונים במבנה הבא:
// JSON representation
{
"tasks": [
{
object (Task)
}
],
"nextPageToken": string,
"totalSize": integer
}
תגובה מוצלחת עדיין יכולה להיות ריקה. תגובה ריקה מציינת שלא נמצאו משימות שעומדות בקריטריוני הסינון שצוינו.
פקודת curl
לדוגמה:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?filter=state%20%3D%20OPEN%20AND%20delivery_vehicle_id%20%3D%20${VEHICLE_ID}"
הצגה של רשימת רכבים למשלוחים
אתם יכולים להציג רשימה של כלי רכב למשלוחים מסביבת שרת או דפדפן. הנהג/ת ערכת ה-SDK לא תומכת בכרטיסי מוצר עם משלוחים.
כלי רכב למשלוחים מבקשים גישה רחבה לרכבי משלוחים, שמיועד למשתמשים מהימנים בלבד. שימוש בקריאה של Fleet למסירה או ב-Super Delivery אסימוני אימות משתמש כששולחים בקשות מכלי רכב למשלוח רשימות.
בכלי הרכב הרשומים מצונזרים השדות הבאים עקב השפעתם לגבי גודל התגובה:
- CurrentRouteSegment
- RemainingVehicleJourneySegments
אפשר לסנן את רשימת כלי הרכב שמוצעים למכירה לפי מאפיין attributes
שלהם. עבור
לדוגמה, כדי לשלוח שאילתה על מאפיין עם המפתח my_key
והערך my_value
, משתמשים
attributes.my_key = my_value
. כדי לשלוח שאילתה לגבי כמה מאפיינים, צריך לחבר שאילתות
באמצעות האופרטורים הלוגיים AND
ו-OR
כמו ב-attributes.key1 = value1 AND
attributes.key2 = value2
. לקבלת מידע מלא, ראו AIP-160
לתיאור התחביר של שאילתת הסינון.
אפשר לסנן את רכבי המשלוח שצוינו לפי מיקום באמצעות בקשת viewport
הפרמטר. פרמטר הבקשה viewport
מגדיר אזורי תצוגה באמצעות שני תוחמים
קואורדינטות: high
(צפון מזרח) ו-low
(דרום מערב) קו רוחב וקו אורך
בצמד הקואורדינטות. הבקשות נדחות אם הן מכילות קו רוחב גבוה
נמוך מבחינה גיאוגרפית מקו רוחב נמוך.
כברירת מחדל, רשימות של רכבי משלוח מחולקות לדפים, לפי גודל דף סביר. אם המיקום מציינים גודל דף, הבקשה מחזירה רק את מספר כלי הרכב שצוין במגבלה, או פחות. אם גודל הדף המבוקש חורג מגודל פנימי כערך המקסימלי, המערכת תשתמש בערך המקסימלי הפנימי. דף ברירת המחדל ודף המקסימום שני הגדלים הם 100 כלי רכב.
רשימת כלי רכב למשלוחים יכולה לכלול אסימון לקריאת הדף הבא של תוצאות. אסימון דף מוצג בתגובה רק כאשר דפים נוספים של מסירה כלי רכב זמינים לאחזור. כדי לאחזר את דף המשימות הבא: אסימון הדף עם בקשה שזהה אחרת לאסימון הקודם בקשה.
gRPC
הדוגמה הבאה מראה איך להשתמש ספריית Java gRPC כדי לפרסם כלי רכב למשלוחים באזור מסוים עם מאפיין מסוים. א' תגובה מוצלחת עדיין יכולה להיות ריקה. במקרה כזה, פירוש הדבר הוא שלא כלי רכב עם המאפיין שצוין כבר נמצאים באזור התצוגה שצוין.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
ListDeliveryVehiclesRequest listDeliveryVehiclesRequest =
ListDeliveryVehiclesRequest.newBuilder() // No need for the header
.setParent(parent)
.setViewport(
Viewport.newBuilder()
.setHigh(LatLng.newBuilder()
.setLatitude(37.45)
.setLongitude(-122.06)
.build())
.setLow(LatLng.newBuilder()
.setLatitude(37.41)
.setLongitude(-122.11)
.build())
.setFilter("attributes.my_key = my_value")
.build();
try {
ListDeliveryVehiclesResponse listDeliveryVehiclesResponse =
deliveryService.listDeliveryVehicles(listDeliveryVehiclesRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
כדי להציג רשימת משימות מדפדפן, צריך לשלוח קריאה ל-HTTP REST ל-ListDeliveryVehicles
:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles`
כדי להחיל מסנן על המשימות שברשימה, צריך לכלול 'מסנן' פרמטר של כתובת אתר עם רכיב ערך של שאילתת סינון שמסומנת בתו בריחה (escape) של כתובת URL.
כותרת הבקשה חייבת להכיל שדה Authorization עם הערך האסימון <token>, כאשר <token> הוא אסימון שהונפק על ידי מפעל לאסימונים של Fleet Engine.
אם החיפוש יסתיים בהצלחה, גוף התגובה יכיל נתונים במבנה הבא:
// JSON representation
{
"deliveryVehicles": [
{
object (DeliveryVehicle)
}
],
"nextPageToken": string,
"totalSize": integer
}
תגובה מוצלחת עדיין יכולה להיות ריקה. במקרה כזה, פירוש הדבר הוא שלא נמצאו רכבי משלוח שעומדים בשאילתת הסינון ובאזור התצוגה שצוינו.
פקודת curl
לדוגמה:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?filter=attributes.my_key%20%3D%20my_value%20&viewport.high.latitude=37.45&viewport.high.longitude=-122.06&viewport.low.latitude=37.41&viewport.low.longitude=-122.11"
מעקב אחר כלל המכשירים בארגון
יש שתי אפשרויות להשתמש Fleet Engine Deliveries API כדי להפעיל מעקב אחרי כלל המכשירים:
מועדף: השתמשו ספריית Fleet Tracking. הספרייה מאפשרת להציג באופן חזותי את המיקום של כלי רכב ומיקומים של תחומי עניין שנמצאים במעקב ב-Fleet Engine. התוצאה מכילה רכיב מפה של JavaScript שהוא תחליף לאובייקט google.maps.Map סטנדרטי, ורכיבי נתונים לחיבור עם Fleet Engine. הרכיב הזה מאפשר לספק חוויה מונפשת של מעקב אחר כלל המכשירים בארגון מאפליקציית האינטרנט או האפליקציה לנייד.
תוכלו להטמיע מעקב משלכם אחרי כלל המכשירים בנוסף ל-Fleet Engine Deliveries API.
המפתח הוא לחפש משימות בארגון כולו לפי מזהה לצורכי מעקב.
רישום ביומן
אפשר להגדיר את Fleet Engine כך שישלח יומני RPC ל-Cloud Logging. לקבלת מידע נוסף מידע נוסף, ראה רישום ביומן.
תפקידים ואסימונים
כפי שמתואר במאמר ניהול מחזור החיים של רכב ומשימה ואת הערות ההרשאה לתרחישים לדוגמה ספציפיים, כך לקריאות ל-Fleet Engine מחייבות אימות באמצעות אסימוני אינטרנט JSON שיש להם נחתם באמצעות פרטי כניסה של חשבון שירות. חשבונות השירות שבהם נעשה שימוש להנפקת האסימונים האלה יכול להיות תפקיד אחד או יותר, שכל תפקיד מקצה קבוצה שונה של הרשאות.
מידע נוסף זמין במאמר הבא: אימות והרשאה.
פתרון בעיות נפוצות
אם נתקלתם בבעיות, כדאי לעיין בקטעים הבאים כדי לקבל עזרה.
עמידות
Fleet Engine לא נחשב למקור מידע. באחריותך לשחזור מצב המערכת במקרה הצורך, מבלי להסתמך על מנוע Fleet.
מצב אובדן מכשיר ב-Fleet Engine
כשעובדים עם Fleet Engine, מטמיעים לקוחות כדי שהמערכת תרפאו עצמו במקרה של כשל. לדוגמה, כש-Fleet Engine מנסה לעדכן הוא עשוי להגיב עם שגיאה שמציינת שהרכב לא מגיב קיימים. לאחר מכן הלקוח צריך ליצור מחדש את הרכב במצב החדש. למרות הבעיה הזו מתרחשת לעיתים רחוקות, צריך לוודא שהמערכת עמידה מספיק כדי להתמודד עם את זה.
במקרה הנדיר ביותר של כשל קטסטרופלי מ-Fleet Engine, יכול להיות שתצטרכו ליצור מחדש את רוב כלי הרכב והמשימות, או את כולם. אם קצב היצירה גבוה מדי, חלק מהבקשות עלולות להיכשל שוב בגלל בעיות במכסה, בדיקות מכסות מופעלות כדי למנוע התקפות מניעת שירות (DOS). במקרה כזה, האטו את שיעור הנסיעות באמצעות אסטרטגיית השהיה לפני ניסיון חוזר (backoff) עבור ניסיונות חוזרים.
מצב אובדן מכשיר באפליקציית הנהג
אם אפליקציית הנהג קורסת, האפליקציה צריכה ליצור מחדש את המצב הנוכחי ב-Driver SDK. האפליקציה צריכה לנסות ליצור מחדש משימות כדי לוודא שהם קיימים ולשחזר את המצבים הנוכחיים שלהם. האפליקציה צריכה גם ליצור מחדש ולהגדיר במפורש את רשימת העצירות ל-Driver SDK.
שאלות נפוצות
מה קורה אם נהג עוצר לקראת משימה שלא תקינה?
במקרה כזה, קודם מעדכנים את הסדר של המשימות ואז ממשיכים כרגיל, סימון זמן ההגעה לעצירה, השלמת המשימה ופרטים נוספים. אם לא תעשו זאת, ייתכן שהמערכת לא תהיה עקבית, וזמני ההגעה המשוערים עלולים להיות שגויים, וייתכן שידווחו שגיאות לא צפויות.