Aller au contenu principal

Sélecteurs

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

Sélecteur d'appareil — chemin de l'URL​

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

Exemple de routeSignification du sélecteur
inverse3/0Premier Inverse3 selon l'index (base 0)
inverse3/A14Inverse3 dont l'identifiant d'appareil est A14
inverse3/*Tous les appareils Inverse3 (caractère générique)
*inverse/*Tous les appareils de la famille Inverse (Inverse3, Inverse3x, Minverse)
inverse3:left/0Premier Inverse3 gaucher selon l'index
*inverse:right/0Premier appareil de la famille Inverse droitier selon l'index
verse_grip/0Premier VerseGrip filaire selon l'index
wireless_verse_grip/*Tous les VerseGrip sans fil
*verse_grip/*Tous les appareils de la famille VerseGrip (filaires, sans fil, personnalisés)
*verse_grip:custom/0Premier VerseGrip personnalisé selon l'index (équivalent à custom_verse_grip/0)

Les filtres de classe sont résolus avant l'indexation​

Un sélecteur <type>:<class>/<N> applique 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 d'index 0 de la famille Inverse. Si trois appareils Inverse sont connectés (droitier, gaucher, droitier), ce sélecteur correspond au deuxième appareil, et non à l'index 0 filtré pour « doit être gaucher ».
  • inverse3:right/0 — le Inverse3 droitier d'index 0.
  • *inverse:left/3 — 404 s'il y a moins de quatre appareils Inverse gauchers connectés, même si plus de quatre appareils Inverse existent au total.

La même règle s'applique aux sélecteurs génériques : *inverse/* et *verse_grip/* correspondent à tous les appareils de la famille, et les requêtes POST / DELETE ciblant ces sélecteurs appliquent l'opération à toutes les correspondances, et non 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 est appliquée à toutes les correspondances
  • Les réponses 404 utilisent la forme no device matches selector '<sel>', où <sel> est l'expression de sélecteur originale telle que 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) exigent un paramètre de requête ?session=<expr> pour identifier le contexte de la session dans lequel opérer.

ExpressionSignification
(omis)Toutes les sessions (autorisé uniquement sur DELETE)
#123 ou 123Session dont l'identifiant numérique est 123
:0Première session selon l'index
:-1Dernière session selon l'index
profile_namePremière session avec ce profil (peut être ambigu)
profile_name:0Première session avec ce profil, à l'index 0
:default:0Première session avec le profil default à l'index 0
co.haply.hub::*:0Première session dont le profil commence par co.haply.hub:: (caractère générique glob)
:co.haply.hub::*:-1Derniè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 glob :

MétacaractèreSignification
*correspond à toute séquence de caractères (y compris une séquence vide)
?correspond à exactement un caractère

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

Un * seul (ou all) conserve sa signification existante, soit toutes les sessions. Pour correspondre à des profils dont le nom commence par *, ajoutez au moins un autre caractère (par ex. *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, levez l'ambiguïté avec 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 tolérés sur les routes qui acceptent explicitement plusieurs correspondances de session — GET /sessions/<sel> (renvoie toutes les correspondances) et les points de terminaison DELETE (appliqués à toutes les correspondances).

Sélecteur de session — chemin de l'URL​

Le point de terminaison /sessions/{selector} accepte la même expression qu'un paramètre de chemin — utile pour rechercher une session précise ou vérifier qu'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 est fonctionnellement équivalent à GET /sessions?session=<selector> ; les deux routes appellent le même gestionnaire. GET /sessions/<sel> est l'un des rares points de terminaison qui tolèrent un motif générique ambigu sans suffixe :<index> — il renvoie toutes les correspondances dans la même enveloppe de liste que GET /sessions.

Transmettez les sélecteurs tels quels

Chaque forme de sélecteur ci-dessus — y compris #42 et les motifs de profil 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 * (p. 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 comme motifs génériques sur les fichiers locaux.

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

Les sessions WebSocket n'ont pas besoin 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 sessions — voir Sessions).