跳过至主要内容

选择器

选择器用于指定哪些设备和哪些会话作为HTTP 请求或 WebSocket 命令的目标。

设备选择器 — URL 路径​

在所有设备级别的HTTP路由中，/{device_type}/{id_or_index}/… 以……的形式使用。

路径示例选择器的含义
inverse3/0索引（从0开始）指定的第一个Inverse3
inverse3/A14设备 ID A14 Inverse3
inverse3/*所有 Inverse3 设备（通配符）
*inverse/*Inverse 系列的所有设备（Inverse3、Inverse3x、Minverse）
inverse3:left/0以索引（从0开始）指定的第一个左侧Inverse3
*inverse:right/0索引（从 0 开始）指定的第一个右对齐的Inverse 字体家族设备
verse_grip/0索引（从0开始）中指定的第一个有线VerseGrip
wireless_verse_grip/*所有无线版 VerseGrip
*verse_grip/*VerseGrip 系列的所有设备（有线、无线、定制）
*verse_grip:custom/0通过索引（从0开始）指定的第一个自定义VerseGrip（custom_verse_grip/0 （与……相同）

在建立索引之前解决类过滤器问题​

<type>:<class>/<N> 样式选择器首先类过滤器应用该操作，随后对过滤后的集合进行索引。<N> 指的是经过过滤后的列表中的位置，而非原始设备列表中的位置：

  • *inverse:left/0 — 第0号左撇子这是 Inverse 系列的一款设备。当连接了 3 台 Inverse 设备时（顺序为右、左、右），该设备将被识别为第二台设备。索引 0 を「left である必要がある」でフィルターした結果を指すわけではありません。
  • inverse3:right/0 — 第0号右撇子这是Inverse3。
  • *inverse:left/3 — 如果已连接的左旋 Inverse 设备少于 4 台，即使 Inverse 设备总数超过 4 台， 404 返回。

该规则同样适用于通配符选择器。*inverse/* 和 *verse_grip/* 是该家族中的所有与设备匹配，并针对这些选择器 POST 以及 DELETE 该请求不仅会对第一台设备，还会对所有匹配的设备应用该操作。

规则：

  • GET 会拒绝通配符选择器（因其含义不明确）→ 400
  • POST 和 DELETE 支持通配符。该操作适用于所有匹配情况
  • 404 响应是 no device matches selector '<sel>' 使用该格式。<sel> 是接收到的原始选择器表达式

对应 {device_type} 的值： inverse3、verse_grip、wireless_verse_grip、或家族通配符 *inverse、*verse_grip。

会话选择器 — ?session=<expr> 查询参数​

在会话作用域的 HTTP 端点（basis、mount、preset、filters、navigation、SDF）中，为了确定操作对象会话的上下文， ?session=<expr> 需要查询参数。

式含义
（省略）所有会话（DELETE （仅限）
#123 或者 123ID 为 123 的会话
:0通过索引指定的第一个会话
:-1通过索引指定的最后一次会话
profile_name具有此配置文件的第一个会话（可能会有歧义）
profile_name:0指定配置文件后，索引为 0 的会话
:default:0个人资料 default 在所有会话中，索引为 0 的第一个会话
co.haply.hub::*:0配置文件名为 co.haply.hub:: 以...开头的第一个会话（Glob 通配符）
:co.haply.hub::*:-1co.haply.hub:: 命名空间中的最后一个会话

例：

GET /inverse3/0/config/navigation?session=:default:0

配置文件名的通配符​

在配置文件模式中，可以使用两种类型的 glob 元字符：

元字符含义
*匹配包含空字符串的任意长度字符串
?正好匹配1个字符

除上述以外的所有字符（:、.、-、[、] （包括）作为字面量进行匹配（[abc] 诸如这样的字符类是不支持）。区分大小写。

单独的 *（或 all）仍按惯例所有会议的意思是。名字是 * 要与以该字符开头的配置文件匹配，请再包含至少一个字符（例如： *foo）。

常用模式：

  • co.haply.hub::* — co.haply.hub:: 命名空间内的任意配置文件
  • *-update — -update 以...结尾的任意配置文件
  • co.haply.*:* — 命名空间为 co.haply. 以...开头的任意配置文件
  • defaul? — defaul 以...开头的任意7个字符的个人资料

通配符模式单独使用时暧昧（可能与多个会话匹配）。GET / POST 要在端点上使用，请在末尾添加 :<index> 请添加以下内容以消除歧义：

# First session in the Haply Hub namespace
GET /inverse3/0/config/basis?session=co.haply.hub::*:0

# Last session in a Unity namespace
GET /inverse3/0/config/mount?session=:co.haply.unity::*:-1

在 GET/POST 请求中，模糊通配符（无索引）是 400 将被拒绝。在明确允许匹配多个会话的路由中，这些情况是被允许的。具体来说，GET /sessions/<sel>（返回所有匹配项），DELETE 这是端点（适用于所有匹配情况）。

会话选择器 — URL 路径​

/sessions/{selector} 端点是，与路径参数相同的表达式接受此操作。这在搜索单个会话或确认该会话是否存在时非常有用：

GET /sessions                      # list all active sessions
GET /sessions/:default:0           # one session by profile + index
GET /sessions/:-1                  # last active session
GET /sessions/#42                  # session id 42
GET /sessions/co.haply.hub::*      # every session in the co.haply.hub:: namespace
GET /sessions/co.haply.hub::*:0    # first session in that namespace

从功能上讲，这是 GET /sessions?session=<selector> 与……相同。这两条路径都会调用同一个处理程序。GET /sessions/<sel> 是，:<index> 这是少数几个允许使用不带“的”后缀的模糊通配符模式的端点之一。GET /sessions 采用与该列表相同的列表式包装器结构，返回所有匹配项。

直接传递选择器

上述所有选择器格式（#42 や * （包括包含该配置模式的配置）是标准的HTTP客户端（Python requests、libhv、curl、fetch）将直接发送。客户端无需进行 URL 编码。在 shell 中，# や * 请用引号将包含该词的令牌括起来（例如： --session "#42"、--session "co.haply.hub::*:0"）。否则，shell 会将它们视为注释，或者对本地文件进行通配符展开。

有一个例外: ? 的glob通配符是，通关在……中，它是 URL 查询部分的分隔符。路径形式的選擇器（例如： /sessions/defaul?:0）那么，%3F 需要进行百分比编码（例如： GET /sessions/defaul%3F:0）。查询式选择器（?session=defaul?:0）那么，首先 ? 只有它会将查询拆分，而后续的 ? 文字将原样传递。

WebSocket 会话无需选择器

在 WebSocket 连接中，连接本身会话即为。configure 和 commands 该条目会自动针对当前会话中的设备。需要会话选择器的情况是，超文本传输协定 仅限请求（包括跨会话的远程操作。详情请参见 会话 请参阅（）。