API REST Proxima : contrôle à distance du volume, de la mise en sourdine et de l'alimentation

Les serveurs Proxima 4020, 4040 et 4060 peuvent être contrôlés à distance via une interface API REST simple et efficace. Cette API publique vous permet de contrôler le volume audio, de gérer l’état du mute et d’effectuer des actions système telles que le redémarrage ou l’arrêt.

Ce document présente tous les points de terminaison disponibles, leur fonctionnement et un exemple concret d’intégration HTML/JavaScript.

TABLE DES MATIÈRES

• Documentation publique de l’API REST disponible
  • API Lecteur
    • Mute
    • Unmute
    • Basculer le mute
    • Définir et obtenir le volume
    • Définir le mode de maintenance
  • API Alimentation
    • Redémarrer
    • Arrêter
• Exemple en HTML/JavaScript

Documentation publique de l’API REST disponible

Dans cette section, vous trouverez la liste de tous les points de terminaison API disponibles, regroupés par fonctionnalité. Chaque point de terminaison est brièvement décrit pour vous aider à identifier celui qui correspond à vos besoins d’intégration.

API Lecteur

Mute

• Méthode : POST ou GET
• Chemin de l’API :

  /api/player/mute
  

• Description : Activer le mute audio.
• Authentification : (aucune)
• Paramètres de requête : (aucun paramètre)
• Exemples :

  http://192.168.1.1/api/player/mute                    // activer le mute audio
  

• Réponses :

  Code	Type	Description	Retourne
  200	Succès	La requête a réussi	(null)
  417	Erreur	Échec de l’expectative	(null)

Unmute

• Méthode : POST ou GET 
• Chemin de l’API :

  /api/player/unmute
  

• Description : Désactiver le mute audio.
• Authentification : (aucune)
• Paramètres de requête : (aucun paramètre)
• Exemples :

  http://192.168.1.1/api/player/unmute                    // désactiver le mute audio
  

Basculer le mute

• Méthode : POST ou GET 
• Chemin de l’API :

  /api/player/toggle-mute
  

• Description : Basculer le mute audio.
• Authentification : (aucune)
• Paramètres de requête : (aucun paramètre)
• Exemples :

  http://192.168.1.1/api/player/toggle-mute                    // basculer le mute audio
  

Définir et obtenir le volume

• Méthode : POST ou GET 
• Chemin de l’API :

  /api/player/set-volume?volume=<number>&relative=<boolean>
  

• Description : Définir et obtenir le volume audio (absolu ou relatif).
• Authentification : (aucune)
• Paramètres de requête :

  Champ	Type	Description
  volume (requis)	Nombre	Niveau de volume [0...100]
  relative (optionnel)	Booléen	Indique si le niveau de volume est relatif au volume actuel. Valeur par défaut : false

• Exemples :

  http://192.168.1.1/api/player/set-volume                              // Obtenir le volume
  http://192.168.1.1/api/player/set-volume?volume=60                    // définir le volume à 60
  http://192.168.1.1/api/player/set-volume?volume=10&relative=true      // Augmenter le volume de 10
  http://192.168.1.1/api/player/set-volume?volume=-20&relative=true     // Diminuer le volume de 20
  http://192.168.1.1/api/player/set-volume?volume=85&relative=false     // Définir le volume à 85
  

Définir le mode de maintenance

• Méthode : POST ou GET
• Chemin de l’API :

  /api/player/maintenance
  

• Description : true pour activer le mode maintenance, false pour quitter le mode maintenance (= redémarrer Composer)
• Authentification : (aucune)
• Paramètres de requête :

  Champ	Type	Description
  value (requis)	Booléen	true -> activer le mode maintenance, false -> quitter le mode maintenance

• Exemples :

  http://192.168.1.1/api/player/maintenance?value=true  // mettre le serveur en mode maintenance = arrêter Composer
  http://192.168.1.1/api/player/maintenance?value=false // quitter le mode maintenance = redémarrer Composer
  

API Alimentation

Redémarrer

• Méthode : POST ou GET 
• Chemin de l’API :

  /api/power/reboot
  

• Description : Redémarrer le serveur.
• Authentification : (aucune)
• Paramètres de requête : (aucun paramètre)
• Exemples :

  http://192.168.1.1/api/power/reboot                    // redémarrer le serveur
  

Arrêter

• Méthode : POST ou GET 
• Chemin de l’API :

  /api/power/shutdown
  

• Description : Arrêter le serveur.
• Authentification : (aucune)
• Paramètres de requête : (aucun paramètre)
• Exemples :

  http://192.168.1.1/api/power/shutdown                    // arrêter le serveur
  

Exemple en HTML/JavaScript

Voici une interface HTML/JavaScript prête à l’emploi pour tester et intégrer l’API REST de Proxima. Vous pouvez modifier directement l’adresse IP et les paramètres pour correspondre à votre configuration.

(Modifiez la variable ProximaURL pour qu’elle corresponde à l’adresse IPv4 de votre serveur Proxima) :

<!DOCTYPE html>
<html lang="fr">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Appel API REST Proxima</title>
  <style>
    body {
      font-family: Arial, sans-serif;
      margin: 20px;
    }
    #response {
      margin-top: 20px;
      padding: 10px;
      border: 1px solid #ccc;
      background-color: #f9f9f9;
      white-space: pre-wrap;
    }
    button {
      padding: 10px 15px;
      background-color: #007bff;
      color: white;
      border: none;
      border-radius: 5px;
      cursor: pointer;
      margin: 2px 2px 2px 2px;
    }
    button:hover {
      background-color: #0056b3;
    }
  </style>
</head>
<body>
  <h1>Appel API REST avec JavaScript</h1>    
  <div>
    <button id="apiButtonGetVolume">API Obtenir le Volume</button>    
  </div>
  <div>
    <button id="apiButtonVolumeRelative">API Définir Volume Relatif</button>
    <input type="number" id="apiVolumeRelativeParameter1" min="-100" max="100" value="0" />
  </div>
  <div>
    <button id="apiButtonVolumeAbsolute">API Définir Volume Absolu</button>
    <input type="number" id="apiVolumeAbsoluteParameter1" min="0" max="100" value="70"/>    
  </div>
  <div>
    <button id="apiButtonMute">API Mute</button>
    <button id="apiButtonUnmute">API Unmute</button>
    <button id="apiButtonToggleMute">API Basculer Mute</button>
  </div>
  <div>
    <button id="apiButtonMaintenanceOn">API Maintenance Activée</button>
    <button id="apiButtonMaintenanceOff">API Maintenance Désactivée</button>    
  </div>
  <div>
    <button id="apiButtonReboot">API Redémarrer</button>
    <button id="apiButtonShutdown">API Arrêter</button>
  </div>
  <div id="response">La réponse de l’API s’affiche ici.</div>
  <script>
    const ProximaURL = 'http://192.168.1.1'; // URL du serveur Proxima
    const apiUrlVolume = ProximaURL + '/api/player/set-volume'; // Définir le volume relatif ou absolu et obtenir le volume et les paramètres de mute
    const apiUrlMute = ProximaURL + '/api/player/mute'; // Activer le mute 
    const apiUrlUnmute = ProximaURL + '/api/player/unmute'; // Désactiver le mute 
    const apiUrlToggleMute = ProximaURL + '/api/player/toggle-mute'; // Basculer mute/désactiver mute    
    const apiUrlMaintenanceOn = ProximaURL + '/api/player/maintenance?value=true'; // Maintenance Activée
    const apiUrlMaintenanceOff = ProximaURL + '/api/player/maintenance?value=false'; // Maintenance Désactivée    
    const apiUrlReboot = ProximaURL + '/api/system/reboot'; // Redémarrer
    const apiUrlShutdown = ProximaURL + '/api/system/shutdown'; // Arrêter
    async function callApi(arg1, arg2, arg3) {
      try {
        document.getElementById('response').textContent = '';
        let APIUrl;
        if (arg2 !== undefined && arg3 !== undefined) {
          const completeArg1 = '?volume=';
          const completeArg2 = '&relative=';
          APIUrl = `${arg1 + completeArg1 + arg2 + completeArg2 + arg3}`;
        }
        else {
          APIUrl = arg1;
        }
        const response = await fetch(APIUrl, { method: "POST" });                               
        if (arg1 !== apiUrlVolume) {
          document.getElementById('response').textContent = 'Requête envoyée !';                    
        }
        else {
          if (!response.ok) {
            throw new Error(`Erreur HTTP ! statut : ${response.status}`);
          }
          const data = await response.json();
          document.getElementById('response').textContent = JSON.stringify(data, null, 2);
        }
      } catch (error) {
        document.getElementById('response').textContent = `Erreur : ${error.message}`;
        }
    }
    async function callApiPlus(arg1, arg2) {
    callApi(arg1);
    callApi(apiUrlVolume);
    }
    document.getElementById('apiButtonGetVolume').addEventListener('click', () => callApi(apiUrlVolume));
    document.getElementById('apiButtonVolumeRelative').addEventListener('click', () => callApi(apiUrlVolume, document.getElementById('apiVolumeRelativeParameter1').value, true));        
    document.getElementById('apiButtonVolumeAbsolute').addEventListener('click', () => callApi(apiUrlVolume, document.getElementById('apiVolumeAbsoluteParameter1').value, false));
    document.getElementById('apiButtonMute').addEventListener('click', () => callApiPlus(apiUrlMute, apiUrlVolume));
    document.getElementById('apiButtonUnmute').addEventListener('click', () => callApiPlus(apiUrlUnmute, apiUrlVolume));
    document.getElementById('apiButtonToggleMute').addEventListener('click', () => callApiPlus(apiUrlToggleMute, apiUrlVolume));    
    document.getElementById('apiButtonMaintenanceOn').addEventListener('click', () => callApi(apiUrlMaintenanceOn));
    document.getElementById('apiButtonMaintenanceOff').addEventListener('click', () => callApi(apiUrlMaintenanceOff));    
    document.getElementById('apiButtonReboot').addEventListener('click', () => callApi(apiUrlReboot));
    document.getElementById('apiButtonShutdown').addEventListener('click', () => callApi(apiUrlShutdown));
    </script>
</body>
</html>