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)
  },
  "prepayment": {
    object (Prepayment)
  },
  "requireCreditCard": enum (RequireCreditCard),
  "ticketTypeId": [
    string
  ],
  "durationRequirement": enum (DurationRequirement),
  "schedulingRuleOverrides": {
    object (SchedulingRuleOverrides)
  },
  "confirmationMode": enum (ConfirmationMode),
  "linkoutRequiredReason": enum (LinkoutRequiredReason)
}
欄位
startTime

string (Timestamp format)

預約時段的開始時間。

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，精確度達奈秒單位，最多九個小數位數。例如 "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)

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

object (Prepayment)

選用設定。這個可預訂時段的選用預付款資訊。
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 確認模式來針對供應時段建立預訂，則必須立即拒絕或以「待處理」的狀態建立。
linkoutRequiredReason

enum (LinkoutRequiredReason)

選用設定。這個版位必須提供外連連結的原因。如果已設定，這個版位的商家資源必須包含有效的 LinkoutTemplate。(選填)

資源

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

JSON 表示法 
{
  "staffId": string,
  "staffName": string,
  "roomId": string,
  "roomName": string,
  "partySize": integer,
  "roomDescription": {
    object (Text)
  }
}
欄位
staffId

string

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

string

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

string

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

string

(選用) 服務進行時所在空間的名稱。這個欄位會向預訂者顯示，且應為使用者可理解的格式，而非隱晦 ID。(選用，但如果有 roomId 就必須使用) 在餐飲類別中，房間名稱應只用於酒吧或露台等座位區，不應用於固定價格菜單、特殊活動或任何其他非房間值 (例如預訂或晚餐)。強烈建議您不要為預設座位區建立相關聯的房間。
partySize

integer

僅適用於「餐飲業」：在此時段可接待的用餐人數。餐廳可以同時與多個時段建立關聯，這些時段可分別指定不同的 partySize (例如預訂可接受 2 人、3 人或 4 人入座)。
roomDescription

object (Text)

選用設定。本地化聊天室說明。如果已設定，則必須提供預設值。建議您也提供商家所在區域的常用語言。(選填)

重複週期

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

需求條件：

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

string (Timestamp format)

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

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，精確度達奈秒單位，最多九個小數位數。例如 "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 開始的時段不會受到影響。

預付款

使用者可能需要支付的預訂費用。

JSON 表示法 
{
  "priceInfo": {
    object (PriceInfo)
  }
}
欄位
priceInfo

object (PriceInfo)

價格詳細資料容器。

PriceInfo

價格詳細資料容器。

JSON 表示法 
{
  "priceType": enum (PriceType),

  // Union field price_options can be only one of the following:
  "price": {
    object (Price)
  },
  "priceRange": {
    object (PriceRange)
  }
  // End of list of possible types for union field price_options.
}
欄位
priceType

enum (PriceType)

定義價格或價格範圍的套用方式 (每人或固定)
聯集欄位 price_options。價格選項可指定確切價格或價格範圍。price_options 只能是下列其中一項：
price

object (Price)

服務或費用的價格。
priceRange

object (PriceRange)

服務或費用的上限和/或下限。

PriceRange

除非同時設定兩個值，否則系統會將貨幣金額範圍視為無限。至少須提供 minAmount 或 maxAmount 其中一個。

JSON 表示法 
{
  "minPrice": {
    object (Price)
  },
  "maxPrice": {
    object (Price)
  }
}
欄位
minPrice

object (Price)

最低金額。
maxPrice

object (Price)

金額上限。應一律大於 minPrice。

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 以非同步方式確認對這個時段所做的預訂。

LinkoutRequiredReason

廣告位有外連體驗的原因。

列舉
LINKOUT_REQUIRED_REASON_UNSPECIFIED 預設值：請勿使用，等同於不明。
PAYMENT_REQUIRED 預訂時必須在合作夥伴平台中付款。

方法

replace

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