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

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

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

يجب أن تتم مصادقة ومنح الأذونات من خلال الخلفية في Fleet Engine باستخدام آليات بيانات الاعتماد التلقائية للتطبيق العادية. احرص على استخدام ملفّات JWT التي تم توقيعها من خلال حساب خدمة مناسب. للاطّلاع على قائمة بأدوار حسابات الخدمة، اطّلِع على أدوار حساب خدمة Fleet Engine في أساسيات Fleet Engine.

في المقابل، يجب أن تتم المصادقة والتفويض في الخلفية باستخدام بيانات الاعتماد التلقائية للتطبيق العادية باستخدام آليات Fleet Engine.

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

عناصر رمز 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": ["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.

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