הגדרת JavaScript Consumer SDK

באמצעות ה-SDK של JavaScript לצרכנים, אפליקציית הצרכנים יכולה להציג מפה מבוססת-אינטרנט עם המיקום של כלי הרכב ומיקומי עניין אחרים שבהם מתבצע מעקב ב-Fleet Engine. כך המשתמשים שלכם יוכלו לראות את ההתקדמות של המשלוח. במדריך הזה אנו מביאים בחשבון שכבר הגדרתם את Fleet Engine עם הפרויקט ועם מפתחות ה-API המשויכים שלו ב-Google Cloud. פרטים נוספים זמינים במאמר Fleet Engine.

כדי להגדיר את JavaScript Consumer SDK:

1. מפעילים את Maps JavaScript API.
2. מגדירים הרשאה.

הפעלת Maps JavaScript API

מפעילים את Maps JavaScript API בפרויקט במסוף Google Cloud שבו אתם משתמשים למכונה של Fleet Engine. פרטים נוספים זמינים בקטע הפעלת ממשקי API במסמכי העזרה של Maps JavaScript API.

הגדרת הרשאה

בקריאות לשיטות API מסביבות עם רמת אמון נמוכה, מערכת Fleet Engine דורשת שימוש באסימוני JWT (JSON Web Tokens) בחתימה של חשבון שירות מתאים. סביבות עם רמת אמון נמוכה כוללות סמארטפונים ודפדפנים. JWT נוצר בשרת שלכם, שהוא סביבה מהימנה לחלוטין. ה-JWT נחתם, מוצפן ומוענק ללקוח לצורך אינטראקציות עתידיות עם השרת, עד שתוקף האסימון יפוג או שהוא כבר לא יהיה תקף.

הקצה העורפי צריך לבצע אימות והרשאה מול Fleet Engine באמצעות מנגנונים רגילים של Application Default Credentials. חשוב להשתמש באסימוני JWT שחתומים על ידי חשבון שירות מתאים. לרשימת התפקידים של חשבונות השירות, ראו תפקידים של חשבונות שירות ב-Fleet Engine בקטע יסודות של Fleet Engine.

לעומת זאת, הקצה העורפי צריך לבצע אימות והרשאה מול Fleet Engine באמצעות מנגנונים רגילים של Application Default Credentials.

איך מתבצע האימות?

ההרשאה באמצעות נתוני Fleet Engine כוללת הטמעה גם בצד השרת וגם בצד הלקוח.

הרשאה בצד השרת

לפני שמגדירים אימות והרשאה באפליקציה מבוססת-האינטרנט, שרת הקצה העורפי צריך להיות מסוגל להנפיק לאפליקציה מבוססת-האינטרנט אסימוני אינטרנט מסוג JSON כדי לקבל גישה ל-Fleet Engine. האפליקציה מבוססת-האינטרנט שולחת את אסימוני ה-JWT האלה עם הבקשות שלה, כדי ש-Fleet Engine יזהה את הבקשות כמאומתות ועם הרשאה לגשת לנתונים שבבקשה. להוראות להטמעת JWT בצד השרת, אפשר לעיין בקטע הנפקה של אסימוני אינטרנט מסוג JSON בקטע יסודות של Fleet Engine.

• הנחיות כלליות להנפקה של אסימוני JSON Web
• הנחיות לשימוש ב-JWT במשימות מתוזמנות
• דוגמה לטוקן של אפליקציית צרכן

הרשאה מצד הלקוח

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

• אין טוקן תקף, למשל כש-SDK לא קרא למאחזר בטעינה של דף חדש, או כשהמאחזר לא החזיר טוקן.

• פג תוקפו של הטוקן.

• תוקף האסימון יפוג תוך דקה.

אחרת, ה-SDK של צרכן JavaScript משתמש באסימון החוקי שהונפק בעבר ולא קורא למאחזר.

יצירת אובייקט לאחזור של אסימון הרשאה

יוצרים את האסימון של מבצע האחזור של אסימון ההרשאה לפי ההנחיות הבאות:

• אוסף הנתונים חייב להחזיר מבנה נתונים עם שני שדות, עטוף ב-Promise באופן הבא:

  • מחרוזת token.

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

• האחזור צריך לקרוא לכתובת URL בשרת כדי לאחזר אסימון. כתובת ה-URL הזו – SERVER_TOKEN_URL – תלויה ביישום הקצה העורפי. כתובת ה-URL לדוגמה הבאה היא של קצה העורפי של האפליקציה לדוגמה ב-GitHub:

  • https://SERVER_URL/token/delivery_consumer/TRACKING_ID

דוגמה – יצירת אובייקט לאחזור אסימון אימות

בדוגמאות הבאות מוסבר איך יוצרים אובייקט לאחזור אסימון הרשאה:

async function authTokenFetcher(options) {
  // options is a record containing two keys called
  // serviceType and context. The developer should
  // generate the correct SERVER_TOKEN_URL and request
  // based on the values of these fields.
  const response = await fetch(SERVER_TOKEN_URL);
  if (!response.ok) {
    throw new Error(response.statusText);
  }
  const data = await response.json();
  return {
    token: data.Token,
    expiresInSeconds: data.ExpiresInSeconds
  };
}

function authTokenFetcher(options: {
  serviceType: google.maps.journeySharing.FleetEngineServiceType,
  context: google.maps.journeySharing.AuthTokenContext,
}): Promise<google.maps.journeySharing.AuthToken> {
  // The developer should generate the correct
  // SERVER_TOKEN_URL based on options.
  const response = await fetch(SERVER_TOKEN_URL);
  if (!response.ok) {
    throw new Error(response.statusText);
  }
  const data = await response.json();
  return {
    token: data.token,
    expiresInSeconds: data.ExpiresInSeconds,
  };
}

המאמרים הבאים

• מעקב אחרי משלוח