إعداد "حزمة تطوير البرامج (SDK) للمستهلكين" بلغة JavaScript

باستخدام حزمة تطوير البرامج (SDK) الخاصة بمستهلك JavaScript، يمكن لتطبيق المستهلك عرض موقع المركبات والمواقع الأخرى ذات الأهمية التي يتم تتبعها في Fleet Engine على أساس الويب الخريطة. يتيح ذلك للمستخدمين الاطلاع على مدى تقدم شحناتهم. يفترض هذا الدليل أنك أعددت Fleet Engine بالجهاز المرتبط به مشروع Google Cloud ومفاتيح واجهة برمجة التطبيقات راجِع Fleet Engine للاطّلاع على التفاصيل.

يمكنك إعداد حزمة تطوير البرامج (SDK) لإصدار JavaScript المخصّص للمستهلكين باتّباع الخطوات التالية:

1. فعِّل واجهة برمجة التطبيقات Maps JavaScript API.
2. إعداد التفويض

تفعيل واجهة برمجة تطبيقات JavaScript للخرائط

فعِّل واجهة برمجة التطبيقات Maps JavaScript API في مشروع Google Cloud Console الذي تستخدمه لمثيل Fleet Engine. لمزيد من التفاصيل، يُرجى الاطّلاع على تفعيل واجهات برمجة التطبيقات في مستندات JavaScript API للخرائط

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

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

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

من المفترض أن يصادق تطبيق المستهلك لديك من خلال دور واحد (delivery_consumer) من مشروعك على Google Cloud يمكن عرضه فقط الخاصة بالمستهلك. بهذه الطريقة، يعمل Fleet Engine على فلترة جميع والمعلومات الأخرى في الردود. على سبيل المثال، أثناء مهمة عدم التوفّر، لا تتم مشاركة أي معلومات عن الموقع الجغرافي مع المستخدم النهائي. اطّلِع على دوار حساب الخدمة للمهام المجدوَلة.

في المقابل، يجب أن تتم المصادقة والتفويض في الخلفية باستخدام بيانات الاعتماد التلقائية للتطبيق المعمول بها في Fleet Engine .

كيف يعمل التفويض؟

يشمل التفويض باستخدام بيانات Fleet Engine تنفيذًا من جهة العميل والخادم معًا.

التفويض من جهة الخادم

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

على وجه التحديد، يُرجى تذكُّر ما يلي بالنسبة إلى حزمة تطوير البرامج (SDK) الخاصة بمستهلكي JavaScript تتبع الشحنات:

• الإرشادات العامة لإصدار الرموز المميّزة للويب JSON
• إرشادات JWT للمهام المُجدوَلة
• مثال على رمز مميّز لتطبيق للمستهلك

التفويض من جهة العميل

عند استخدام حزمة JavaScript Consumer SDK، تطلب الحزمة رمزًا مميزًا من الخادم باستخدام أداة جلب رمز التفويض. ويتم ذلك في حال استيفاء أيٍّ من المتطلّبات التالية:

• ولا يتوفّر رمز مميّز صالح، كما هو الحال عندما لا تستدعي حزمة تطوير البرامج (SDK) أداة الجلب في تحميل صفحة جديدة أو في حال عدم عرض برنامج الجلب مع رمز مميّز.

• انتهت صلاحية الرمز المميّز.

• ستنتهي صلاحية الرمز المميّز خلال دقيقة واحدة.

بخلاف ذلك، تستخدم "حزمة تطوير البرامج (SDK) للمستهلكين في JavaScript" رمزًا مميّزًا صالحًا تم إصداره سابقًا ولا واستدعاء برنامج الجلب.

إنشاء أداة جلب رمز مميّز لمنح الأذونات

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

• يجب أن يعرض برنامج الجلب بنية بيانات من حقلين، ملفوفين في Promise على النحو التالي:

  • سلسلة token.

  • رقم expiresInSeconds تنتهي صلاحية الرمز المميز خلال هذه المدة الزمنية بعد الجلب. يجب أن يجتاز برنامج استرجاع الرمز المميّز للمصادقة تاريخ انتهاء الصلاحية. الوقت بالثواني، بدءًا من وقت الجلب إلى المكتبة كما هو موضّح في المثال.

• يجب أن يستدعي برنامج الجلب عنوان URL على خادمك لاسترداد رمز مميز. هذا النمط يعتمد عنوان URL SERVER_TOKEN_URL على التنفيذ في الخلفية. تشير رسالة الأشكال البيانية فيما يلي مثال على عنوان URL لنموذج واجهة التطبيق على GitHub:

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

مثال: إنشاء برنامج لاسترجاع الرمز المميّز للمصادقة

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

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

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

• متابعة شحنة