此页面由 Cloud Translation API 翻译。

Google 钱包中 Motics 票券的技术详情

本页提供了公共交通运营商 (PTO) 和他们的系统集成商需要与 Google 集成，才能提供 Motics 服务工单。该解决方案使用 Google Wallet API，在 PTO 上实施激活端点。

系统架构

本部分介绍系统架构和 Motics 保存流程。

图 1. Motics 门票保存流程

图 1 显示了在在多个实体中使用 Google 钱包：

Google 服务器
PTO（系统集成商）服务器
Motics SCE 服务器
网上商店

下文详细介绍了该流程：

在初始设置阶段，PTO 服务器会创建 transitClass，使用 transitClass:Insert 传递 ownerId 和 activationUrl Google Wallet API 端点。这是一项一次性活动。
接下来，当用户从网上商店购买工单时，PTO 服务器会调用 transitObject:Insert，其中包含基本票务信息和一些初始字段，用于指明此是 Motics 票券。
然后，PTO 服务器和网络商店会协同工作 “添加到 Google 钱包”按钮，并最终将票券的 JWT 返回给保存链接
现在，当 Google 服务器调用 activationUrl 后面的激活端点。
为响应第 4 步，PTO 服务器生成签名 (sigSTB) 包含由 SAM 签名的 SCE_ID。
在响应 activationUrl 调用之前，PTO 服务器应首先调用 transitObject:Patch，其中包含所有必要的 Motics 信息，包括 Motics applicationData。
只有在 transitObject:Patch 调用成功后，PTO 才会服务器应向 activationUrl 返回成功 (HTTP-200) 响应调用。

实施动作并解除关联流程

为了提供良好的用户体验，用户应能移动其 Motics 在发卡机构定义的特定限制内，从一台设备到另一台设备。为此，发卡机构必须实现移动和解除关联流程。

激活端点

发行商/PTO（或其系统集成商）需要实现工单保存票券时 Google 将调用的激活端点。网址 transitClass:Insert 方法。激活端点将生成签名 (sigSTB) 并调用 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 成功响应：

包含 SCE_ID 的 sigSTB 已生成并使用 SAM 签名
已成功调用 transitObject:Patch 方法

Status: 200 - OK
Body: {}

延迟时间目标

激活端点应遵守以下延迟时间目标：

所有请求至少有 50% 应在 200ms内得到回复
所有请求至少有 95% 应在 2s内得到回复
硬性上限为 10s

Google Wallet API 的变化

下面概述了对 Google Wallet API 端点进行的更改，支持 Motics（如系统架构中所述）。

方法：transitClass:insert

这是 Google Wallet API 端点，用于在 Google 的transitClass 后端。系统集成商需要使用以下代码调用此 API 请求参数以及任何其他适用的字段。请参阅 transitClass 和transitClass.Insert API 文档，以获取完整的（非 Motics）参数及更多详情。

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

JSON 表示法

Motics 集成至少需要以下 JSON 表示法 transitClass:insert 请求正文中的 transitClass。其他必填项您还需要设置 transitClass 元数据字段。

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

当 certEnvironment = PRODUCTION 时，Google 服务器将提取证书从 Motics 正式版服务器中获取。当 certEnvironment = STAGING Google 服务器将从沙盒 Motics 服务器提取证书。

方法：transitObject:insert

这是 Google Wallet API 端点，用于为新的 transitObject 插入用户想要购买并添加到 Google 钱包的票券。系统集成商应传递一个 transitObject，其中主要包含工单信息，位于。请参阅 transitObject 和transitObject.Insert API （非 Motics）参数完整列表及更多详情的文档。

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

JSON 表示法

Motics 集成至少需要以下 JSON 表示法 transitObject:insert 请求正文中的 transitObject。其他对象还可以设置元数据字段，还应设置所有其他必填字段包括在内。

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

注意：

该 API 要求包含 applicationData 字段。此时在 Motics 激活流程中，applicationData 值尚不已知，因此必须设为空字符串
- 稍后在 transitObject:Patch 中设置 applicationData 调用。
validTimeInterval DateTime 对象必须具有时区偏移量例如 2024-04-12T19:20:50.52-04:00。

方法：transitObject:patch

这是 Google Wallet API 端点，用于为 transitObject 修补 Google 使用它生成 Motics 条形码和提取 VDV 电子票券服务证书。请参阅 transitObject 和transitObject.Patch API （非 Motics）参数完整列表及更多详情的文档。

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

JSON 表示法

Motics 集成需要以下表示 transitObject:patch 请求正文中的 transitObject。请注意，它在这里表示已填充 applicationData 字段。

{
  "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`