REST Resource: transitobject

資源：TransitObject

JSON 表示法 
{
  "classReference": {
    object (TransitClass)
  },
  "ticketNumber": string,
  "passengerType": enum (PassengerType),
  "passengerNames": string,
  "tripId": string,
  "ticketStatus": enum (TicketStatus),
  "customTicketStatus": {
    object (LocalizedString)
  },
  "concessionCategory": enum (ConcessionCategory),
  "customConcessionCategory": {
    object (LocalizedString)
  },
  "ticketRestrictions": {
    object (TicketRestrictions)
  },
  "purchaseDetails": {
    object (PurchaseDetails)
  },
  "ticketLeg": {
    object (TicketLeg)
  },
  "ticketLegs": [
    {
      object (TicketLeg)
    }
  ],
  "hexBackgroundColor": string,
  "tripType": enum (TripType),
  "id": string,
  "classId": string,
  "version": string,
  "state": enum (State),
  "barcode": {
    object (Barcode)
  },
  "messages": [
    {
      object (Message)
    }
  ],
  "validTimeInterval": {
    object (TimeInterval)
  },
  "locations": [
    {
      object (LatLongPoint)
    }
  ],
  "hasUsers": boolean,
  "smartTapRedemptionValue": string,
  "hasLinkedDevice": boolean,
  "disableExpirationNotification": boolean,
  "infoModuleData": {
    object (InfoModuleData)
  },
  "imageModulesData": [
    {
      object (ImageModuleData)
    }
  ],
  "textModulesData": [
    {
      object (TextModuleData)
    }
  ],
  "linksModuleData": {
    object (LinksModuleData)
  },
  "appLinkData": {
    object (AppLinkData)
  },
  "activationStatus": {
    object (ActivationStatus)
  },
  "rotatingBarcode": {
    object (RotatingBarcode)
  },
  "deviceContext": {
    object (DeviceContext)
  },
  "heroImage": {
    object (Image)
  },
  "groupingInfo": {
    object (GroupingInfo)
  },
  "passConstraints": {
    object (PassConstraints)
  },
  "saveRestrictions": {
    object (SaveRestrictions)
  },
  "linkedObjectIds": [
    string
  ],
  "notifyPreference": enum (NotificationSettingsForUpdates),
  "valueAddedModuleData": [
    {
      object (ValueAddedModuleData)
    }
  ],
  "merchantLocations": [
    {
      object (MerchantLocation)
    }
  ]
}
欄位
classReference

object (TransitClass)

父項類別的沿用欄位副本。這類欄位是在 GET 執行期間所擷取。
ticketNumber

string

票券的編號。這是大眾運輸業者系統中的票券專屬 ID。
passengerType

enum (PassengerType)

乘客人數。
passengerNames

string

該票券指派的乘客姓名。上述 passengerType 欄位是用來提供此欄位的 Google 背景資訊。
tripId

string

如果使用者儲存了同趟旅程的多張票券，系統會使用此 ID 將票券分組。
ticketStatus

enum (TicketStatus)

票券的狀態。如果狀態會影響顯示情形，請改用 state 欄位。
customTicketStatus

object (LocalizedString)

ticketStatus 未提供正確選項時，要用於票券狀態值的自訂狀態。ticketStatus 和 customTicketStatus 都可不予設定。
concessionCategory

enum (ConcessionCategory)

票券的優待票類別。
customConcessionCategory

object (LocalizedString)

concessionCategory 未提供正確選項時，要使用的自訂優待票類別。concessionCategory 和 customConcessionCategory 都可不予設定。
ticketRestrictions

object (TicketRestrictions)

此票券的使用限制相關資訊。舉例來說，這張票券可在星期幾使用，或是可使用票券的路線。
purchaseDetails

object (PurchaseDetails)

此票券的購買明細。
ticketLeg

object (TicketLeg)

單趟票券行程含有出發和抵達的資訊，以及搭乘資訊和座位資訊。如果要指定多段行程，請改用 ticketLegs 欄位。ticketLeg 和 ticketLegs 都可不予設定。
ticketLegs[]

object (TicketLeg)

每張票券可以包含一段以上的行程。每段行程都包含出發和抵達的資訊，以及搭乘資訊和座位資訊。如果僅要指定一段行程，請改用 ticketLeg 欄位。ticketLeg 和 ticketLegs 都可不予設定。
hexBackgroundColor

string

卡片的背景顏色。如果未設定，系統會使用主頁橫幅的主要顏色；如果未設定主頁橫幅，系統會使用標誌的主要顏色。格式為 #rrggbb，其中 rrggbb 是採十六進位制的 RGB 三元組，例如 #ffcc00。您也可以使用 RGB 三元組的簡寫版本 #rgb，例如 #fc0。
tripType

enum (TripType)

必要欄位。此大眾運輸物件代表的行程類型。用來判斷出發地與目的地之間所要使用的符號。
id

string

必要欄位。物件的專屬 ID。特定核發機構的所有物件 ID 都不得重複。這個值應依循 issuer ID 格式。identifier 的格式，其中前者是由 Google 核發，後者則由您指定。專屬 ID 只能包含英數字元、「.」、「_」或「-」。
classId

string

必要欄位。與此物件相關聯的類別。必須是與這個物件同類型、已存在，並且經過核准的類別。

類別 ID 應依循 issuer ID 格式。identifier 的格式，其中前者是由 Google 核發，後者則由您指定。
version
(deprecated)

string (int64 format)

已淘汰
state

enum (State)

必要欄位。物件的狀態。您可以使用這個欄位來設定物件在應用程式中的顯示情形。舉例來說，inactive 物件會移至「過期的票證」區段。
barcode

object (Barcode)

條碼類型和值。
messages[]

object (Message)

應用程式中顯示的訊息陣列。這個物件的所有使用者都會收到與該物件相關聯的訊息。這類欄位的數量上限是 10 個。
validTimeInterval

object (TimeInterval)

這個物件處於 active 狀態且可供使用的時間範圍。如果過了這段時間範圍，物件的狀態會變成 expired。
locations[]
(deprecated)

object (LatLongPoint)

注意：系統目前不支援使用這個欄位觸發地理通知。
hasUsers

boolean

表示這個物件是否有使用者。這個欄位是由平台所設定。
smartTapRedemptionValue

string

這個物件會透過 NFC 傳送至智慧感應認證感應式刷卡機的值。如要讓票證支援智慧感應功能，您也必須正確設定類別層級欄位 enableSmartTap 和 redemptionIssuers。系統僅支援 ASCII 字元。
hasLinkedDevice

boolean

表示這個物件目前是否已連結至某部裝置。當使用者儲存物件以將物件連結到裝置時，平台會設定這個欄位。適用於特定合作夥伴。如需更多資訊，請與支援團隊聯絡。
disableExpirationNotification

boolean

表示是否應明確封鎖通知。如果將這個欄位設為 true，無論 messages 欄位的值為何，向使用者發出的到期通知都會遭封鎖。根據預設，這個欄位會設為 false。

目前只能針對優惠進行設定。
infoModuleData

object (InfoModuleData)

已淘汰，請改用 textModulesData。
imageModulesData[]

object (ImageModuleData)

圖片模組資料。這類欄位的顯示數量上限為物件層級 1 個，以及類別物件層級 1 個。
textModulesData[]

object (TextModuleData)

文字模組資料。如果類別中也定義了文字模組資料，則兩項資料都會顯示。這類欄位的顯示數量上限為來自物件的 10 個，以及來自類別的 10 個。
activationStatus

object (ActivationStatus)

物件的啟用狀態。如果類別已設定 activationOptions，則為必要欄位。
rotatingBarcode

object (RotatingBarcode)

旋轉條碼的類型和值。
deviceContext

object (DeviceContext)

與物件相關聯的裝置內容。
heroImage

object (Image)

顯示在卡片正面的選用橫幅圖片。如果沒有，系統會顯示該類別的主頁橫幅圖片 (如果有)。如果類別也沒有主頁橫幅圖片，系統就不會顯示任何圖片。
groupingInfo

object (GroupingInfo)

用於控管票證分組方式的資訊。
passConstraints

object (PassConstraints)

傳遞物件的限制條件。包括限制 NFC 和螢幕截圖行為。
saveRestrictions

object (SaveRestrictions)

使用者嘗試儲存票證前，需要驗證的物件限制。請注意，這項限制只會在儲存時間期間套用。如果使用者儲存票證後，限制條件有所變更，系統不會將新限制套用至已儲存的票證。
linkedObjectIds[]

string

linkedObjectIds 是其他物件的清單，例如活動票券、會員卡、優惠、一般、禮物卡、大眾運輸和登機證，這些物件應自動附加至此大眾運輸物件。如果使用者已儲存這張大眾運輸卡，系統會自動將這些 linkedObjectId 推送至使用者的錢包 (除非使用者關閉接收這類已連結票證的設定)。

請確認已插入 linkedObjectIds 中的物件，否則呼叫會失敗。連結一經建立，就無法取消連結。您無法連結屬於其他發卡機構的物件。單一物件可連結的物件數量有限。達到上限後，系統會以無通知的方式忽略呼叫中的新連結物件。

物件 ID 應依循 issuer ID 的格式。identifier 的格式，其中前者是由 Google 核發，後者則由您指定。
notifyPreference

enum (NotificationSettingsForUpdates)

此物件的欄位更新是否應觸發通知。如果設為 NOTIFY，我們會嘗試觸發向使用者發出欄位更新通知。只有在欄位屬於許可清單的一部分時，系統才會傳送這些通知給使用者。如果設為 DO_NOT_NOTIFY 或 NOTIFICATION_SETTINGS_UNSPECIFIED，系統就不會觸發通知。這項設定是暫時性的，需要在每次 PATCH 或 UPDATE 要求中設定，否則系統不會觸發通知。
valueAddedModuleData[]

object (ValueAddedModuleData)

選用價值加值模組資料。物件上最多可有十個。
merchantLocations[]

object (MerchantLocation)

商家地點。物件上最多可有十個。超過 10 個的 MerchantLocations 都會遭到拒絕。當使用者進入 Google 設定的圓心半徑範圍內，這些位置就會觸發通知。這個欄位會取代已淘汰的 LatLongPoints。

PassengerType

列舉
PASSENGER_TYPE_UNSPECIFIED
SINGLE_PASSENGER
singlePassenger

SINGLE_PASSENGER 的舊版別名，已淘汰。
MULTIPLE_PASSENGERS
multiplePassengers

MULTIPLE_PASSENGERS 的舊版別名，已淘汰。

TicketStatus

列舉
TICKET_STATUS_UNSPECIFIED
USED
used

USED 的舊版別名，已淘汰。
REFUNDED
refunded

REFUNDED 的舊版別名，已淘汰。
EXCHANGED
exchanged

EXCHANGED 的舊版別名，已淘汰。

ConcessionCategory

列舉
CONCESSION_CATEGORY_UNSPECIFIED
ADULT
adult

ADULT 的舊版別名，已淘汰。
CHILD
child

CHILD 的舊版別名，已淘汰。
SENIOR
senior

SENIOR 的舊版別名，已淘汰。

TicketRestrictions

JSON 表示法 
{
  "routeRestrictions": {
    object (LocalizedString)
  },
  "routeRestrictionsDetails": {
    object (LocalizedString)
  },
  "timeRestrictions": {
    object (LocalizedString)
  },
  "otherRestrictions": {
    object (LocalizedString)
  }
}
欄位
routeRestrictions

object (LocalizedString)

可使用之路線的相關限制。例如，這裡的內容可能會是「僅限預訂的英國縱貫鐵路火車」這個字串。
routeRestrictionsDetails

object (LocalizedString)

有關上述 routeRestrictions 的更多詳細資料。
timeRestrictions

object (LocalizedString)

此票券的使用時間相關限制。
otherRestrictions

object (LocalizedString)

不屬於「路線」或「時間」類別的其他限制。

PurchaseDetails

JSON 表示法 
{
  "purchaseReceiptNumber": string,
  "purchaseDateTime": string,
  "accountId": string,
  "confirmationCode": string,
  "ticketCost": {
    object (TicketCost)
  }
}
欄位
purchaseReceiptNumber

string

透過售票機構追蹤購票活動所用的收據編號/ID。
purchaseDateTime

string

票券的購買日期/時間。

日期/時間採用 ISO 8601 擴充格式 (不一定含有偏移量)。時間的精確度可以指定到奈秒。此外，即使 ISO 8601 格式並未包含時差的秒數，時差的精確度仍可指定到秒。

例如：

1985-04-12T23:20:50.52Z 是世界標準時間 1985 年 4 月 12 日 23 時 20 分 50.52 秒。

1985-04-12T19:20:50.52-04:00 是 1985 年 4 月 12 日 19 時 20 分 50.52 秒，當地時間比世界標準時間慢 4 小時 (與上述範例為同一時間)。如果活動是在紐約舉行，則等同於美東夏令時間 (EDT)。請注意，時差可能會因當地當時是否施行日光節約時間 (或夏令時間) 而異。

1985-04-12T19:20:50.52 是 1985 年 4 月 12 日 19 時 20 分 50.52 秒，不含時差資訊。

在沒有偏移量資訊的情況下，某些實用功能可能無法使用。
accountId

string

用於購買票券的帳戶 ID。
confirmationCode

string

購買的確認碼。多張不同票券可能會有相同的確認碼，且可使用確認碼將票券分成一組。
ticketCost

object (TicketCost)

票券費用。

TicketCost

JSON 表示法 
{
  "faceValue": {
    object (Money)
  },
  "purchasePrice": {
    object (Money)
  },
  "discountMessage": {
    object (LocalizedString)
  }
}
欄位
faceValue

object (Money)

票券面額。
purchasePrice

object (Money)

票券的實際購買價格 (稅後和/或套用折扣後)。
discountMessage

object (LocalizedString)

說明所套用之任何折扣的訊息。

TicketLeg

JSON 表示法 
{
  "originStationCode": string,
  "originName": {
    object (LocalizedString)
  },
  "destinationStationCode": string,
  "destinationName": {
    object (LocalizedString)
  },
  "departureDateTime": string,
  "arrivalDateTime": string,
  "fareName": {
    object (LocalizedString)
  },
  "carriage": string,
  "platform": string,
  "zone": string,
  "ticketSeat": {
    object (TicketSeat)
  },
  "ticketSeats": [
    {
      object (TicketSeat)
    }
  ],
  "transitOperatorName": {
    object (LocalizedString)
  },
  "transitTerminusName": {
    object (LocalizedString)
  }
}
欄位
originStationCode

string

出發站點代碼。如果 destinationStationCode 存在，或 originName 不存在，則此為必要項目。
originName

object (LocalizedString)

出發站點名稱。如果 desinationName 存在，或 originStationCode 不存在，則此為必要項目。
destinationStationCode

string

目的地站點代碼。
destinationName

object (LocalizedString)

目的地名稱。
departureDateTime

string

出發日期/時間。如果大眾運輸物件上並未設定有效的時間間隔，則此為必填項目。

日期/時間採用 ISO 8601 擴充格式 (不一定含有偏移量)。時間的精確度可以指定到奈秒。此外，即使 ISO 8601 格式並未包含時差的秒數，時差的精確度仍可指定到秒。

例如：

1985-04-12T23:20:50.52Z 是世界標準時間 1985 年 4 月 12 日 23 時 20 分 50.52 秒。

1985-04-12T19:20:50.52-04:00 是 1985 年 4 月 12 日 19 時 20 分 50.52 秒，當地時間比世界標準時間慢 4 小時 (與上述範例為同一時間)。如果活動是在紐約舉行，則等同於美東夏令時間 (EDT)。請注意，時差可能會因當地當時是否施行日光節約時間 (或夏令時間) 而異。

1985-04-12T19:20:50.52 是 1985 年 4 月 12 日 19 時 20 分 50.52 秒，不含時差資訊。

不含時差的日期/時間部分會被視為「當地日期/時間」，且應是出發站點的當地日期/時間。例如，如果在 2018 年 6 月 5 日 20 時從出發站點出發，則當地日期/時間的部分應為 2018-06-05T20:00:00。如果出發站點的當地日期/時間比世界標準時間慢 4 小時，可以加上 -04:00 的時差。

在沒有偏移量資訊的情況下，某些實用功能可能無法使用。
arrivalDateTime

string

抵達日期/時間。

日期/時間採用 ISO 8601 擴充格式 (不一定含有偏移量)。時間的精確度可以指定到奈秒。此外，即使 ISO 8601 格式並未包含時差的秒數，時差的精確度仍可指定到秒。

例如：

1985-04-12T23:20:50.52Z 是世界標準時間 1985 年 4 月 12 日 23 時 20 分 50.52 秒。

1985-04-12T19:20:50.52-04:00 是 1985 年 4 月 12 日 19 時 20 分 50.52 秒，當地時間比世界標準時間慢 4 小時 (與上述範例為同一時間)。如果活動是在紐約舉行，則等同於美東夏令時間 (EDT)。請注意，時差可能會因當地當時是否施行日光節約時間 (或夏令時間) 而異。

1985-04-12T19:20:50.52 是 1985 年 4 月 12 日 19 時 20 分 50.52 秒，不含時差資訊。

不含時差的日期/時間部分會被視為「當地日期/時間」，且應是目的地站點的當地日期/時間。例如，如果活動是在 2018 年 6 月 5 日 20 時於目的地站點發生，則當地日期/時間的部分應為 2018-06-05T20:00:00。如果目的地站點的當地日期/時間比世界標準時間慢 4 小時，可以加上 -04:00 的時差。

在沒有偏移量資訊的情況下，某些實用功能可能無法使用。
fareName

object (LocalizedString)

這段行程的票價簡短說明/名稱。例如「Anytime Single Use」。
carriage

string

乘客要搭乘的火車或船舶的名稱/編號。
platform

string

乘客乘車的月台或閘門。
zone

string

月台內的乘車區域。
ticketSeat

object (TicketSeat)

乘客的預留座位。如果要指定多個座位，請改用 ticketSeats 欄位。ticketSeat 和 ticketSeats 都可不予設定。
ticketSeats[]

object (TicketSeat)

乘客的預留座位。如果僅要指定一個座位，請改用 ticketSeat 欄位。ticketSeat 和 ticketSeats 都可不予設定。
transitOperatorName

object (LocalizedString)

負責營運此段行程的大眾運輸業者名稱。
transitTerminusName

object (LocalizedString)

火車/公車等交通工具的終點站或目的地。

TicketSeat

JSON 表示法 
{
  "fareClass": enum (FareClass),
  "customFareClass": {
    object (LocalizedString)
  },
  "coach": string,
  "seat": string,
  "seatAssignment": {
    object (LocalizedString)
  }
}
欄位
fareClass

enum (FareClass)

售票座位的艙等。
customFareClass

object (LocalizedString)

沒有適用的 fareClass 時會採用的自訂艙等。fareClass 和 customFareClass 都可不予設定。
coach

string

售票座位所在的車廂 ID，例如：「10」
seat

string

售票座位所在位置的 ID，例如：「42」。如果沒有特定的 ID，請改用 seatAssigment。
seatAssignment

object (LocalizedString)

乘客的座位安排。例如：「無特定座位」。使用時機為 seat 中沒有特定 ID 可用時。

FareClass

列舉
FARE_CLASS_UNSPECIFIED
ECONOMY
economy

ECONOMY 的舊版別名，已淘汰。
FIRST
first

FIRST 的舊版別名，已淘汰。
BUSINESS
business

BUSINESS 的舊版別名，已淘汰。

TripType

列舉
TRIP_TYPE_UNSPECIFIED
ROUND_TRIP
roundTrip

ROUND_TRIP 的舊版別名，已淘汰。
ONE_WAY
oneWay

ONE_WAY 的舊版別名，已淘汰。

ActivationStatus

物件的啟用狀態。如果值支援啟用功能，這個欄位就會包含啟用狀態。

JSON 表示法 
{
  "state": enum (State)
}
欄位
state

enum (State)

州

列舉
UNKNOWN_STATE
NOT_ACTIVATED 未啟用，這是預設狀態
not_activated

NOT_ACTIVATED 的舊版別名，已淘汰。
ACTIVATED 已啟用
activated

ACTIVATED 的舊版別名，已淘汰。

DeviceContext

與物件相關聯的裝置內容。

JSON 表示法 
{
  "deviceToken": string
}
欄位
deviceToken

string

如果設為已啟用，系統只會在啟用物件時，將兌換資訊傳回給指定裝置。請勿將這項資訊用於追蹤使用者的裝置。這可能會因同一部裝置的不同票證而異，甚至會因同一部裝置的不同啟用方式而異。設定此值時，呼叫端也必須在要啟用的物件上設定 hasLinkedDevice。

方法

addmessage

 在指定物件 ID 參照的大眾運輸物件中新增訊息。

get

 傳回具有指定物件 ID 的大眾運輸物件。

insert

 插入具有指定 ID 和屬性的大眾運輸物件。

list

 傳回指定發卡機構 ID 的完整大眾運輸物件清單。

patch

 更新指定物件 ID 參照的大眾運輸物件。

update

 更新指定物件 ID 參照的大眾運輸物件。