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

توفّر حزمة تطوير البرامج (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 Essentials.

كيف يحصل العملاء على الرموز المميزة؟

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

بصفتك مطوّرًا، يجب أن يتيح لك تنفيذ العميل تنفيذ ما يلي:

  • أحضر رمز JSON المميّز للويب (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) للمستهلكين