التفاصيل الفنية لتذاكر Motics في "محفظة Google"

تقدّم هذه الصفحة التفاصيل الفنية لمشغّل وسائل النقل العام (PTO) إلى الدمج مع Google لتقديم تذاكر Motics في "محفظة Google" يستخدم هذا الحلّ واجهة برمجة تطبيقات "محفظة Google" ويستند أيضًا إلى على تنفيذ نقطة نهاية التنشيط على PTO.

بنية النظام

يعرض هذا القسم بنية النظام وتدفق حفظ Motics.

الشكل 1. مسار حفظ تذكرة Motics

يوضح الشكل 1 تدفق إنشاء تذكرة Motics وتنشيطها وتثبيتها في "محفظة Google" في عدّة كيانات:

• خوادم Google
• خادم شركة تكامل النظام (PTO)
• خادم Motics SCE
• المتجر الإلكتروني

فيما يلي وصف التدفق بمزيد من التفصيل:

1. في مرحلة الإعداد الأولية، ينشئ خادم PTO الخادم transitClass، اجتياز ownerId وactivationUrl باستخدام transitClass:Insert نقطة نهاية Google Wallet API. وهذا نشاط لمرة واحدة.
2. بعد ذلك، عندما يشتري المستخدم تذكرة من متجر الويب، يتصل خادم PTO transitObject:Insert يحتوي على معلومات التذاكر الأساسية وبعض الحقول الأولية التي تشير إلى أن هذه تذكرة Motics.
3. ثم يعمل خادم PTO ومتجر الويب معًا لعرض يمكنك الإضافة إلى "محفظة Google" وإرسال رمز JWT للتذكرة في النهاية إلى Google، باستخدام رابط الحفظ
4. يمكن الآن أن تبدأ مرحلة تثبيت التذاكر، عندما يستدعي خادم Google نقطة نهاية التفعيل بعد activationUrl.
5. استجابة للخطوة 4، ينشئ خادم PTO التوقيع (sigSTB) يحتوي على SCE_ID الموقع من خلال SAM.
6. قبل الاستجابة لاستدعاء activationUrl، يجب أن يبدأ خادم PTO أولاً استدعاء transitObject:Patch يحتوي على جميع معلومات Motics اللازمة بما في ذلك applicationData Motics.
7. فقط بعد نجاح استدعاء transitObject:Patch، لن يظهر رمز PTO أن يعرض الخادم استجابة ناجحة (HTTP-200) إلى خطأ activationUrl الاتصال.

تنفيذ النقل إلغاء ربط التدفق

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

نقطة نهاية التفعيل

على جهة الإصدار/جهة تأسيس التداول (PTO) (أو جهة تكامل النظام) تقديم طلب دعم. نقطة نهاية التفعيل التي ستستدعيها Google عند حفظ التذكرة. عنوان URL إلى نقطة النهاية هذه في الاستدعاء transitClass:Insert. ستنشئ نقطة نهاية التفعيل التوقيع (sigSTB) وتستدعي transitObject:Patch مع المَعلمات المحدَّدة في ما يلي .

ملاحظة مهمة: على خادم PTO (أداة تكامل النظام) استدعاء transitObject:Patch. قبل الرجوع من نقطة نهاية التفعيل.

الطلب

يكون الطلب إلى نقطة نهاية التفعيل بالتنسيق التالي:

Content-Type: application/json
Body: {
  "classId": "123.classId",
  "expTimeMillis": 1669671940735,
  "eventType": "activate",
  "objectId": string - base64 encoded ID of the TransitObject,
  "deviceContext": string - base64 encoded SCE_ID,
}

الرد

يجب عرض استجابة HTTP-200 الناجحة بدون نص في الحالات التالية:

• تم إنشاء ملف sigSTB الذي يحتوي على SCE_ID وتوقيعه باستخدام SAM.
• تم استدعاء طريقةtransitObject:Patch بنجاح

Status: 200 - OK
Body: {}

أهداف وقت الاستجابة

يجب أن تلتزم نقطة نهاية التفعيل بأهداف وقت الاستجابة التالية:

• يجب الرد على 50% على الأقل من كل الطلبات في غضون 200ms
• يجب الرد على 95% على الأقل من كل الطلبات في غضون 2s
• هناك حد أقصى صارم بقيمة 10s

التغييرات في Google Wallet API

في ما يلي توضيح للتغييرات التي طرأت على نقاط نهاية Google Wallet API من أجل على Motics كما هو موضح في بنية النظام.

ملاحظة مهمة: تفترض القيم التالية أنك سبق أن أكملت أحد المعايير. دمج Google Wallet API لا يتم إجراء سوى التحديثات والتغييرات التي تطرأ على نقاط النهاية على تظهر هنا Motics التي نوفّرها.

الطريقة: transitClass:insert

هذه هي نقطة نهاية Google Wallet API لإنشاء transitClass على الخلفية. على جهة دمج النظام استدعاء واجهة برمجة التطبيقات هذه مع ما يلي: معلمات الطلب إلى جانب أي حقول أخرى قابلة للتطبيق. ارجع إلى transitClass مستندات واجهة برمجة التطبيقات transitClass.Insert للاطّلاع على قائمة كاملة المعلمات (غير المختلطة) والمزيد من التفاصيل.

POST: https://walletobjects.googleapis.com/walletobjects/v1/transitClass

تمثيل JSON

يتطلب تكامل Motics تمثيل JSON التالي على الأقل transitClass في نص الطلب transitClass:insert. غير ذلك إلزامي يجب أيضًا ضبط transitClass حقل للبيانات الوصفية.

{
  "id": string,
  "multipleDevicesAndHoldersAllowedStatus": ONE_USER_ONE_DEVICE (MultipleDevicesAndHoldersAllowedStatus),
  "deviceCertificationSupport": {
     "vdvCertDetails": {
        "ownerId" string,
        "certEnvironment": PRODUCTION/STAGING,
      },
  },
  "activationOptions": {
    "activationUrl": string
  },
  ...
}

عندما تكون certEnvironment = PRODUCTION، سيجلب خادم Google الشهادة. من خادم الإنتاج Motics. عندما تكون certEnvironment = "مراقبة نظام Google" الخادم بجلب الشهادة من خادم Motics في وضع الحماية.

الطريقة: transitObject:insert

هذه هي نقطة نهاية Google Wallet API لإدراج transitObject في تذكرة يريد المستخدم شراؤها وإضافتها إلى "محفظة Google". النظام يجب أن تجتاز شركة الدمج transitObject مع تضمين معلومات التذكرة بشكل أساسي في هذه النقطة. يُرجى الرجوع إلى transitObject و واجهة برمجة التطبيقات transitObject.Insert للحصول على قائمة كاملة بالمعلمات (غير المختلطة) والمزيد من التفاصيل.

POST: https://walletobjects.googleapis.com/walletobjects/v1/transitObject

تمثيل JSON

يتطلب تكامل Motics تمثيل JSON التالي على الأقل transitObject في نص الطلب transitObject:insert. كائن آخر يجوز تعيين حقول بيانات التعريف أيضًا، ويجب أيضًا تعيين جميع الحقول الإلزامية .

{
  "id": string,
  "classId": string,
  "validTimeInterval": {
    object (TimeInterval)
  },
  "activationStatus": {
    "state": NOT_ACTIVATED (State)
  },
  "rotatingBarcode": {
    "type": AZTEC (BarcodeType),
    "valuePattern": "{vdv_barcode}",
    "deviceEntitlementSupport": {
      "vdvEntitlementDetails": {
        "applicationData": "",
      },
    },
  },
  ...
}

ملاحظات:

• تتطلب واجهة برمجة التطبيقات تضمين الحقل applicationData. في هذه المرحلة في تدفق تفعيل Motics، تظل قيمة applicationData غير معروفة بعد، لذلك يجب تعيينه على سلسلة فارغة.
  • سيتم ضبط applicationData لاحقًا في transitObject:Patch. الاتصال.
• يجب أن تتضمّن عناصر التاريخ والوقت validTimeInterval معادلة المنطقة الزمنية. المحددة، على سبيل المثال: 2024-04-12T19:20:50.52-04:00.

الطريقة: transitObject:patch

هذه هي نقطة نهاية Google Wallet API لتصحيح transitObject بالبيانات التي يجب تنفيذها. تستخدمه Google لإنشاء الرمز الشريطي في Motics وجلب خدمة VDV eTicket. الشهادات. يُرجى الرجوع إلى transitObject و واجهة برمجة التطبيقات transitObject.Patch للحصول على قائمة كاملة بالمعلمات (غير المختلطة) والمزيد من التفاصيل.

PATCH:
https://walletobjects.googleapis.com/walletobjects/v1/transitObject/{resourceId}

تمثيل JSON

يتطلب تكامل Motics التمثيل التالي transitObject في نص الطلب transitObject:patch. لاحظ أنه في هذا عند تعبئة الحقل applicationData.

ملاحظة: تدعم نقطة نهاية النقلtransitObject:patch دلالات التصحيح، لذلك كافيًا لتضمين المعلومات المحددة التالية فقط عن Motics عند رمز التصحيح.

{
  "activationStatus": {
    "state": ACTIVATED (State)
  },
  "rotatingBarcode": {
    "type": AZTEC (BarcodeType),
    "valuePattern": "{vdv_barcode}",
    "deviceEntitlementSupport": {
      "vdvEntitlementDetails": {
        "applicationData": string - Hex encoded,
      },
    },
  }
}

مواصفات بيانات التطبيق

فيما يلي مواصفات Motics لمحتويات applicationData (العلامة:0x5F07). يجب أن يتم إنشاء applicationData بواسطة وحدة تكامل النظام بتنسيق طول العلامة (TLV). هذه البيانات لاحقًا يتم تغليفها في بنية بيانات أكبر ليتم تشفيرها أخيرًا كجزء من رمز الاستجابة السريعة الرمز.

العلامة	الطول	القيمة
0x9E	81 80	التوقيع OctetString، أول 128 بايت من بيانات الاستحقاق الموقَّعة عبارة Google: sigSTB
0x9A	يختلف	البيانات المتبقية OctetString، بيانات الاستحقاق المتبقية عبارة Google: sigSTB cont.
0x7F21	81 C8	شهادة جهة الإصدار OctetString، بيانات الشهادة عبارة Google: Cert(puk_SAM)
0x42	08	مرجع هيئة إصدار الشهادات (CAR) OctetString، قيمة CAR عبارة Google: CAR