Migration des sessions : Mise en place et configuration

Ce guide fournit des instructions de configuration détaillées et des exemples de code pour permettre la migration des sessions sur toutes les plates-formes prises en charge. Pour une vue d'ensemble de la rotation des serveurs et de son impact sur les sessions, voir Rotation des serveurs et migration des sessions.

Vue d'ensemble

Les serveurs multimédias de Video API de Vonage font l'objet d'une rotation périodique dans le cadre de la maintenance normale du cloud, de l'autoscaling et des mises à jour de l'infrastructure. Les sessions qui durent plus de 8 heures sont particulièrement susceptibles d'être affectées.

Session Migration est disponible auprès de SDK version 2.30.0 et a atteint Disponibilité générale (GA) dans le SDK 2.31.0 (août 2025).

Comment ça marche

1. Le backend de Vonage détecte qu'un serveur média hébergeant une session est programmé pour une rotation.
2. A sessionNotification est envoyé au point de rappel de votre serveur - à l'adresse 4 heures et à nouveau à 1 heure avant la rotation.
3. Si la migration de session est activée, la plateforme migre automatiquement toutes les connexions éligibles vers un nouveau serveur média.
4. Les clients se reconnectent de manière transparente avec un temps d'arrêt minimal. La reconnexion s'effectue généralement en quelques secondes.

Ce qui est migré automatiquement et ce qui nécessite une action manuelle

Lors d'une migration de session, tous les services ne sont pas gérés automatiquement. Utilisez le tableau ci-dessous pour comprendre ce que votre application doit gérer.

Activation de la migration automatique des sessions

Client SDK (Web / Native)

Activer la migration de session en passant sessionMigration: true lors de l'initialisation d'une session :

Web (JavaScript)

const session = OT.initSession(apiKey, sessionId, {
  sessionMigration: true
});

iOS (Swift)

let settings = OTSessionSettings()
settings.sessionMigration = true
let session = OTSession(apiKey: apiKey, sessionId: sessionId, delegate: self, settings: settings)

Android (Kotlin)

val settings = Session.SessionProperties.Builder()
    .sessionMigration(true)
    .build()
val session = Session(context, apiKey, sessionId, settings)

React Native

// Pass sessionMigration in the OTSession options prop
<OTSession
  apiKey={apiKey}
  sessionId={sessionId}
  token={token}
  options={{ sessionMigration: true }}
>

SIP (Dial API)

Pour activer la migration de session pour les connexions SIP, inclure sessionMigration: true dans le corps de la demande de l'API Dial :

{
  "sessionId": "<session-id>",
  "token": "A valid token with the role set to moderator",
  "sip": {
    "uri": "sip:user@sip.partner.com;transport=tls",
    "from": "from@example.com",
    "sessionMigration": true
  }
}

Connecteur audio (Connect API)

Pour activer la migration de session pour les connexions WebSocket de l'Audio Connector, inclure sessionMigration: true dans le corps de la demande de l'API Connect :

{
  "sessionId": "<session-id>",
  "token": "A valid token with the role set to moderator",
  "websocket": {
    "uri": "wss://your-websocket-server.example.com",
    "sessionMigration": true
  }
}

Connecteur vidéo (Python SDK)

Pour activer la migration de session pour le connecteur vidéo, définissez les paramètres suivants enable_migration=True dans les paramètres de votre session :

from vonage_video_connector import VonageVideoClient
from vonage_video_connector.models import SessionSettings

session_settings = SessionSettings(enable_migration=True)
client = VonageVideoClient()
client.connect(
    application_id="<application-id>",
    session_id="<session-id>",
    token="<token>",
    session_settings=session_settings
)

Déclencher manuellement la migration des sessions

En plus de la migration automatique lors de la rotation des serveurs, vous pouvez déclencher manuellement une migration de session à l'aide de l'API REST. Ceci est utile pour :

• Migration proactive d'une session avant une rotation programmée (par exemple, au bout de 7,5 heures)
• Tester et simuler le comportement de rotation du serveur dans votre application
• Donner aux clients le contrôle sur le moment de la migration (par exemple, pendant une pause au cours d'une longue réunion).

Migration de l'API de session

Méthode : POST

URI :

/v2/project/<projectId>/session/<sessionId>/migrate

En-têtes :

Exemple de demande :

Codes de réponse

Gestion des événements de notification de session

La plateforme Vonage envoie sessionNotification à votre serveur avant une rotation programmée. Vous pouvez les utiliser pour informer les utilisateurs de manière proactive ou pour déclencher une migration manuelle à un moment opportun.

Exemple de charge utile de rappel :

{
  "sessionId": "<session-id>",
  "projectId": "<project-id>",
  "event": "sessionNotification",
  "reason": "serverRotation",
  "remainingTime": 3600
}

Pour recevoir ces événements, configurez une URL de rappel de surveillance de session dans votre fichier Tableau de bord de l'API Vonage.

Notes

• La migration des sessions ne s'applique qu'aux rotation du serveur média. Elle ne couvre pas la rotation des serveurs SIP ou TURN, qui sont gérés séparément par la plateforme.
• sessionMigration La valeur par défaut est false et doit être explicitement activée sur chaque connexion client qui doit être automatiquement reconnectée. Les connexions qui n'ont pas ce drapeau seront fermées pendant la migration.
• La version minimale du SDK requise est la suivante 2.30.0. Assurez-vous que tous les clients utilisent le SDK 2.30.0 ou une version ultérieure.
• Pour les connexions SIP et Audio Connector, la branche d'appel externe (SIP ou WebSocket) reste connectée pendant la migration. Les connexions média sont rétablies sur le nouveau serveur. Un bref silence peut se produire sur le point d'extrémité pendant le basculement.
• L'archivage, la diffusion, Experience Composer et les sous-titres en direct doivent être redémarrés manuellement après la migration. Pour Experience Composer, redémarrer sur le serveur même ID de session - la session migrée conserve le même identifiant de session sur le nouveau serveur.
• Après la migration, le nouveau serveur fournit un Fenêtre de grâce de 10 minutes pour permettre aux clients de se reconnecter et aux services de reprendre. Pendant cette fenêtre, toute tentative de reconnexion ou demande d'API (comme le lancement d'une archive) est automatiquement dirigée vers le nouveau serveur.
• L'API Migrate Session empêche les migrations multiples et simultanées. Si une migration est déjà en cours, l'API renvoie une valeur de 409 erreur avec le code 15214. Si elle est appelée trop tôt après la création de la session ou une migration précédente, elle renvoie l'information suivante 409 avec code 15215.
• Pour les sessions approchant les 8 heures, envisagez de déclencher proactivement la migration au bout de 7,5 heures à l'aide de l'API Migrate Session afin d'éviter les interruptions pendant les pics d'utilisation.
• Moniteur sessionNotification événements - utilisez les avertissements de 4 heures et d'une heure pour informer les utilisateurs de manière proactive ou planifiez une migration manuelle à un moment où le trafic est faible.