الحصول على الرموز المميّزة للتفويض

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

تستخدِم حزمة Consumer SDK رمز JSON المميّز للويب الذي يقدّمه التطبيق للقيام بالاتصال بـ Fleet Engine. لمعرفة تفاصيل الرموز التي يتوقعها خادم Fleet Engine، يُرجى الاطّلاع على رموز JSON المميّزة للويب وإصدار رموز JSON المميّزة للويب.

يمنح رمز التفويض إمكانية الوصول إلى خدمات Fleet Engine التالية:

• ‫TripService: تمنح حزمة SDK للمستخدمين إذن الوصول إلى تفاصيل الرحلة، بما في ذلك موقع المركبة ومسارها ووقت الوصول المقدَّر. يجب أن تتضمّن علامات التفويض لخدمة الرحلة ادعاء tripid:TRIP_ID في عنوان authorization للرمز المميّز، حيث يكون TRIP_ID هو رقم تعريف الرحلة عند الطلب التي تتم مشاركتها.

• ‫VehicleService: تقدّم حزمة SDK للمستهلك معلومات عن الموقع الجغرافي التقريبي للمركبة لعرض طبقة كثافة المركبات وتقدير أوقات الوصول المقدَّرة لنقطة الاستلام. بما أنّ حِزم تطوير البرامج (SDK) للمستهلك لا تستخدم سوى مواقع جغرافية تقريبية، لا تتطلّب رموز التفويض للخدمة المتعلقة بالمركبة تقديم مطالبة بموجب اتفاقية vehicleid.

ما هو الرمز المميّز؟

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

يجب أن تتم مصادقة الخلفية وتفويضها ضد Fleet Engine باستخدام آليات بيانات الاعتماد التلقائية للتطبيق العادية. احرص على استخدام ملفّات JWT التي تم توقيعها من خلال حساب خدمة مناسب. للاطّلاع على قائمة بأدوار حسابات الخدمة، راجِع أدوار حساب خدمة Fleet Engine في أساسيات 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
    }
  }
}

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

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