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

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

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

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

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

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

عناصر JWT

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

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

حقول عنوان JWT

الحقل

الوصف

alg

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

typ

نوع الرمز. `JWT`.

طفلة

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

الحقل

الوصف

إيس

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

sub

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

أودي

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.

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