Jitsi Meet预订系统设置 –支持通过 REST API 的预订系统

可以使用 REST API 连接到外部会议预订系统。在创建新的 Jitsi Meet 会议之前，将查询预订系统以检查房间的可用性。该系统应返回一个正或负的响应代码，其中还包含会议的持续时间。Prosody 将强制执行会议持续时间，如果超过时间限制，则会终止会议。

启用预订系统

为了启用预订系统，必须配置 REST API 端点的 URL 基础。在 prosody 的主虚拟主机下，启用模块 “reservations” 并添加配置 reservations_api_prefix：

VirtualHost "meet.icloudportal.com"
    -- ....
    modules_enabled = {
        -- ....
        "reservations";
    }
    reservations_api_prefix = "http://s.icloudportal.com/api"

URL 基础用于构建请求 URL。目前，只支持 ‘/conference’ 终端点，因此所有请求都将发送到：

http://s.icloudportal.com/api/conference

还提供了其他配置选项：

• “reservations_api_timeout”：更改 API 调用的超时时间（默认为 20 秒）
• “reservations_api_headers”：指定包含在所有 API 调用中的自定义 HTTP 标头，例如提供身份验证令牌。
• “reservations_api_retry_count”：指定 API 调用失败重试的次数（默认为 3 次）
• “reservations_api_retry_delay”：重试之间等待的秒数（默认为 3 秒）
• “reservations_api_should_retry_for_code”：作为一个函数，接受 HTTP 响应代码并返回 true，如果应重试 API 调用。默认情况下，对于 5XX 响应，会进行重试。超时永远不会重试，HTTP 调用失败总是会重试。
• “reservations_enable_max_occupants”：启用设置最大入住人数的支持。如果设置为 true，并且 API 响应有效载荷包括一个 “max_occupants” 值，则该值将被设置为该特定房间的最大入住限制。
• 必须还启用 “muc_max_occupants” 模块才能使其正常工作。
• “reservations_enable_lobby_support”：启用大厅支持。如果设置为 true，并且 API 响应有效载荷包括一个 “lobby” 字段设置为 true，则将为该房间启用大厅。
• 必须还启用 “muc_lobby_rooms” 和 “persistent_lobby” 模块才能使其正常工作。
• “reservations_enable_password_support”：启用房间密码支持。如果设置为 true，并且 API 响应有效载荷包括一个 “password” 值，则该值将作为房间密码设置。然后用户将需要知道该密码才能加入房间，或者在启用大厅的情况下，可以使用密码绕过大厅。

    --- The following are all optional
    reservations_api_headers = {
        ["Authorization"] = "Bearer TOKEN-237958623045";
    }
    reservations_api_timeout = 10  -- timeout if API does not respond within 10s
    reservations_api_retry_count = 5  -- retry up to 5 times
    reservations_api_retry_delay = 1  -- wait 1s between retries
    reservations_api_should_retry_for_code = function (code)
        return code >= 500 or code == 408
    end
    reservations_enable_max_occupants = true -- enable integration with muc_max_occupants
    reservations_enable_lobby_support = true -- enable integration with muc_lobby_rooms
    reservations_enable_password_support = true -- enable support for setting room passwords

调用流程

注意

所有 API 调用使用以下日期时间格式：

yyyy-MM-dd’T’HH:mm:ss.SSSX – 更多信息可以在 SimpleDateFormat JavaDoc 中找到

会议分配

当第一个用户加入一个 MUC 房间（即打开 Jitsi Meet URL）时，将向 ‘/conference’ 终端点发送 HTTP POST 请求，包含以下参数：

• name (字符串) – 会议室的简短名称（不是完整的 MUC 地址）。如果使用了租户，则名称将为 [租户]房间名。
• start_time (字符串) – 会议开始的日期和时间
• mail_owner (字符串) – 如果启用了身份验证系统，该字段将包含用户的身份。在这种情况下，将无法在没有身份验证的情况下创建新的会议室。

发送到终端点的有效载荷将编码为 application/x-www-form-urlencoded。

预订系统预计将以以下响应之一响应：

HTTP 200 或 201 会议创建成功

在 HTTP 响应中，预期一个 JSON 对象。它应包含系统分配的会议 ID 和以秒为单位的持续时间。示例响应主体：

{
  "id": 364758328,
  "name": "conference1234",
  "mail_owner": "user@server.com",
  "start_time": "2048-04-20T17:55:12.000Z",
  "duration": 900000
}

modules_enabled = {对象还可以可选地包含一个 max_occupants 键，其值为整数。当提供时，且如果启用了 reservations_enable_max_occupants，则该值将传递给 muc_mod_max_occupants 以强制执行每个房间的人数限制。

HTTP 409 – 会议已存在

这是为了从先前的故障中恢复。如果由于某种原因会议被重新启动并且用户尝试再次创建房间，则此响应通知 Prosody 该会议室已经存在。预期的是在 JSON 响应主体中包含 conflict_id：

{
  "conflict_id": 364758328
}

Prosody 将使用 HTTP GET 获取给定 conflict_id 的冲突会议的信息。关于此请求的更多信息可以在 “读取会议信息” 部分找到。

HTTP 4xx
其他响应代码将导致会议创建失败。JSON 响应可以包含一个消息对象，该对象将被发送回客户端。

例如，用户 1 尝试通过将会议 IQ 发送到 Jicofo 来启动一个新会议。系统将拒绝该请求。

客户端 -> Jicofo:

<iq from='client1@xmpp.com' to='jicofo.meet.com' type='set'>
  <conference xmlns='http://jitsi.org/protocol/focus' room='testroom1' />
</iq>

Prosody -> 预订系统:

POST /conference HTTP/1.1
content-type:application/x-www-form-urlencoded;charset=utf-8
host: http://reservation.example.com
content-length: length

name=testroom1&start_time=2048-04-20T17%3A55%3A12.000Z&mail_owner=client1%40xmpp.com

预订系统 -> Prosody:

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: length

{
  "message": "client1 is not allowed to create the room at this time"
}

Prosody -> 客户端:

<iq from='jicofo.meet.com' to='client1@xmpp.com' type='error'>
  <error type='cancel'>
    <service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas' />
    <text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>
          client1 is not allowed to create the room at this time
    </text>
    <reservation-error xmlns='http://jitsi.org/protocol/focus' error-code='403'/>
  </error>
</iq>

应用程序可以使用文本和 reservation-error 元素向用户提供有意义的信息。

读取会议信息

如果对 HTTP POST 请求的响应是 409，则 Prosody 将尝试使用 HTTP GET ‘/conference/{conflict_id}’ 终端点读取有关冲突会议的信息。响应应提供存储在预订系统中的有关会议的所有信息：

• “id”: 预订系统分配的会议标识符
• “name”: 会议室名称
• “mail_owner”: 创建会议的用户的身份
• “start_time”: 会议开始的日期和时间
• “duration”: 预定会议持续时间（以秒为单位）
• 如果适用，还应提供可选的 max_occupants 值。

示例响应 JSON 主体（包含与 HTTP POST 的 200 OK 相同的信息）：

{
  "id": 364758328,
  "name": "conference1234",
  "mail_owner": "user@server.com",
  "start_time": "2048-04-20T17:55:12.000Z",
  "duration": 900000
}

删除会议

Prosody 在两种情况下从预订系统中删除会议。首先是当所有用户离开 XMPP 多用户聊天室时。其次是当超过会议持续时间限制时。在后一种情况下，Prosody 将销毁 XMPP MUC 房间。在 MUC 房间被销毁后，Prosody 将向 ‘/conference/{id}’ 终端点发送 HTTP DELETE 请求，其中 {id} 被预订系统分配的会议标识符替换。

DELETE /conference/364758328 HTTP/1.1
host: http://reservation.example.com
...