رموز 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:
- تستخدم حزمة Consumer SDK هذا الادّعاء دائمًا.
-
يمكن أن يغطي رمز JWT عمليات المركبة والرحلة، حتى إذا لم يكن ذلك مطلوبًا، ما قد يسهّل عملية تنفيذ توقيع الرمز المميّز.
المهام المُجدوَلة
-
deliveryvehicleid
يُستخدَم عند طلب بيانات من واجهات برمجة التطبيقات الخاصة بكل مركبة توصيل.
-
taskid
يجب استخدامها عند طلب بيانات من واجهات برمجة التطبيقات الخاصة بكل مهمة.
-
taskids
استخدِم هذا الرقم عند الاتصال بـ BatchCreateTasksAPI. يجب أن يكون هذا الادعاء في شكل مصفوفة، ويجب أن تحتوي المصفوفة على جميع أرقام تعريف المهام اللازمة لإكمال الطلب. لا تتضمّن ادعاءات delivervehicleid أو trackingid أو taskid.
-
trackingid
يجب استخدامها عند الاتصال بالرقم GetTaskTrackingInfoAPI. يجب أن يتطابق الطلب مع معرّف التتبُّع في الطلب. لا تتضمّن ادعاءات delivervehicleid أو taskid أو taskids.
الخطوات التالية
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eJSON Web Tokens (JWTs) are required for API calls to Fleet Engine from low-trust environments like smartphones and browsers, providing authentication and authorization.\u003c/p\u003e\n"],["\u003cp\u003eJWTs are digitally signed by a service account on your server, a trusted environment, and passed to the client for secure communication with Fleet Engine.\u003c/p\u003e\n"],["\u003cp\u003eJWTs contain header and claim sections with information about the private key, encryption algorithm, token lifespan, and authorized access scopes like vehicle or trip IDs.\u003c/p\u003e\n"],["\u003cp\u003eFleet Engine utilizes private claims within JWTs to ensure data security and limit access to specific resources based on assigned roles and vehicle or task IDs.\u003c/p\u003e\n"],["\u003cp\u003eUnlike API keys, JWTs are short-lived and restrict operations to those permitted by the associated service account role, enhancing security.\u003c/p\u003e\n"]]],[],null,["# JSON Web Tokens\n\nA JSON Web Token (JWT) is an open web standard that's used for authenticating\nand authorizing information exchanges between a client and a server. When an app\nuser first signs in with the appropriate role credentials, the server creates\nand returns an encoded, digitally-signed JWT for use with subsequent requests.\nThis process both authenticates the user and authorizes them to access routes,\nservices, and resources based on their account role.\n\nFleet Engine requires the use of **JSON Web Tokens** (JWTs) for API method calls\nfrom **low-trust environments**: smartphones and browsers.\n\nA JWT originates on your server, is signed, encrypted, and passed to the client\nfor subsequent server interactions until it expires or is no longer valid.\n\n**Key details**\n\n- Use [Application Default Credentials](https://google.aip.dev/auth/4110) to authenticate and authorize against Fleet Engine.\n- Use an appropriate service account to sign JWTs. See [Fleet Engine serviceaccount](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts#fleet_engine_service_account_roles) roles in **Fleet Engine Basics**.\n\nUnlike API keys, JWTs are short lived and limit operations to only those that\nthe role is authorized to perform. For more information on JWTs, see\n[JSON Web Tokens](https://en.wikipedia.org/wiki/JSON_Web_Token) on Wikipedia. For detail on access roles, see\n[Service account roles](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts) in this guide.\n\nJWT elements\n------------\n\nJWTs contain a header and a claim section. The header section contains\ninformation such as the private key obtained from service accounts, and the\nencryption algorithm. The claim section contains information such as the JWT's\ncreate time, time to live, the services that the JWT claims\naccess to, and other authorization information to scope access; for\nexample, the delivery vehicle ID.\n\nThe following table provides descriptive details about JWT fields in general,\nas well as specific information about where you can find the values for these\nfields in your Fleet Engine Cloud project.\n\n| **Field** | **Description** |\n|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| alg | The algorithm to use. \\`RS256\\`. |\n| typ | The type of token. \\`JWT\\`. |\n| kid | Your service account's private key ID. You can find this value in the `private_key_id` field of your service account JSON file. Make sure to use a key from a service account with the correct level of permissions. |\n[JWT header fields]\n\n| **Field** | **Description** |\n|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| iss | Your service account's email address, found in the `client_email` field of your service account JSON file. |\n| sub | Your service account's email address, found in the `client_email` field of your service account JSON file. |\n| aud | Your service account's `SERVICE_NAME`, in this case `https://fleetengine.googleapis.com/` |\n| iat | The timestamp when the JWT was created, specified in seconds elapsed since 00:00:00 `UTC, January 1, 1970`. Allow 10 minutes for skew. If the timestamp is too far in the past, or in the future, the server might report an error. |\n| exp | The timestamp when the JWT expires, specified in seconds elapsed since `00:00:00 UTC, January 1, 1970`. The request fails if the timestamp is more than one hour in the future. |\n| authorization | Depending on the use case, may contain `deliveryvehicleid`, `trackingid`, `taskid`, or `taskids`. If specifying taskids, the authorization scope must be an array in one of the following forms: `\"taskids\": [\"task_id_one\",\"task_id_two\"]` or `\"taskids\": [\"*\"]` |\n[JWT claims fields]\n\n### Fleet Engine JWT claims\n\nFleet Engine uses private claims. Using private claims ensures that only\nauthorized clients can access their own data.\n\nFor example, when your server issues a JSON Web Token for a driver's mobile\ndevice, it should contain either the `vehicleid` claim or the\n`deliveryvehicleid` claim with the value of that driver's vehicle ID. Then,\ndepending on the driver role, JWTs enable access only for the specific vehicle\nID and not any other arbitrary vehicle ID.\n\nFleet Engine uses the following private claims: \n\n### On-demand trips\n\n- **`vehicleid`** :\n - The Driver SDK always uses this claim, whether operating on a trip or vehicle. The Fleet Engine backend assures that the vehicle is associated with the requested trip before doing the modification.\n - The JWT can cover both vehicle and trip operations, even if not required, which may simplify the JWT signing implementation.\n- **`tripid`** :\n - The Consumer SDK always uses this claim.\n - The JWT can cover both vehicle and trip operations, even if not required, which may simplify the token signing implementation.\n\n### Scheduled tasks\n\n- `deliveryvehicleid`\n\n Use when calling per-delivery-vehicle\n APIs.\n- `taskid`\n\n Use when calling per-task APIs.\n- `taskids`\n\n Use when calling\n `BatchCreateTasksAPI`. This claim must be in array form,\n and the array should contain all task IDs necessary to complete the\n request. Don't include `delivervehicleid`,\n `trackingid`, or `taskid` claims.\n- `trackingid`\n\n Use when calling the\n `GetTaskTrackingInfoAPI`. The claim must match the tracking\n ID in the request. Don't include `delivervehicleid`,\n `taskid`, or `taskids` claims.\n\nWhat's next\n-----------\n\n- Read about [Fleet Engine security design](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/security-design) to understand the complete authentication flow.\n- Learn how to [Issue JSON Web Tokens](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/issue-jwt) from your server."]]
