Sélecteurs

Les sélecteurs indiquent quel appareil et quelle session sont ciblés par une requête HTTP ou une commande WebSocket.

Sélecteur d'appareil — chemin d'accès de l'URL

Utilisé dans toutes les routes HTTP au niveau de l'appareil, sous la forme /{device_type}/{id_or_index}/….

Exemple d'itinéraire	Signification du sélecteur
inverse3/0	Inverse3 s principales selon l'index (base 0)
inverse3/A14	Inverse3 dont l'identifiant de l'appareil est A14
inverse3/*	Tous les appareils Inverse3 (caractère générique)
*inverse/*	Tous les appareils de la gamme Inverse (Inverse3, Inverse3x, Minverse)
inverse3:left/0	Inverse3 -gaucher de premier plan selon l'Index
*inverse:right/0	Premier appareil de la gamme Inverse pour droitiers, selon l'index
verse_grip/0	Premier VerseGrip filaire selon l'index
wireless_verse_grip/*	Tous les VerseGrip sans fil
*verse_grip/*	Tous les appareils de la gamme VerseGrip (avec fil, sans fil, personnalisés)
*verse_grip:custom/0	Premier VerseGrip personnalisé selon l'index (équivalent à custom_verse_grip/0)

Les filtres de classe sont traités avant l'indexation

Un sélecteur <type>:<class>/<N> appliqué d'abord le filtre de classe, puis indexe dans l'ensemble filtré. Le <N> désigne une position dans la liste filtrée, et non dans la liste brute des appareils :

• *inverse:left/0 — l'appareil gaucher de l'index 0 de la gamme Inverse. Si trois appareils Inverse sont connectés (pour droitier, pour gaucher, pour droitier), ce sélecteur correspond au deuxième appareil, et non à l'index 0 filtré pour « doit être gaucher ».
• inverse3:right/0 — le Inverse3 plus à droite d'indice 0.
• *inverse:left/3 — 404 s'il y a moins de quatre appareils Inverse gauchers connectés, même si le nombre total d'appareils Inverse est supérieur à quatre.

La même règle s'applique aux sélecteurs génériques : *inverse/* et *verse_grip/* correspondant à tous les appareils de la famille et les requêtes POST / DELETE ciblant ces sélecteurs appliquent l'opération à toutes les correspondances, et pas seulement la première.

Règles :

• GET rejette les sélecteurs génériques (ambigus) → 400
• POST et DELETE acceptent les caractères génériques — l'opération s'applique à toutes les correspondances
• Les réponses 404 utilisent la forme no device matches selector '<sel>', où <sel> est l'expression de sélecteur d'origine telle qu'elle a été reçue

Valeurs prises en charge pour {device_type} : inverse3, verse_grip, wireless_verse_grip, ou les caractères génériques de famille *inverse, *verse_grip.

Sélecteur de session — paramètre de requête ?session=<expr>

Les points de terminaison HTTP à portée de session (basis, mount, preset, filters, navigation, SDF) nécessitent un paramètre de requête ?session=<expr> pour identifier le contexte de la session dans lequel intervenir.

Expression	Signification
(omis)	Toutes les sessions (autorisées uniquement sur DELETE)
#123 ou 123	Session dont l'identifiant numérique est 123
:0	Première session selon l'index
:-1	Dernière session selon l'index
profile_name	Première session avec ce profil (peut-être ambigu)
profile_name:0	Première session avec ce profil, à l'index 0
:default:0	Première session avec ce profil default à l'index 0
co.haply.hub::*:0	Première session dont le profil commence par co.haply.hub:: (caractère générique « glob »)
:co.haply.hub::*:-1	Dernière session de l'espace de noms co.haply.hub::

Exemple :

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

Caractères génériques dans les noms de profil

Les motifs de profil acceptent deux métacaractères globaux :

Métacaractère	Signification
*	correspond à n'importe quelle séquence de caractères (y compris une séquence vide)
?	correspondent à exactement un caractère

Tout autre caractère — y compris :, ., -, [, ] — est comparé littéralement (les classes de caractères telles que [abc] ne sont pas pas (prises en charge). La correspondance tient compte de la casse.

Un * seul (ou all) conserver sa signification actuelle, c'est-à-dire toutes les sessions. Pour trouver les profils dont le nom commence par *, ajoutez au moins un autre caractère (par exemple *foo).

Motifs utiles :

• co.haply.hub::* — tout profil de l'espace de noms co.haply.hub::
• *-update — tout profil se terminant par -update
• co.haply.*:* — tout profil dont l'espace de noms commence par co.haply.
• defaul? — tout profil de 7 caractères commençant par defaul

Un motif générique est ambigu à lui seul (il peut correspondre à plusieurs sessions). Pour l'utiliser sur un point de terminaison GET / POST, dissipez l'ambiguïté à l'aide d'un :<index> final :

# 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

Les caractères génériques ambigus (sans index) sont rejetés avec 400 sur GET/POST. Ils sont autorisés sur les routes qui acceptent explicitement plusieurs correspondances de session — GET /sessions/<sel> (renvoie toutes les correspondances) et les points d'extrémité DELETE (applicables à toutes les correspondances).

Sélecteur de session — chemin d'accès de l'URL

Le point d'arrivée /sessions/{selector} accepte la la même expression qu'un paramètre de chemin — utile pour rechercher une session précise ou vérifier si elle existe :

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

Cela revient au même que GET /sessions?session=<selector> ; les deux routes font appel au même gestionnaire. GET /sessions/<sel> est l'un des rares points de terminaison qui acceptent un motif générique ambigu sans suffixe :<index> — il renvoie tous les courriers dans la même enveloppe de liste que GET /sessions.

Transmettez les sélecteurs tels quels

Chaque type de sélecteur mentionné ci-dessus — y compris #42 et les motifs en relief avec * — est transmise telle quelle par les clients HTTP standard (Python requests, libhv, curl, fetch). Aucun encodage d'URL côté client n'est nécessaire. Dans l'interpréteur de commandes, mettez entre guillemets les jetons qui contiennent # ou * (par ex. --session "#42", --session "co.haply.hub::*:0") pour empêcher l'interpréteur de les traiter comme des commentaires ou de les développer en motifs génériques sur les fichiers locaux.

Une exception : le métacaractère « glob » ? est le délimiteur de requête dans l'URL dans les chemins. Dans un sélecteur de forme de chemin (par ex. /sessions/defaul?:0), il doit être exprimé en pourcentage sous la forme %3F — GET /sessions/defaul%3F:0. Dans un sélecteur de forme de requête (?session=defaul?:0), seul le premier ? sépare la requête et les ? Les éléments suivants sont transmis tels quels.

Les sessions WebSocket ne nécessitent pas de sélecteurs

Sur une connexion WebSocket, vous êtes La session : vos entrées configure et commands ciblent automatiquement les appareils de la session en cours. Les sélecteurs de session ne sont nécessaires que pour les requêtes HTTP (y compris la télécommande entre deux sessions — voir Séances).