إعداد مكتبة تتبُّع مجموعة JavaScript

قبل استخدام مكتبة تتبُّع أسطول المركبات باستخدام JavaScript، تأكَّد من أنّك على دراية بخدمة Fleet Engine وأعدّتها. لمعرفة التفاصيل، يُرجى الاطّلاع على Fleet Engine.

يوضّح هذا المستند كيفية تفعيل التفويض بين تطبيق صفحة الويب وFleet Engine. بعد إعداد طلباتك المرسَلة إلى Fleet Engine باستخدام الرموز المميّزة الصحيحة لمنح الأذونات، ستكون مستعدًا لتتبُّع مركبة على الخريطة.

إعداد التفويض

بالنسبة إلى طلبات بيانات واجهة برمجة التطبيقات من البيئات ذات مستوى الثقة المنخفض، تتطلّب أداة Fleet Engine استخدام رموز JSON المميّزة للويب (JWT) التي تم توقيعها من خلال حساب خدمة مناسب. وتشمل البيئات ذات الثقة المنخفضة الهواتف الذكية والمتصفّحات. يبدأ JWT على خادمك، وهو بيئة موثوق بها بالكامل. يتم توقيع ملف JWT وتشفيره ونقله إلى العميل للتفاعلات التالية مع الخادم إلى أن تنتهي صلاحيته أو يصبح غير صالح.

يجب أن تتم مصادقة الخلفية وتفويضها ضد Fleet Engine باستخدام آليات بيانات الاعتماد التلقائية للتطبيق العادية. احرص على استخدام ملفّات JWT التي تم توقيعها من خلال حساب خدمة مناسب. للحصول على قائمة بأدوار حسابات الخدمة، اطّلِع على أدوار حساب خدمة Fleet Engine في أساسيات Fleet Engine.

في المقابل، يجب أن تتم المصادقة والتفويض في الخلفية باستخدام بيانات الاعتماد التلقائية للتطبيق العادية باستخدام آليات 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

مثال: إنشاء أداة جلب رمز مميّز للتفويض

توضِّح الأمثلة التالية كيفية إنشاء أداة جلب رمز مميّز للتفويض:

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,
  };
}

الخطوات التالية

• تتبُّع مركبة
• عرض أسطول