このページは Cloud Translation API によって翻訳されました。

Google ウォレットの Motics チケットの技術的な詳細

このページでは、公共交通機関事業者（PTO）およびシステムインテグレータが Motics チケットを提供するために Google と統合する必要がある。このソリューションは Google Wallet API を利用します。また、アクティベーションエンドポイントを実装しています

システムアーキテクチャ

このセクションでは、システムアーキテクチャと Motics の保存フローについて説明します。

図 1. Motics チケットの保存フロー

図 1 は、Motics チケットを作成、有効化、固定するフローを示しています。 Google ウォレットを複数の事業体で利用可能:

Google サーバー
PTO（システムインテグレータ）サーバー
Motics SCE サーバー
ウェブショップ

以下では、このフローについて詳しく説明します。

初期設定フェーズでは、PTO サーバーは transitClass を作成します。 transitClass:Insert を使用して ownerId と activationUrl を渡す Google Wallet API エンドポイント。これは 1 回限りのアクティビティです。
次に、ユーザーがウェブショップでチケットを購入すると、PTO サーバーが次の呼び出しを行います。 transitObject:Insert には、基本的なチケット発行情報と一部が含まれます。これが Motics チケットであることを示す初期フィールドです。
その後、PTO サーバーとウェブショップが連携して [Google ウォレットに追加] ボタンをクリックし、最終的にチケットの JWT を保存リンクを使用します。
チケットの固定フェーズは、Google サーバーが activationUrl の背後にあるアクティベーションエンドポイント。
ステップ 4 に応答して、PTO サーバーは署名（sigSTB）を生成する（SAM で署名された SCE_ID を含む）。
PTO サーバーは、activationUrl 呼び出しに応答する前に、まず、必要な Motics 情報をすべて含む transitObject:Patch を呼び出します。 Motics の applicationData を含む。
transitObject:Patch 呼び出しが成功した後にのみ、PTO はサーバーが activationUrl に成功（HTTP-200）レスポンスを返す必要があるあります。

ムーブメントとリンク解除のフロー

優れたユーザーエクスペリエンスを提供するため、ユーザーはモーチックを動かせる必要があります。発行元が定義した制限内で、1 つのデバイスから別のデバイスにチケットを転送できます。そのためには、カード発行会社は移動とリンク解除のフローを実装する必要があります。

アクティベーションエンドポイント

カード発行会社/PTO（またはそのシステムインテグレータ）がチケットを実装する必要があるチケットの保存時に Google が呼び出すアクティベーションエンドポイント。URL このエンドポイントへのパスは、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 のサービスに transitClass を作成するための Google Wallet API エンドポイントです。バックエンドです。システムインテグレータは、次のコマンドでこの API を呼び出す必要があります。リクエストパラメータと、該当する他のフィールド。詳しくは、 transitClass と完全なリストについては、transitClass.Insert API ドキュメントをご覧ください。パラメータなどの詳細を確認できます。

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 サーバーは証明書を取得しますダウンロードしますcertEnvironment = Google をステージングする場合サンドボックス Motics サーバーから証明書を取得します。

メソッド: transitObject:insert

これは、新しいアカウントに transitObject を挿入する Google Wallet API エンドポイントです。チケットを発行します。システムインテグレータは、主に次のチケット情報を含む 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 の値がまだ不明の場合、空の文字列を設定する必要があります。
- applicationData は、後で transitObject:Patch で設定されます。あります。
validTimeInterval DateTime オブジェクトにはタイムゾーンオフセットが必要（例: 2024-04-12T19:20:50.52-04:00）。

メソッド: transitObject:patch

これは、対象のデータで transitObject にパッチを適用する Google Wallet API エンドポイントです。 Google が Motics バーコード生成と VDV eTicket サービスの取得に使用する提供します。詳しくは、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,
      },
    },
  }
}

アプリデータの仕様

以下は、 applicationData（タグ:0x5F07）applicationData は、タグ長値（TLV）形式のシステムインテグレータ。このデータは大きなデータ構造にカプセル化され、最終的に QR の一部としてエンコードされるできます。

タグ	長さ	値
`0x9E`	81×80	署名 `OctetString`、署名付き利用資格データの最初の 128 バイト Google の用語: `sigSTB`
`0x9A`	場合によって異なる	残差データ `OctetString`、残りの利用資格データ Google の用語: `sigSTB cont.`
`0x7F21`	81 c8	発行元の証明書 `OctetString`、証明書データ Google の用語: `Cert(puk_SAM)`
`0x42`	08	Certificate Authority Reference（CAR） `OctetString`、CAR 価格 Google の用語: `CAR`

Google ウォレットの Motics チケットの技術的な詳細

システム アーキテクチャ

ムーブメントとリンク解除のフロー

アクティベーション エンドポイント

リクエストする

レスポンス

レイテンシ目標

Google Wallet API の変更点

メソッド: transitClass:insert

JSON 表現

メソッド: transitObject:insert

JSON 表現

メソッド: transitObject:patch

JSON 表現

アプリデータの仕様

システムアーキテクチャ

アクティベーションエンドポイント