ה-SDK של הצרכן מספק הרשאה באמצעות אסימוני JSON Web. אסימון אינטרנט מסוג JSON (JWT) הוא אסימון הרשאה שמספק הצהרה אחת או יותר בשירות.
ה-SDK של הצרכן משתמש בטוקן ה-JSON Web שסופק על ידי האפליקציה כדי לתקשר עם Fleet Engine. תוכלו לקרוא פרטים נוספים על האסימונים שאמורים להיות לשרת ה-Fleet Engine, במאמרים JSON Web Tokens והנפקת אסימוני אינטרנט JSON.
אסימון ההרשאה מספק גישה לשירותים הבאים של Fleet Engine:
TripService
– מעניק ל-SDK לצרכן גישה לפרטי הנסיעה, כולל מיקום הרכב, המסלול וזמן ההגעה המשוער. אסימוני ההרשאה לשירות הנסיעה חייבים לכלול הצהרהtripid:TRIP_ID
בכותרתauthorization
של האסימון.TRIP_ID
הוא מזהה הנסיעה של הנסיעה על פי דרישה ששותפה.VehicleService
– נותן ל-Consumer SDK מידע על המיקום המשוער של הרכב, כדי להציג את שכבת צפיפות הרכבים ולחשב את זמני ההגעה המשוער לנקודת האיסוף. מאחר ש-Consumer SDK משתמש רק במיקומים משוערים, לא נדרשת הצהרתvehicleid
לטוקני ההרשאה של שירות הרכב.
מה זה אסימון?
בקריאות לשיטות API מסביבות עם רמת אמון נמוכה, מערכת Fleet Engine דורשת שימוש באסימוני JWT (JSON Web Tokens) בחתימה של חשבון שירות מתאים. סביבות עם רמת אמון נמוכה כוללות סמארטפונים ודפדפנים. ה-JWT מגיע בשרת, שהוא סביבה מהימנה לגמרי. ה-JWT נחתם, מוצפן ועובר ללקוח לאינטראקציה הבאה עם השרת, עד שהתוקף שלו פג או שהוא כבר לא בתוקף.
הקצה העורפי צריך לבצע אימות והרשאה מול Fleet Engine באמצעות מנגנונים רגילים של Application Default Credentials. הקפידו להשתמש באסימוני JWT שחתמו על ידי חשבון שירות מתאים. לרשימת התפקידים של חשבונות השירות, ראו תפקידי חשבון השירות של Fleet Engine בקטע יסודות של Fleet Engine.
לעומת זאת, הקצה העורפי צריך לבצע אימות ואישור מול Fleet Engine באמצעות מנגנונים רגילים של Application Default Credentials.
למידע נוסף על אסימוני JSON Web, ראו JSON Web Tokens בקטע יסודות של Fleet Engine.
איך לקוחות מקבלים אסימונים?
אחרי שהנהג או הצרכן מתחברים לאפליקציה עם פרטי הכניסה המתאימים, בכל עדכון שמונפקים מהמכשיר צריך להשתמש באסימוני ההרשאה המתאימים, והם מעבירים ל-Fleet Engine את ההרשאות לאפליקציה.
כמפתחים, ההטמעה של הלקוח אמורה לספק את היכולת לבצע את הפעולות הבאות:
- אחזור אסימון רשת מבוסס JSON מהשרת.
- כדאי לעשות שימוש חוזר באסימון עד שתוקף התוקף שלו יפוג, כדי לצמצם את מספר הרענונים של האסימון.
- צריך לרענן את האסימון כשהתוקף שלו יפוג.
המחלקה AuthTokenFactory
יוצרת אסימוני הרשאה בזמן עדכון המיקום. ה-SDK צריך לארוז את האסימונים יחד עם פרטי העדכון כדי לשלוח אותם ל-Fleet Engine. לפני שמפעילים את ה-SDK, צריך לוודא שההטמעה בצד השרת יכולה להנפיק אסימונים.
פרטים על האסימונים ששירות Fleet Engine מצפה להם מפורטים במאמר הנפקת אסימוני אינטרנט מסוג JSON בנושא Fleet Engine.
דוגמה למאחזר של אסימון הרשאה
הקוד לדוגמה הבא מדגים איך מטמיעים קריאה חוזרת (callback) לאסימון הרשאה.
Java
class JsonAuthTokenFactory implements AuthTokenFactory {
private static final String TOKEN_URL =
"https://yourauthserver.example/token";
private static class CachedToken {
String tokenValue;
long expiryTimeMs;
String tripId;
}
private CachedToken token;
/*
* This method is called on a background thread. Blocking is OK. However, be
* aware that no information can be obtained from Fleet Engine until this
* method returns.
*/
@Override
public String getToken(AuthTokenContext context) {
// If there is no existing token or token has expired, go get a new one.
String tripId = context.getTripId();
if (tripId == null) {
throw new RuntimeException("Trip ID is missing from AuthTokenContext");
}
if (token == null || System.currentTimeMillis() > token.expiryTimeMs ||
!tripId.equals(token.tripId)) {
token = fetchNewToken(tripId);
}
return token.tokenValue;
}
private static CachedToken fetchNewToken(String tripId) {
String url = TOKEN_URL + "/" + tripId;
CachedToken token = new CachedToken();
try (Reader r = new InputStreamReader(new URL(url).openStream())) {
com.google.gson.JsonObject obj
= com.google.gson.JsonParser.parseReader(r).getAsJsonObject();
token.tokenValue = obj.get("ServiceToken").getAsString();
token.expiryTimeMs = obj.get("TokenExpiryMs").getAsLong();
/*
* The expiry time could be an hour from now, but just to try and avoid
* passing expired tokens, we subtract 5 minutes from that time.
*/
token.expiryTimeMs -= 5 * 60 * 1000;
} catch (IOException e) {
/*
* It's OK to throw exceptions here. The error listeners will receive the
* error thrown here.
*/
throw new RuntimeException("Could not get auth token", e);
}
token.tripId = tripId;
return token;
}
}
Kotlin
class JsonAuthTokenFactory : AuthTokenFactory() {
private var token: CachedToken? = null
/*
* This method is called on a background thread. Blocking is OK. However, be
* aware that no information can be obtained from Fleet Engine until this
* method returns.
*/
override fun getToken(context: AuthTokenContext): String {
// If there is no existing token or token has expired, go get a new one.
val tripId =
context.getTripId() ?:
throw RuntimeException("Trip ID is missing from AuthTokenContext")
if (token == null || System.currentTimeMillis() > token.expiryTimeMs ||
tripId != token.tripId) {
token = fetchNewToken(tripId)
}
return token.tokenValue
}
class CachedToken(
var tokenValue: String? = "",
var expiryTimeMs: Long = 0,
var tripId: String? = "",
)
private companion object {
const val TOKEN_URL = "https://yourauthserver.example/token"
fun fetchNewToken(tripId: String) {
val url = "$TOKEN_URL/$tripId"
val token = CachedToken()
try {
val reader = InputStreamReader(URL(url).openStream())
reader.use {
val obj = com.google.gson.JsonParser.parseReader(r).getAsJsonObject()
token.tokenValue = obj.get("ServiceToken").getAsString()
token.expiryTimeMs = obj.get("TokenExpiryMs").getAsLong()
/*
* The expiry time could be an hour from now, but just to try and avoid
* passing expired tokens, we subtract 5 minutes from that time.
*/
token.expiryTimeMs -= 5 * 60 * 1000
}
} catch (e: IOException) {
/*
* It's OK to throw exceptions here. The error listeners will receive the
* error thrown here.
*/
throw RuntimeException("Could not get auth token", e)
}
token.tripId = tripId
return token
}
}
}