توفّر حزمة تطوير البرامج (SDK) للمستهلك إذن الوصول باستخدام علامات JSON Web Tokens. رمز JSON Web Token (JWT) هو رمز مصادقة يقدّم مطالبة واحدة أو أكثر في خدمة معيّنة.
تستخدِم حزمة تطوير البرامج (SDK) للمستهلك رمز JSON Web Token الذي يقدّمه التطبيق للتواصل مع Fleet Engine. للحصول على تفاصيل عن الرموز المميّزة التي يتوقّعها ملف خادم Fleet Engine، يُرجى الاطّلاع على رموز JSON Web Tokens وإصدار رموز JSON Web Tokens.
يمنح رمز التفويض إمكانية الوصول إلى خدمات Fleet Engine التالية:
TripService
: تمنح حزمة تطوير البرامج (SDK) للمستخدمين إذن الوصول إلى تفاصيل الرحلة، بما في ذلك موقع المركبة ومسارها ووقت الوصول المقدَّر. يجب أن تتضمّن رموز التفويض لخدمة الرحلة مطالبةtripid:TRIP_ID
في عنوانauthorization
الرمز، حيث يكونTRIP_ID
هو معرّف الرحلة التي تتم مشاركتها عند الطلب.
VehicleService
: تقدّم حزمة تطوير البرامج (SDK) للمستهلك معلومات عن الموقع الجغرافي التقريبي للمركبة لعرض طبقة كثافة المركبات وتقدير أوقات الوصول المقدَّرة لنقطة الاستلام. بما أنّ حزمة Consumer SDK لا تستخدم سوى المواقع الجغرافية التقريبية، لا تتطلّب الرموز المميّزة للتفويض لخدمة المركبات تقديم مطالبة بموجبvehicleid
.
ما هو الرمز المميّز؟
تتطلّب أداة Fleet Engine استخدام رموز JSON المميّزة للويب (JWT) لطلبات واجهة برمجة التطبيقات من البيئات ذات مستوى الثقة المنخفض: الهواتف الذكية والمتصفّحات.
يبدأ JWT على خادمك، ويتم توقيعه وتشفيره وتمريره إلى العميل لتفاعلات الخادم اللاحقة إلى أن تنتهي صلاحيته أو لم يعُد صالحًا.
التفاصيل الرئيسية
- استخدِم بيانات الاعتماد التلقائية للتطبيق للمصادقة والحصول على الإذن في Fleet Engine.
- استخدِم حساب خدمة مناسبًا لتوقيع ملفات JWT. اطّلِع على أدوار حساب خدمة Fleet Engine في أساسيات Fleet Engine.
لمزيد من المعلومات عن رموز JSON المميّزة للويب، يُرجى الاطّلاع على رموز JSON المميّزة للويب في أساسيات Fleet Engine.
كيف يحصل العملاء على الرموز المميّزة؟
بعد أن يسجّل السائق أو المستهلك الدخول إلى تطبيقك باستخدام بيانات اعتماد التفويض المناسبة، يجب أن تستخدم أي تعديلات يتم إجراؤها من هذا الجهاز رموزاً مميّزة مناسبة للتفويض، والتي تُرسِل إلى Fleet Engine أذونات التطبيق.
بصفتك مطوِّرًا، يجب أن يتيح لك تنفيذ العميل تنفيذ ما يلي:
- استرِجِع رمز JSON المميّز للويب من خادمك.
- أعِد استخدام الرمز المميّز إلى أن تنتهي صلاحيته لتقليل عمليات إعادة تحميل الرمز المميّز.
- أعِد تحميل الرمز المميّز عند انتهاء صلاحيته.
تنشئ فئة AuthTokenFactory
وحدات ترميز التفويض في وقت تعديل الموقع الجغرافي. يجب أن تحزِّم حزمة SDK الرموز المميّزة مع معلومات التحديث
لإرسالها إلى Fleet Engine. تأكَّد من أنّ التنفيذ على جانب الخادم
يمكنه إصدار الرموز المميّزة قبل إعداد حزمة تطوير البرامج (SDK).
لمعرفة تفاصيل الرموز المميّزة التي تتوقّعها خدمة Fleet Engine، يُرجى الاطّلاع على مقالة إصدار رموّز الويب المميّزة بتنسيق JSON لخدمة Fleet Engine.
مثال على أداة جلب رمز التفويض
يوضِّح مثال الرمز البرمجي التالي كيفية تنفيذ رمز التفويض للاستدعاء.
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
}
}
}