REST Resource: inventory.partners.merchants.services.availability

資源：Availability

商家服務的可預訂時段，標示出時間和開放的名額數量。

JSON 表示法 
{
  "startTime": string,
  "duration": string,
  "spotsTotal": string,
  "spotsOpen": string,
  "availabilityTag": string,
  "resources": {
    object (Resources)
  },
  "paymentOptionId": [
    string
  ],
  "recurrence": {
    object (Recurrence)
  },
  "scheduleException": [
    {
      object (ScheduleException)
    }
  ],
  "deposit": {
    object (Deposit)
  },
  "noShowFee": {
    object (NoShowFee)
  },
  "requireCreditCard": enum (RequireCreditCard),
  "ticketTypeId": [
    string
  ],
  "durationRequirement": enum (DurationRequirement),
  "schedulingRuleOverrides": {
    object (SchedulingRuleOverrides)
  },
  "confirmationMode": enum (ConfirmationMode)
}
欄位
startTime

string (Timestamp format)

預約時段的開始時間。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
duration

string (Duration format)

預約時段的時間長度。

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。
spotsTotal

string (int64 format)

這個可預訂時段的總名額和開放名額數量。請見下方例子：

  • 瑜珈教室有 10 個名額，其中 3 個名額已有人預定：availability {spotsTotal: 10, spotsOpen: 7 ...}
  • 已預訂額滿的坐式按摩時段：availability {spotsTotal: 1, spotsOpen: 0 ...}

注意事項：如果使用下方定義的預訂情形壓縮格式來傳送要求，系統會推測這兩個欄位的值。

  • Recurrence 表示 spotsTotal=1 且 spotsOpen=1。
  • ScheduleException 意指 spotsTotal=1 和 spotsOpen=0。
spotsOpen

string (int64 format)

開放名額的數量。
availabilityTag

string

(選用) 用於辨識這個供應時段的隱晦字串。如果設定這個項目，系統會在預約/更新/取消預約的要求中納入這項資訊。
resources

object (Resources)

此為選用資源；如果可預訂時段的服務中含括不同的員工或房間，可用「資源」來做明確的區隔。

例如同一間瑜珈教室有兩名講師共用：

availability { resources { staffId: "1" staffName: "Amy" }
               spotsTotal: 10 spotsOpen: 7 }
availability { resources { staffId: "2" staffName: "John" }
               spotsTotal: 5 spotsOpen: 2 }
paymentOptionId[]

string

可用於支付該時段費用的付款方式參照 ID 清單。實際付款方式需在商家層級定義，而且可由多個商家共用。

這個欄位會覆寫服務訊息中指定的任何 payment_option_ids。同樣地，在這裡指定的 payment_option_ids「不必」顯示在服務訊息中，但必須在商家層級定義。
recurrence

object (Recurrence)

供應時段的週期資訊，代表有多個開始時間。一個週期應包含一個工作天的預約。
scheduleException[]

object (ScheduleException)

無法安排這項服務的時間。如要限制 scheduleException 訊息的數量，建議加入相鄰的例外狀況。
deposit

object (Deposit)

選用欄位，表示這個可預訂時段是否需要收取訂金。指定此欄位將會覆寫該服務的訂金。
noShowFee

object (NoShowFee)

選用欄位，表示這個可預訂時段是否會收取逾時未到費用。指定此欄位將會覆寫該服務的逾時未到費用。
requireCreditCard

enum (RequireCreditCard)

指出消費者是否需要提供信用卡資訊才能預訂這個時段。如果沒有設定這個值，系統會沿用服務層級設定的值 (如果已在服務層級設定)。(選填)
ticketTypeId[]

string

列出此供應時段支援的票券類型。如果未設定，表示父項服務中所有的票券類型皆可供這個時段使用。請注意，這個欄位的值必須在父項服務中定義，請見下方例子：

  • 含 4 種票券類型的服務：TicketType {ticketTypeId: "adult_1" shortDescription: "Adult weekdays"} TicketType {ticketTypeId: "adult_2" shortDescription: "Adult weekends"} TicketType {ticketTypeId: "youth_1" shortDescription: "Youth weekdays"} TicketType {ticketTypeId: "youth_2" shortDescription: "Youth weekends"}

平常日庫存清單的表示方式像這樣：availability {ticketTypeId: "adult_1" ticketTypeId: "youth_1"...}。假日庫存清單的表示方式如下：availability {ticketTypeId: "adult_2" ticketTypeId: "youth_2"...}。

  • 含 3 種票券類型的服務：TicketType {ticketTypeId: "adult" shortDescription: "Adult"} TicketType {ticketTypeId: "youth" shortDescription: "Youth"} TicketType {ticketTypeId: "senior" shortDescription: "Senior"}

如要指出在此時段這 3 種票券均可購買，請使用 availability {ticketTypeId: "adult" ticketTypeId: "youth" ticketTypeId: "senior" ...} 或「availability {...}」（請勿在這個時段設定 ticketTypeId)。

(選填)
durationRequirement

enum (DurationRequirement)

顯示時段時間長度和/或結束時間的規定。如果版位無法提供服務，系統會忽略這個欄位。未用於「觀光景點」類別。(選填)
schedulingRuleOverrides

object (SchedulingRuleOverrides)

預訂情形的排程規則。填入欄位後，就會覆寫服務層級 SchedulingRules 的任何相應排程規則。
confirmationMode

enum (ConfirmationMode)

預訂此時段時可使用的確認模式。若可預訂時段的確認模式是 CONFIRMATION_MODE_SYNCHRONOUS，就必須在建立預訂時立刻確認或拒絕。若可預訂時段的確認模式為 CONFIRMATION_MODE_ASYNCHRONOUS，就必須立即拒絕或建立預訂，且建立狀態為「待處理」。

資源

如果可預訂時段的服務中含括不同的員工或房間，可用「資源」來做明確的區隔。時間間隔相同且提供相同服務的多個時段只要包含不同的資源，就可以同時存在。

JSON 表示法 
{
  "staffId": string,
  "staffName": string,
  "roomId": string,
  "roomName": string,
  "partySize": integer
}
欄位
staffId

string

選用欄位，可指明提供服務員工的 ID。這個欄位用來識別所有商家、服務和預訂情形記錄中所有的員工，此外，這項資訊必須保持穩定一段時間，才能與過往的預訂建立關聯。如已提供 employeeName，則必須使用此欄位。
staffName

string

選用欄位，用來指明提供服務員工的名字。這個欄位會向預訂者顯示，且應為使用者可理解的格式，而非隱晦 ID。如已提供 employeeId，則必須使用這個欄位。
roomId

string

(選用) 服務進行時所在的空間的 ID。這個欄位可用於在所有商家、服務和供應情形記錄中識別空間。此外，這項資訊必須保持穩定一段時間，才能與過往的預訂建立關聯。如果已提供 roomName，則此欄位為必要項目。
roomName

string

(選用) 服務進行時所在空間的名稱。這個欄位會向預訂者顯示，且應為使用者可理解的格式，而非隱晦 ID。(如有提供 roomId，則為必填) 用餐地點名稱只應用於座椅區，例如酒吧或露台，不能用於固定價格菜單、特殊活動或任何其他非客房價值 (例如預訂或晚餐)。強烈建議將預設座椅休息區設成無關聯的房間。
partySize

integer

僅適用於「餐飲業」：在此時段可接待的用餐人數。一間餐廳可同時與多個時段建立關聯，而每個時段則指定不同的 partySize (例如預約對象可坐 2、3 或 4 人)。

重複週期

週期訊息是選用項目，能夠以更精簡的表示法代表持續重複發生的可預訂時段。這類訊息通常代表一天的工作排程，接著，系統會使用 ScheduleException 訊息來代表工作日當天已預訂/無法預訂的時間範圍。

需求條件：

  1. 擴充可預訂時段或週期時，「不得」建立完全相同的時段。系統會將 ID、startTime、duration 和 resources 都相符的時段視為相同時段。
  2. 「請勿」在單一服務的多個時段中混用標準預訂情形格式和週期。接受預約的商家/服務都可以使用週期格式，標準格式則適用於舉辦定期課程的商家/服務。
  3. 週期不可延續超過 24 小時。
JSON 表示法 
{
  "repeatUntil": string,
  "repeatEvery": string
}
欄位
repeatUntil

string (Timestamp format)

設定期限來指明要重複提供可預訂時段到何時，用世界標準時間格式的最晚時間戳記表示 (最晚時間包含在內)。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
repeatEvery

string (Duration format)

定義連續的可預訂時段的間隔時間。

例子：若可預訂時段的時間長度為 20 分鐘，repeatEvery 為 30 分鐘，startTime 是上午 9:00，repeatUntil 則是上午 11:00，那麼產生的時段分別是上午 9:00-9:20、上午 9:30-9:50、上午 10:00-10:20、上午 10:30-10:50，以及上午 11:00-11:20。(必填)

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。

ScheduleException

ScheduleException 訊息代表該工作日已預訂/無法預訂的時間範圍，這些是上述週期中的例外部分。每次有人預訂時段，就應隨之更新例外狀況清單，以顯示最新的無法預訂時間範圍，請不要修改週期本身。

JSON 表示法 
{
  "timeRange": {
    object (TimeRange)
  }
}
欄位
timeRange

object (TimeRange)

例外狀況的時間範圍。凡是與這個「從休息中到開門營業」的時間範圍重疊的週期指定時段，都視為無法預訂。

例子：如果週期指定的期間為 20 分鐘、repeatEvery 是 30 分鐘，startTime 是上午 9:00，repeatUntil 則是上午 11:00，那麼將 ScheduleException 的 timeRange 設為上午 9:45-11:00 後，上午 9:30-9:50、上午 10-10:20 和上午 10:30-10:50 這 3 個時段都無法預訂。

請注意，由於這是「從休息中到開門營業」的時間範圍，因此從上午 11:00 開始的時段不會受到影響。

DurationRequirement

這個列舉會指出，使用者須符合哪些條件，才能確認或查看要求的時段持續時間/結束時間。

列舉
DURATION_REQUIREMENT_UNSPECIFIED 未指定結束時間。此為預設值。
DO_NOT_SHOW_DURATION 使用者不會看到結束時間。
MUST_SHOW_DURATION 您必須先向使用者顯示結束時間，才能進行預約。

SchedulingRuleOverrides

預訂情形層級排程規則。

JSON 表示法 
{
  "lastBookableSec": string,
  "firstBookableSec": string,
  "lastOnlineCancellableSec": string
}
欄位
lastBookableSec

string (int64 format)

這個時段的最晚開放預訂時間 (以秒為單位)。這個時間戳記必須早於時段的 startSec，否則系統無法遵循 (若想讓消費者能夠在開始時間後預訂，請使用服務層級的 SchedulingRules.min_booking_before_end_time)。如果使用這個項目，其將覆寫對應服務的 SchedulingRules 在 min_booking_buffer 中指定的任何值。
firstBookableSec

string (int64 format)

這個時段可供預訂的最早時間 (以秒為單位)。這個時間戳記必須早於時段的 startSec，或者是 lastBookableSec (如有指定)。
lastOnlineCancellableSec

string (int64 format)

如果設定這項功能，可透過「透過 Google 預訂」取消該特定預約時段的最後一次時間 (自 Unix 紀元開始算起的秒數)。這個欄位會覆寫任何服務層級的取消規則。(選填)

ConfirmationMode

預訂時段時可使用的確認模式。

列舉
CONFIRMATION_MODE_UNSPECIFIED 未指定確認模式，系統會假設採用同步確認。
CONFIRMATION_MODE_SYNCHRONOUS 以同步方式確認對這個時段所做的預訂。
CONFIRMATION_MODE_ASYNCHRONOUS 以非同步方式確認對這個時段所做的預訂。

方法

replace

 取代並傳回指定集結網站所管理商家現有 Service 的 Availability。