可用性 Feed 示例和定义

{
  "metadata": {
    "processing_instruction": "PROCESS_AS_COMPLETE",
    "shard_number": 0,
    "total_shards": 1,
    "nonce": "11203880",
    "generation_timestamp": 1524606581
  },
  "service_availability": [
    {
      "availability": [
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535853600,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 6
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535853600,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 5
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535853600,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 4
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
         {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535853600,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 3
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
         {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535853600,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 2
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535853600,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 1
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535855400,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 6
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535855400,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 5
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
       {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535855400,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 4
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535855400,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 3
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535855400,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 2
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535855400,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 1
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        }
      ]
    }
  ]
}

message AvailabilityFeed {
  FeedMetadata metadata = 1;
  repeated ServiceAvailability service_availability = 2;
}

message ServiceAvailability {
  // If provided, we will consider the Availability entities provided to be a
  // complete snapshot from [start_timestamp_restrict, end_timestamp_restrict).
  // That is, all existing availability will be deleted if the following
  // condition holds true:
  //
  //    start_timestamp_restrict <= Availability.start_sec &&
  //    Availability.start_sec < end_timestamp_restrict
  //
  // If a duration message is set, the condition is further restricted:
  //   Availability.duration == duration_restrict_sec
  //
  // If a resource_restrict message is set, the condition is further restricted:
  //
  //    Availability.resource.staff_id == resource_restrict.staff_id &&
  //    Availability.resource.room_id == resource_restrict.room_id
  //
  // These fields are typically used to provide a complete update of
  // availability in a given time range.
  //
  // Setting start_timestamp_restrict while leaving end_timestamp_restrict unset
  // is interpreted to mean all time beginning at start_timestamp_restrict.
  //
  // Setting end_timestamp_restrict while leaving start_timestamp_restrict unset
  // is interpreted to mean all time up to the end_timestamp_restrict.
  //
  // In Unix time format (seconds since the epoch) from UTC. (both optional)
  int64 start_timestamp_restrict = 1;
  int64 end_timestamp_restrict = 2;

  // If provided, the timestamp restricts will be applied only to the given
  // merchant or service.
  //
  // These fields are typically used to provide complete snapshot of
  // availability in a given range (defined above) for a specific merchant or
  // service.
  //
  // Leaving these fields unset, or setting these to the empty string or null,
  // is interpreted to mean that no restrict is intended. (both optional)
  string merchant_id_restrict = 3;
  string service_id_restrict = 4;

  // Setting duration further restricts the scope of the update to just the
  // availability with matching duration.
  //
  // In seconds. (optional)
  int64 duration_restrict_sec = 7;

  // Setting resources_restrict further restricts the scope of the update to
  // just this set of resources. All id fields of the resources must match
  // exactly. (optional)
  Resources resources_restrict = 6;

  // All Availability Slots included in this Service Availability (required)
  repeated Availability availability = 5;
}

// An availability of the merchant's service, indicating time and number
// of spots.
// The availability feed should be a list of this message.
// Please note that it's up to the partner to call out all the possible
// availabilities.
// If a massage therapist is available 9am-12pm, and they provide
// one-hour massage sessions, the aggregator should provide the feed as
//   availability {start_sec: 9am, duration: 60 minutes, ...}
//   availability {start_sec: 10am, duration: 60 minutes, ...}
//   availability {start_sec: 11am, duration: 60 minutes, ...}
// instead of
//   availability {start_sec: 9am, duration: 180 minutes, ...}
//
message Availability {
  // An opaque string from an aggregator to identify a merchant. (required)
  string merchant_id = 1;

  // An opaque string from aggregator to identify a service of the
  // merchant. (required)
  string service_id = 2;

  // Start time of this availability, using epoch time in seconds in UTC.
  //(required)
  int64 start_sec = 3;

  // Duration of the service in seconds, e.g. 30 minutes for a chair massage.
  // (required)
  int64 duration_sec = 4;

  // Number of total spots and open spots of this availability.
  // E.g. a party_size of 4 of 10 spots with 3 booked.
  //   availability {spots_total: 10, spots_open: 7 ...}
  // E.g. a party_size of 10 which was already booked.
  //   availability {spots_total: 1, spots_open: 0 ...}
  //
  int64 spots_total = 5;
  int64 spots_open = 6;

  // An optional opaque string to identify this availability slot. If set, it
  // will be included in the requests that book/update/cancel appointments.
  // (optional)
  string availability_tag = 7;

  // Optional resources used to disambiguate this availability slot from
  // others when different room or party_size values are part
  // of the service.
  //
  // E.g. party size of 2 with different seating sections.
  //  availability { resources { party_size: 2 room_id: "patio" room_name: "Garden Patio" }
  //                 spots_total: 10 spots_open: 7 }
  //  availability { resources { party_size: 2 }
  //                 spots_total: 5 spots_open: 2 }
  // (optional)
  Resources resources = 8;

  // Availability level scheduling rules.
  message SchedulingRuleOverrides {
    // The last time (in seconds) that this slot is able to be booked. This
    // timestamp must be before the start_sec of the slot to be respected
    // (if users should be able to book after the start time, use service level
    // SchedulingRules.min_booking_buffer_before_end_time). If present, will
    // override anything specified in the min_booking_buffer of the
    // corresponding Service's SchedulingRules.
    int64 last_bookable_sec = 1;

    // The first time (in seconds) that this slot is able to be booked.
    int64 first_bookable_sec = 2;

    // If set, the last time (in seconds since the Unix epoch) that this
    // specific appointment slot can be cancelled through Reserve with Google.
    // This field will override any service-level cancellation rules. (optional)
    int64 last_online_cancellable_sec = 3;
  }

  // Availability scheduling rules. If fields are populated, they will override
  // any corresponding scheduling rules on the service-level SchedulingRules.
  SchedulingRuleOverrides scheduling_rule_overrides = 16;

  // This enum indicates what requirements exist for the user to
  // acknowledge or view the requested slots duration/end time.
  enum DurationRequirement {
    // The handling of the end time is not specified. This is the default.
    DURATION_REQUIREMENT_UNSPECIFIED = 0;

    // The end time is not shown to the user.
    DO_NOT_SHOW_DURATION = 1;

    // The end time has to be shown to the user before an appointment can be
    // made.
    MUST_SHOW_DURATION = 2;
  }

  // The requirement to show the slots duration and/or endtime.
  // This field will be ignored if the slot is unavailable. Not used in the
  // Things-To-Do vertical. (optional)
  DurationRequirement duration_requirement = 18;

  // The confirmation modes used when booking availabilities.
  enum ConfirmationMode {
    // The confirmation mode was not specified.
    // Synchronous confirmation will be assumed.
    CONFIRMATION_MODE_UNSPECIFIED = 0;
    // Bookings for this availability will be confirmed synchronously.
    CONFIRMATION_MODE_SYNCHRONOUS = 1;
    // Bookings for this availability will be confirmed asynchronously.
    CONFIRMATION_MODE_ASYNCHRONOUS = 2;
  }
  // The confirmation mode that will be used when booking this availability.
  // Attempts to create bookings for availabilities with a confirmation mode
  // of CONFIRMATION_MODE_SYNCHRONOUS must be immediatlely confirmed or denied.
  // Attempts to create bookings for availabilities with confirmation mode
  // of CONFIRMATION_MODE_ASYNCHRONOUS must be either immediately denied
  // or created with status PENDING. Populating confirmation_mode is strongly
  // recommended, but not strictly required. (optional)
  ConfirmationMode confirmation_mode = 17;

  }

// A resource is used to disambiguate availability slots from one another when
// different staff, room or party_size values are part of the service.
// Multiple slots for the same service and time interval can co-exist when they
// have different resources.
message Resources {
  // party_size is required
  // room_id and room_name are optional

  // An optional ID for the room the service is located in. This field
  // identifies the room across all merchant, services, and availability
  // records. It also needs to be stable over time to allow correlation with
  // past bookings. (optional but required if room_name is present)
  string room_id = 3;

  // An optional name for the room the service is located in. This
  // field will be displayed to users making a booking, and should be human
  // readable, as opposed to an opaque identifier. (optional but required if
  // room_id is present)
  // In dining a room name should only be used for seating areas such as the
  // bar or patio and should not be used for fixed price menus, special
  // activities, or any other non-room value (such as reservation or dinner).
  // It is strongly recommended that the default seating area not have a room
  // associated with it. (used with room_id)
  string room_name = 4;

  // Applicable only for Dining: The party size that can be accommodated
  // during this time slot. A restaurant can be associated with multiple Slots
  // for the same time, each specifying a different party_size, if for instance
  // 2, 3, or 4 people can be seated with a reservation. (required)
  int32 party_size = 5;

}