توکن های مجوز را دریافت کنید

کیت توسعه نرم‌افزار مصرف‌کننده (Consumer SDK) با استفاده از توکن‌های وب JSON، مجوزدهی را فراهم می‌کند. توکن وب JSON (JWT) یک توکن مجوزدهی است که یک یا چند درخواست (Claim) را در مورد یک سرویس ارائه می‌دهد.

کیت توسعه نرم‌افزار مصرف‌کننده (Consumer SDK) از JSON Web Token ارائه شده توسط برنامه برای ارتباط با Fleet Engine استفاده می‌کند. برای جزئیات توکن‌های مورد انتظار سرور Fleet Engine، به JSON Web Tokens و Issue JSON Web Tokens مراجعه کنید.

توکن مجوز، دسترسی به سرویس‌های Fleet Engine زیر را فراهم می‌کند:

  • TripService - به Consumer SDK دسترسی به جزئیات سفر، از جمله موقعیت وسیله نقلیه، مسیر و ETA را می‌دهد. توکن‌های مجوز برای سرویس سفر باید شامل یک درخواست tripid:TRIP_ID در سربرگ authorization توکن باشند، که در آن TRIP_ID شناسه سفر درخواستی به اشتراک گذاشته شده است.

  • VehicleService - به Consumer SDK اطلاعات مربوط به موقعیت تقریبی وسیله نقلیه را برای نمایش لایه تراکم وسیله نقلیه و تخمین ETA های نقطه تحویل می‌دهد. از آنجا که Consumer SDK فقط از موقعیت‌های تقریبی استفاده می‌کند، توکن‌های مجوز برای سرویس وسیله نقلیه نیازی به ادعای vehicleid ندارند.

توکن چیست؟

موتور ناوگان (Fleet Engine) برای فراخوانی متدهای API از محیط‌های کم‌اعتماد (مثل تلفن‌های هوشمند و مرورگرها) نیاز به استفاده از توکن‌های وب JSON (JWT) دارد.

یک JWT از سرور شما سرچشمه می‌گیرد، امضا و رمزگذاری می‌شود و برای تعاملات بعدی با سرور به کلاینت ارسال می‌شود تا زمانی که منقضی شود یا دیگر معتبر نباشد.

جزئیات کلیدی

برای اطلاعات بیشتر در مورد JSON Web Tokens، به JSON Web Tokens در Fleet Engine Essentials مراجعه کنید.

مشتریان چگونه توکن دریافت می‌کنند؟

به محض اینکه راننده یا مصرف‌کننده با استفاده از اعتبارنامه‌های مجوز مناسب وارد برنامه شما می‌شود، هرگونه به‌روزرسانی که از آن دستگاه صادر می‌شود باید از توکن‌های مجوز مناسب استفاده کند که مجوزهای برنامه را به Fleet Engine منتقل می‌کند.

به عنوان توسعه‌دهنده، پیاده‌سازی کلاینت شما باید قابلیت انجام موارد زیر را فراهم کند:

  • یک JSON Web Token از سرور خود دریافت کنید.
  • برای به حداقل رساندن به‌روزرسانی‌های توکن، از توکن تا زمان انقضای آن مجدداً استفاده کنید.
  • وقتی توکن منقضی شد، آن را به‌روزرسانی کنید.

کلاس AuthTokenFactory توکن‌های مجوز را در زمان به‌روزرسانی موقعیت مکانی تولید می‌کند. SDK باید توکن‌ها را به همراه اطلاعات به‌روزرسانی بسته‌بندی کند تا به Fleet Engine ارسال شود. قبل از مقداردهی اولیه SDK، مطمئن شوید که پیاده‌سازی سمت سرور شما می‌تواند توکن‌ها را صادر کند.

برای جزئیات توکن‌های مورد انتظار سرویس Fleet Engine، به بخش صدور توکن‌های وب JSON برای Fleet Engine مراجعه کنید.

مثالی از یک دریافت‌کننده‌ی توکن مجوز

مثال کد زیر نحوه پیاده‌سازی فراخوانی توکن مجوز (authorization token callback) را نشان می‌دهد.

جاوا

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

کاتلین

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 مصرف‌کننده