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

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

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

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

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

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

عناصر JWT

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

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

حقول عناوين JWT

الحقل

الوصف

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.

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