رموز JSON المميّزة للويب

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

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

يبدأ JWT على خادمك، ويتم توقيعه وتشفيره وتمريره إلى العميل لتفاعلات الخادم اللاحقة إلى أن تنتهي صلاحيته أو لم يعُد صالحًا.

التفاصيل الرئيسية

على عكس مفاتيح واجهة برمجة التطبيقات، تكون مدة صلاحية ملفات JWT قصيرة وتقتصر العمليات على العمليات التي يُسمح للدور بتنفيذها فقط. لمزيد من المعلومات عن رموز JWT، يُرجى الاطّلاع على مقالة رموز JSON المميّزة للويب على Wikipedia. لمعرفة التفاصيل حول أدوار الوصول، يُرجى الاطّلاع على أدوار حسابات الخدمة في هذا الدليل.

عناصر رمز JSON المميّز على الويب

تحتوي الرموز المميّزة JWT على قسمَي العنوان والمطالبة. يحتوي قسم العنوان على معلومات، مثل المفتاح الخاص الذي تم الحصول عليه من حسابات الخدمة، و خوارزمية التشفير. يحتوي قسم المطالبة على معلومات، مثل وقت إنشاء ملف JWT ومدة صلاحيته والخدمات التي يطالب ملف JWT بالوصول إليها ومعلومات التفويض الأخرى لنطاق الوصول، على سبيل المثال، رقم تعريف مركبة التسليم.

يوفّر الجدول التالي تفاصيل وصفية عن حقول JWT بشكل عام، بالإضافة إلى معلومات محدّدة عن الأماكن التي يمكنك العثور فيها على قيم هذه الحقول في مشروع Fleet Engine Cloud.

حقول رأس رمز JSON المميّز على الويب

الحقل

الوصف

alg

الخوارزمية المُراد استخدامها ‫`RS256`.

typ

نوع الرمز المميّز ‫`JWT`

طفلة

معرّف المفتاح الخاص لحساب الخدمة. يمكنك العثور على هذه القيمة في حقل private_key_id من ملف JSON الخاص بحساب الخدمة. احرص على استخدام مفتاح من حساب خدمة يتضمّن المستوى الصحيح من الأذونات.
حقول بيانات JWT

الحقل

الوصف

iss

عنوان البريد الإلكتروني لحساب الخدمة، والذي يمكن العثور عليه في الحقل client_email من ملف JSON الخاص بحساب الخدمة.

sub

عنوان البريد الإلكتروني لحساب الخدمة، والذي يمكن العثور عليه في الحقل client_email من ملف JSON الخاص بحساب الخدمة.

AUD

SERVICE_NAME لحساب الخدمة، في هذه الحالة https://fleetengine.googleapis.com/

iat

الطابع الزمني لإنشاء JWT، ويتم تحديده بالثواني مرّ عليه 00:00:00 UTC, January 1, 1970. يُرجى الانتظار لمدة 10 دقائق حتى يتم تطبيق الانحراف. إذا كان الطابع الزمني في وقت بعيد جدًا في الماضي أو في المستقبل، قد يُبلغ الخادم عن خطأ.

exp

الطابع الزمني عند انتهاء صلاحية JWT، ويتم تحديده بالثواني التي مرت منذ 00:00:00 UTC, January 1, 1970. لا يتم تنفيذ الطلب إذا كان الطابع الزمني بعد أكثر من ساعة في المستقبل.

السماح

استنادًا إلى حالة الاستخدام، قد يحتوي على deliveryvehicleid أو trackingid أو taskid أو taskids.

في حال تحديد معرّفات المهام، يجب أن يكون نطاق التفويض مصفوفة في أحد الأشكال التالية:

"taskids": ["task_id_one","task_id_two"]

أو

"taskids": ["*"]

مطالبات رمز JWT في Fleet Engine

يستخدم Fleet Engine المطالبات الخاصة. يضمن استخدام المطالبات الخاصة إمكانية وصول العميل المفوَّض فقط إلى بياناته.

على سبيل المثال، عندما يُصدر خادمك رمز أمان ويب بتنسيق JSON لجهاز جوّال سائق، يجب أن يحتوي على مطالبة vehicleid أو مطالبة deliveryvehicleid مع قيمة معرّف مركبة هذا السائق. بعد ذلك، استنادًا إلى دور السائق، لا تسمح ملفات JWT بالوصول إلا إلى رقم تعريف المركبة المحدّد وليس أي رقم تعريف عشوائي آخر للمركبة.

يستخدم Fleet Engine المطالبات الخاصة التالية:

الرحلات عند الطلب

  • vehicleid:
    • تستخدم حزمة Driver SDK هذه المطالبة دائمًا، سواء كانت تعمل على رحلة أو مركبة. تضمن الخلفية في Fleet Engine أنّ المركبة مرتبطة بالرحلة المطلوبة قبل إجراء التعديل.
    • يمكن أن يشمل رمز JWT عمليات المركبات والرحلات ، حتى إذا لم يكن ذلك مطلوبًا، ما قد يسهّل تنفيذ توقيع JWT.
  • tripid:
    • تستخدم حزمة Consumer SDK هذه المطالبة دائمًا.
    • يمكن أن يشمل رمز JWT عمليات المركبات والرحلات، حتى إذا لم يكن ذلك مطلوبًا، ما قد يسهّل تنفيذ توقيع الرمز المميّز.

المهام المُجدوَلة

  • deliveryvehicleid

    استخدِم هذا المقياس عند الاتصال بواجهات برمجة التطبيقات الخاصة بكل مركبة تسليم.

  • taskid

    استخدِم هذا الإجراء عند طلب بيانات من واجهات برمجة التطبيقات لكل مهمة.

  • taskids

    استخدِم الرقم عند الاتصال بـ BatchCreateTasksAPI. يجب أن تكون هذه المطالبة في شكل صفيف، ويجب أن يحتوي الصفيف على جميع أرقام تعريف المهام اللازمة لإكمال الطلب. لا تُدرِج مطالبات delivervehicleid أو trackingid أو taskid.

  • trackingid

    استخدِم هذا الرمز عند الاتصال بالرقم GetTaskTrackingInfoAPI. يجب أن تتطابق المطالبة مع رقم تعريف التتبُّع في الطلب. لا تُدرِج مطالبات delivervehicleid أو taskid أو taskids.

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