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

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

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

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

التفاصيل الأساسية

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

عناصر JWT

تحتوي رموز 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، يجب أن يكون نطاق التفويض مصفوفة بأحد الأشكال التالية:

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

أو

"taskids": ["*"]

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

تستخدم Fleet Engine مطالبات خاصة. يضمن استخدام المطالبات الخاصة ألا يتمكّن من الوصول إلى البيانات إلا العملاء المصرّح لهم.

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

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

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

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

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

  • deliveryvehicleid

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

  • taskid

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

  • taskids

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

  • trackingid

    يجب استخدامها عند استدعاء GetTaskTrackingInfoAPI. يجب أن يتطابق الطلب مع معرّف التتبُّع في الطلب. لا تتضمّن ادعاءات delivervehicleid أو taskid أو taskids.

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