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。此字段用于标识所有商家、服务和可用性记录中的工作人员。此外，考虑到需与之前的预订相关联，此字段需要随着时间的推移保持一致。如果存在 roomName，则必须显示此字段。
staffName

string

提供服务的工作人员的可选姓名。办理预订的用户将看到此字段，该字段应该是用户可理解的内容，而非不透明的标识符。如果存在 personId，则必须显示此字段。
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，并将其返回。