REST Resource: inventory.partners.merchants.services.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 世界协调时间(UTC,即“祖鲁时”)格式,精确到纳秒,最多九个小数位。示例:"2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

duration

string (Duration format)

预约空档的持续时间

该时长以秒为单位,最多包含九个小数位,以“s”结尾。示例:"3.5s"

spotsTotal

string (int64 format)

此可用性的总空档数和可用空档数。示例:

  • 瑜伽课有 10 个空档,其中 3 个已预订:availability {spotsTotal: 10, spotsOpen: 7 ...}
  • 按摩椅服务空档已订满:availability {spotsTotal: 1, spotsOpen: 0 ...}

注意:如果使用下面指定的可用性压缩格式发送请求,将推断出以下两个字段。

  • Recurrence 表示 spotsTotal=1spotsOpen=1
  • ScheduleException 表示 spotsTotal=1spotsOpen=0
spotsOpen

string (int64 format)

空缺数量。

availabilityTag

string

用于标识可用性空档的可选不透明字符串。如果设置,它将包含在预订/更新/取消预约的请求中。

resources

object (Resources)

当服务中包含不同的工作人员或房间时,用于消除此可用性空档与其他空档之间的歧义的可选资源。

例如,同一瑜伽课程有 2 位老师:

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

表示此可用性空档支持的票券类型列表。如果未设置该值,则父级服务中的所有票券类型均适用于此空档。请注意,必须在父级服务中定义此字段的值。示例:

  • 具有四种票券类型的服务: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"...}

  • 具有三种门票类型的服务:TicketType {ticketTypeId: "adult" shortDescription: "Adult"} TicketType {ticketTypeId: "youth" shortDescription: "Youth"} TicketType {ticketTypeId: "senior" shortDescription: "Senior"}

如需表示这三种票券类型均适用于此时间空档,请使用 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 的确认模式创建可用性的预订,则必须立即拒绝或创建状态为 PENDING 的预订。

资源

当服务中包含不同的工作人员或房间时,此资源可用于消除这些可用性空档之间的歧义。如果同一服务和时间间隔的多个空档的资源不同,则这些空档可共存。

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

string

提供服务的工作人员的可选 ID。此字段用于标识所有商家、服务和可用性记录中的工作人员。此外,考虑到需与之前的预订相关联,此字段需要随着时间的推移保持一致。如果存在 peopleName,则必须提供此字段。

staffName

string

提供服务的工作人员的可选姓名。办理预订的用户将看到此字段,该字段应该是用户可理解的内容,而非不透明的标识符。如果存在 peopleId,则必须提供此字段。

roomId

string

服务所在房间的可选 ID。此字段用于标识所有商家、服务和可用性记录中的房间。此外,考虑到需与之前的预订相关联,此字段需要随着时间的推移保持一致。如果存在 RoomName,则必须显示此字段。

roomName

string

服务所在房间的可选名称。办理预订的用户将看到此字段,该字段应该是用户可理解的内容,而非不透明的标识符。(可选,但如果存在 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)

可用性重复截止时间的时间戳,需包含最大时间单位的世界协调时间 (UTC)。

时间戳采用 RFC3339 世界协调时间(UTC,即“祖鲁时”)格式,精确到纳秒,最多九个小数位。示例:"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 生成空档。(必填)

该时长以秒为单位,最多包含九个小数位,以“s”结尾。示例:"3.5s"

ScheduleException

ScheduleException 消息表示工作日内已预订/不可用的时间范围,它是上述重复周期的例外情况。时间空档被预订后,应更新例外情况列表,以反映新的不可用的时间范围。不应修改重复周期本身。

JSON 表示法
{
  "timeRange": {
    object (TimeRange)
  }
}
字段
timeRange

object (TimeRange)

例外情况的时间范围。由重复周期描述且与此已打烊-营业中时间范围重叠的任何空档都将被视为不可用。

示例:如果重复周期指定时长为 20 分钟、repeatEvery 为 30 分钟、startTime 为上午 9:00 且 repeatUntil 为上午 11:00,则 timeRange 为上午 9:45-11:00 的 ScheduleException 会使上午 9:30-9:50、上午 10-10:20 和上午 10:30-10:50 的空档不可用。

请注意,由于时间范围为已打烊-营业中,因此,从上午 11 点开始的空档不会受到影响。

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

替换由指定的集合商家管理的商家现有 ServiceAvailability,并将其返回。