قبل استخدام مكتبة تتبُّع أسطول المركبات باستخدام JavaScript، تأكَّد من أنّك على دراية بخدمة Fleet Engine وأعدّتها. لمعرفة التفاصيل، يُرجى الاطّلاع على Fleet Engine.
يوضح هذا المستند كيفية تمكين التفويض بين تطبيق صفحة الويب وFleet Engine. بعد إعداد طلباتك المرسَلة إلى Fleet Engine باستخدام الرموز المميّزة الصحيحة لمنح الأذونات، ستكون مستعدًا لتتبُّع مركبة على الخريطة.
إعداد التفويض
بالنسبة إلى طلبات بيانات واجهة برمجة التطبيقات من البيئات ذات مستوى الثقة المنخفض، تتطلّب أداة Fleet Engine استخدام رموز JSON المميّزة للويب (JWT) التي تم توقيعها من خلال حساب خدمة مناسب. وتشمل البيئات منخفضة الثقة الهواتف الذكية والمتصفحات. يبدأ JWT على خادمك، وهو بيئة موثوق بها بالكامل. يتم توقيع JWT وتشفيره وتمريره إلى العميل لإجراء تفاعلات لاحقة مع الخادم حتى تنتهي صلاحيته أو لا يصبح صالحًا.
يجب أن تتم المصادقة والتفويض ضد Fleet Engine باستخدام آليات بيانات الاعتماد التلقائية للتطبيقات العادية. احرص على استخدام ملفّات JWT التي تم توقيعها من خلال حساب خدمة مناسب. للحصول على قائمة بأدوار حساب الخدمة، يُرجى الاطّلاع على أدوار حساب خدمة Fleet Engine في Fleet Engine Basics.
في المقابل، يجب أن تتم المصادقة والتفويض ضد Fleet Engine باستخدام آليات بيانات الاعتماد التلقائية للتطبيق العادية.
كيف يعمل التفويض؟
يشمل التفويض باستخدام بيانات Fleet Engine تنفيذًا من جهة العميل والخادم معًا.
التفويض من جهة الخادم
قبل إعداد المصادقة والتفويض في تطبيق تتبُّع مركبات الأسطول، يجب أن يكون خادم الخلفية قادرًا على إصدار رموز الويب المميّزة بتنسيق JSON إلى تطبيق تتبُّع مركبات الأسطول للوصول إلى Fleet Engine. يرسل تطبيق تتبع الأسطول هذه الملفات JWT مع طلباته حتى يتعرف Fleet Engine على الطلبات كتمت مصادقتها ومصرّح بها بالوصول إلى البيانات الواردة في الطلب. للحصول على تعليمات حول تنفيذ JWT من جهة الخادم، اطّلِع على إصدار رموّز الويب المميّزة JSON ضمن أساسيات Fleet Engine.
لإنشاء الرموز المميّزة من خادمك عند تنفيذ ميزة تتبُّع الأسطول، اطّلِع على الخطوات التالية:- الإرشادات العامة لإصدار رموز الويب المميّزة JSON، بما في ذلك أقسام لكلّ من الرحلات عند الطلب والمهام المُجدوَلة
- الرحلات عند الطلب: مثال على رمز مميّز لعملية خادم في الخلفية
- المهام المُجدوَلة: مثال على رمز مميّز لتتبُّع جميع المهام والمركبات في الأسطول
التفويض من جهة العميل
عند استخدام مكتبة تتبُّع الأسطول في JavaScript، تطلب المكتبة رمز مميّزًا من الخادم باستخدام أداة جلب رمز مميّز التفويض. ويتم ذلك في حال استيفاء أيٍّ من المتطلّبات التالية:
ولا يتوفّر رمز مميّز صالح، مثلاً في حال لم يستدعي حزمة تطوير البرامج (SDK) برنامج الجلب عند تحميل صفحة جديدة أو لا يعرض برنامج الجلب مع رمز مميّز.
انتهت صلاحية الرمز المميّز.
ستنتهي صلاحية الرمز المميّز خلال دقيقة واحدة.
بخلاف ذلك، تستخدم مكتبة تتبُّع الأسطول في JavaScript الرمز المميّز الصالح الذي تم إصداره سابقًا ولا تستدعي أداة الجلب.
إنشاء برنامج لاسترجاع الرمز المميّز للتفويض
يمكنك إنشاء أداة استرجاع الرمز المميّز للتفويض باتّباع الإرشادات التالية:
يجب أن يعرض أداة الجلب بنية بيانات تتضمّن حقلَين، يتم تضمينهما في علامة
Promiseعلى النحو التالي:سلسلة
token.رقم
expiresInSecondsوتنتهي صلاحية الرمز المميز خلال هذه المدة من الوقت بعد استرجاعه. ويجب أن يمرّ وقت انتهاء الصلاحية بالثواني من وقت استرجاعه إلى المكتبة كما هو موضّح في المثال.
يجب أن يستدعي برنامج الجلب عنوان URL على خادمك لاسترداد رمز مميز. يعتمد عنوان URL هذا، وهو
SERVER_TOKEN_URL، على عملية التنفيذ في الخلفية. مثال عنوان URL التالي مخصص لنموذج واجهة التطبيق الخلفية على GitHub:https://SERVER_URL/token/fleet_reader
مثال: إنشاء أداة جلب رمز مميّز للتفويض
توضِّح الأمثلة التالية كيفية إنشاء أداة جلب رمز مميّز للتفويض:
JavaScript
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
};
}
TypeScript
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,
};
}