Utiliser l’API locale AppSport¶

Les rubriques de lecture match, matchDays, scorers et standings décrites dans ce guide sont disponibles depuis la V3.0.1. Les commandes et les protections existantes restent compatibles.

Cette API lit et commande le match chargé dans la fenêtre principale AppSport. Utilisez-la pour Companion, les boutons du chrono, les sélections, les événements et les habillages Live Output. Elle peut aussi recevoir les données de Scoreboard OCR pour alimenter les sorties graphiques.

Activer et connecter un outil¶

1. Ouvrez Configuration → AppSport settings → Local API.
2. Cochez Enable API, choisissez le port (par défaut 18800), puis Apply.
3. Vérifiez Running. Utilisez Copy URL et, si Require API key est coché, Copy API key.
4. Ouvrez le match dans la fenêtre principale et attendez son chargement complet.
5. Pour consulter les éléments disponibles, cliquez sur Show match commands.

Les réglages peuvent être appliqués sans match. Le catalogue et les commandes deviennent disponibles une fois le match chargé. Si le catalogue vous demande d’ouvrir un match, revenez à la fenêtre principale, ouvrez la rencontre, attendez son chargement puis consultez à nouveau les commandes.

Télécharger le module Companion et suivre le guide Consulter le Swagger local

Connecter Scoreboard OCR, les scores et l’horloge

Pour un outil sur un autre poste, activez Allow network access et choisissez l’adresse du PC AppSport. La clé locale appartient à ce PC : elle ne correspond pas aux jetons créés dans le menu du compte.

Si vous désactivez explicitement Require API key, les appareils capables de joindre l’API peuvent lire et commander le match avec vos droits. Appliquez ce changement avant de laisser la clé vide dans Companion. Pour limiter l’accès au même PC, désactivez l’accès réseau.

Lecture HTTP¶

$headers = @{ Authorization = 'Bearer COPIER_LA_CLE_LOCALE' }
$state = Invoke-RestMethod -Uri 'http://127.0.0.1:18800/api/v1/state' -Headers $headers
$state.contextKey
$state.buttons

state rassemble contexte, chrono, scores, boutons, textes, joueurs, événements, types, statistiques, sélections et préparation. Les catalogues ont aussi leurs routes dédiées. Les lectures de texte individuel renvoient du text/plain.

L’état contient également les données sportives structurées suivantes, disponibles avec les mêmes autorisations sur leurs routes de lecture :

Par exemple, GET /api/v1/match renvoie { "contextKey": "futsal:1:2", "match": { ... } }. Les trois autres routes utilisent la même enveloppe avec leur tableau. Les champs sont aussi présents dans chaque message WebSocket state ; aucun nouvel abonnement n’est nécessaire.

La journée utilise son libellé réel : l’ID de base de données n’est jamais interprété comme un numéro de journée. Un texte inconnu vaut "", un score inconnu vaut null, et un score nul vaut 0. Les autres rencontres restent limitées au championnat et aux équipes autorisées. Ces lectures utilisent les données déjà chargées dans la page, sans déclencher de scraping ni de requête supplémentaire ; les tableaux se complètent à mesure du chargement et des mises à jour de la page.

scorers exclut les tirs au but et les événements optimistes en attente de sauvegarde. points vaut 1 pour les buts et 1, 2 ou 3 au basketball. ownGoal identifie un CSC ; side est l’équipe à laquelle le score est attribué. Le nom peut être vide si le joueur n’est plus dans l’effectif chargé. Au tennis, le tableau est vide, les noms tiennent compte des partenaires en double et les scores structurés représentent les sets gagnés. Les sets et points en cours restent accessibles dans les données tennis existantes.

Les scores de match correspondent aux données du match. Les valeurs graphiques OCR restent accessibles dans texts et ocr, comme décrit ci-dessous.

Lorsque des valeurs OCR sont reçues, state.ocr.values contient les lectures brutes et state.ocr.mappedValues leurs noms d’export. state.texts.clock, score_home, score_away et period reflètent les associations CLOCK_MLS, T1_SCORE, T2_SCORE et SET_MLS. Ces données d’habillage ne modifient pas automatiquement les scores ni les événements enregistrés du match.

Les valeurs brutes sont utilisables directement dans les sorties, sans association : ocr.2_SCORE.Text dans une carte OGraf, un champ homonyme dans un titre vMix, ou la clé brute dans les données CasparCG. Un nom brut déjà égal à une variable commune, par exemple CLOCK_MLS, alimente aussi celle-ci ; une association explicite reste prioritaire en cas de collision. Pour lire une clé contenant un point depuis un script, utilisez par exemple $state.ocr.values.'2_SCORE.Text' en PowerShell ou state.ocr.values['2_SCORE.Text'] en JavaScript.

Commander et suivre le résultat¶

Envoyez un POST avec contextKey lu dans l’état actuel :

$headers['Idempotency-Key'] = [guid]::NewGuid().ToString()
$body = @{ contextKey = $state.contextKey; gesture = 'left' } | ConvertTo-Json
# Remplacer BUTTON_ID par un ID du catalogue.
$command = Invoke-RestMethod -Method Post -Uri 'http://127.0.0.1:18800/api/v1/buttons/BUTTON_ID/click' -Headers $headers -ContentType 'application/json' -Body $body
Invoke-RestMethod -Uri ("http://127.0.0.1:18800" + $command.statusUrl) -Headers $headers

La réponse 202 accuse la réception. Suivez statusUrl jusqu’à accepted ou failed. Pour un bouton graphique, accepted indique sa remise au gestionnaire, sans garantir la fin de l’animation. Les gestes possibles sont left, middle, right et reset, selon le bouton.

Les actions métier utilisent POST /api/v1/actions/{actionId} avec { "contextKey": "...", "params": { ... } }. Le catalogue expose les actions disponibles : choisir un joueur, préparer ou enregistrer un événement / remplacement, confirmer ou annuler une préparation, ajuster une statistique ou supprimer un événement. Leur disponibilité dépend du sport, du match, des droits et du mode édition.

Utilisez une Idempotency-Key différente par action volontaire. Réutiliser la même clé avec le même contenu retrouve la commande pendant sa rétention, sans deuxième exécution. La clé ne protège pas contre deux intentions distinctes. Les commandes terminées sont conservées jusqu’à 60 secondes après leur création ; les commandes en attente restent consultables.

WebSocket¶

Le flux utilise ws://IP:PORT/api/v1/ws, sans token dans l’URL. En mode protégé, fournissez l’en-tête Bearer lors de l’ouverture ou une première trame { "type": "auth", "token": "CLE_LOCALE" } sous cinq secondes. Les messages ready, state, unavailable, heartbeat, ack, command et error décrivent le transport et les commandes.

Après un message unavailable, retirez les données de l’ancien match. Relisez le contexte avant de commander à nouveau. Companion gère automatiquement le WebSocket et le secours HTTP.

L’API locale limite les origines navigateur. Utilisez Companion, curl ou un client natif sur le réseau du poste pour les essais. Le Swagger public documente les requêtes HTTP et le flux ; il ne permet pas de commander un PC depuis le site d’aide.

Entrée Scoreboard OCR¶

Sélectionnez Scoreboard OCR comme Source de table de marque, activez l'API locale puis cliquez sur Enregistrer. Cette source utilise le serveur de Enable API, sans activation OCR séparée. Les réglages API sont partagés avec Local API. Bodet et l'OCR sont exclusifs ; une connexion OCR est refusée avec HTTP 409 si une autre source est enregistrée. Configurez les associations et consultez les relevés reçus et appliqués dans Table de marque → Scoreboard OCR. Copier l'URL OCR fournit ws://IP:PORT/api/v1/ocr/CLE_ENTREE_OCR si Require API key est coché ; cette clé privée autorise uniquement les relevés. Si la protection est désactivée et appliquée, l'URL est simplement ws://IP:PORT/api/v1/ocr/, par exemple ws://192.168.0.40:18800/api/v1/ocr/.

Scoreboard OCR utilise la sortie Web Socket et envoie { "type": "ocr", "values": { "time": "3:12", "score_a": "56" } }. AppSport accepte l’enregistrement register avec le rôle ocr, répond à ping par pong et conserve les champs omis dans un relevé partiel. Une seule source OCR peut se connecter à la fois. Le guide Scoreboard OCR explique la configuration et les sorties OGraf, vMix et CasparCG.

Persistance des réglages¶

Save to .appsport enregistre les réglages API et les associations OCR sous localControl. Apply les mémorise sur le poste sans modifier le fichier projet. Rouvrir un projet contenant cette rubrique réapplique ses réglages ; un ancien projet sans rubrique conserve ceux du poste. Les clés privées et les lectures OCR ne sont pas exportées dans le .appsport.

Enregistrer dans Table de marque sauvegarde aussi la source sous scoreboardTable et propose de créer le projet si aucun fichier n'est ouvert. Un ancien projet utilisant l'OCR sans ce choix doit enregistrer la source Scoreboard OCR. En mode édition, les relevés sont visibles dans le diagnostic natif mais ne sont pas appliqués au match ni publiés dans state.ocr.