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=1 和 spotsOpen=1。
  • ScheduleException 表示 spotsTotal=1 和 spotsOpen=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

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