How to receive service disruption callbacks and recover each affected service after an internal platform failure.

Dieses Thema umfasst die folgenden Abschnitte:

• Übersicht
• Voraussetzungen
• Unterbrechung der Sitzung
• Störung im Archiv (Aufzeichnung)
• Störung der Übertragung
• Störung bei SIP-Anrufen
• Untertitel-Störung
• Bewährte Praktiken

Übersicht

Die Vonage Video-Plattform überwacht kontinuierlich alle laufenden Dienste. Wenn ein interner Fehler einen Dienst beeinträchtigt – beispielsweise ein Absturz des Medienservers, ein Ausfall des Archivierungssystems, der Ausfall eines Übertragungsknotens, ein Problem mit dem SIP-Gateway oder ein Fehler der Untertitel-Engine –, erkennt das Überwachungssystem der Plattform den Fehler, aktualisiert den Dienststatus und sendet umgehend eine Rückrufbenachrichtigung an Ihren registrierten Endpunkt.

In diesem Leitfaden wird erläutert, welche Callbacks die einzelnen Dienste bei einer Störung auslösen, wie die Payloads aussehen und wie die einzelnen Dienste programmgesteuert wiederhergestellt werden können.

Betriebsstörungen können jeden der folgenden Vonage Video-Dienste betreffen:

In allen Fällen gilt, dass die reason Das Feld in der Callback-Nutzlast lautet normalerweise auf … einstellen "Internal server failure". Je nach Art des Fehlers können auch andere Fehlercodes auftreten; daher sollte Ihr Wiederherstellungscode jede unerwartete Beendigung (die nicht durch Ihre eigenen API-Aufrufe verursacht wurde) als potenzielle Störung behandeln.

Anmerkung: Die Plattform sendet außerdem Warnmeldungen vor Ausfällen im Zusammenhang mit Serverwechseln (reason: "serverRotation") über die sessionNotification Veranstaltung. Siehe Server-Rotation und Sitzungsmigration Weitere Informationen zu diesem konkreten Szenario.

Voraussetzungen

Um serverseitige Callbacks bei Störungen zu erhalten, müssen Sie einen Callback für die Sitzungsüberwachung URL für Ihr Projekt. Siehe Überwachung von Sitzungen für Anweisungen zur Einrichtung.

Für Callbacks zum Status von Archiven, Sendungen und Untertiteln konfigurieren Sie die entsprechende Status-Callback-URL in Ihrer Projekt-Dashboard der Vonage Video API.

Unterbrechung der Sitzung

Wenn der Media Router, auf dem eine Sitzung gehostet wird, abstürzt, wird die Sitzung beendet und die Plattform sendet eine sessionDestroyed Ereignis an Ihren Endpunkt für die Sitzungsüberwachung.

Callback-Nutzdaten

sessionDestroyed

{
  "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId": "123456",
  "event": "sessionDestroyed",
  "reason": "forceDisconnected",
  "timestamp": 1718000050000
}

Client SDK-Ereignisse

Parallel zu den serverseitigen Webhooks erhalten Clients Lebenszyklusereignisse über das SDK:

session.on('sessionReconnecting', () => {
  // Platform is attempting automatic reconnection via session migration
  showReconnectingBanner();
});

session.on('sessionReconnected', () => {
  // Automatic recovery succeeded — no further action needed
  hideReconnectingBanner();
});

session.on('sessionDisconnected', (event) => {
  // Automatic recovery failed or is not enabled
  if (event.reason === 'networkDisconnected' || event.reason === 'networkTimedout') {
    promptUserToRejoin();
  }
});

publisher.on('streamDestroyed', (event) => {
  if (event.reason === 'networkDisconnected') {
    event.preventDefault(); // Keep the publisher element in the DOM
    retryPublish();
  }
});

Verwenden Sie für native SDKs die entsprechenden Delegate-Methoden:

• iOS: OTSessionDelegate.sessionDidBeginReconnecting(_:) / sessionDidReconnect(_:) / sessionDidDisconnect(_:)
• Android: Session.SessionListener.onReconnecting() / onReconnected() / onDisconnected()

Erholung

Wenn sessionDisconnected Feuer mit reason: "forceDisconnected" (oder nach sessionReconnecting Zeitüberschreitungen):

1. Erstellen Sie eine neue Sitzung über die REST-API oder ein Server-SDK.
2. Geben Sie für alle Teilnehmer neue Token aus.
3. Bitten Sie die Kunden, die Verbindung erneut herzustellen – über Ihren eigenen Signalisierungskanal, per Push-Benachrichtigung oder über eine In-App-Nachricht.

// Server-side — handle sessionDestroyed with reason "forceDisconnected"
app.post('/callbacks/vonage/session', (req, res) => {
  const { event, reason, sessionId } = req.body;

  if (event === 'sessionDestroyed' && reason === 'forceDisconnected') {
    createNewSessionAndNotifyClients(sessionId);
  }

  res.sendStatus(200);
});

Tipp: Wenn Sitzung Migration ist aktiviert, kann die Plattform die Sitzung möglicherweise automatisch wiederherstellen. In diesem Fall sessionReconnected wird auf dem Client gestartet, und ein manueller Neustart ist nicht erforderlich.

Störung im Archiv (Aufzeichnung)

Wenn ein Archivierungsprozess während der Aufzeichnung abstürzt, erkennt das Überwachungssystem der Plattform den Ausfall und kennzeichnet das Archiv als "failed", und sendet einen Status-Callback an die von Ihnen registrierte Archiv-Status-URL .

Callback-Nutzdaten

{
  "id": "b40ef09b-3811-4726-b508-e41a0f96c68f",
  "event": "archive",
  "status": "failed",
  "reason": "Internal server failure",
  "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId": "123456",
  "name": "My Recording",
  "createdAt": 1718000000000,
  "duration": 0,
  "outputMode": "composed",
  "hasVideo": true,
  "hasAudio": true
}

Schlüsselfelder:

Erholung

app.post('/callbacks/vonage/archive', (req, res) => {
  const { status, reason, sessionId } = req.body;

  if (status === 'failed' && reason === 'Internal server failure') {
    // Start a new archive for the same session
    opentok.startArchive(sessionId, { name: 'Resumed recording' }, (err, archive) => {
      if (err) console.error('Failed to restart archive:', err);
      else console.log('New archive started:', archive.id);
    });
  }

  res.sendStatus(200);
});

Anmerkung: Verify stets, dass die Sitzung noch aktive Teilnehmer hat, bevor Sie das Archiv neu starten. Das Starten eines Archivs bei einer leeren Sitzung führt zu einem Fehler.

Störung der Übertragung

Wenn ein Übertragungsknoten ausfällt, wird der HLS- oder RTMP-Stream beendet und die Übertragung wird als "failed". Ein Status-Callback wird an Ihre Broadcast-Status-URL gesendet.

Callback-Nutzdaten

{
  "id": "1748b707-0a81-464c-9759-c46ad10d3734",
  "sessionId": "2_MX4xMDBfjE0Mzc2NzY1NDgwMTJ-TjMzfn4",
  "applicationId": 100,
  "createdAt": 1437676551000,
  "updatedAt": 1437676551000,
  "event": "broadcast",
  "group": "status",
  "resolution": "640x480",
  "streamMode": "auto",
  "streams": [],
  "broadcastUrls": {
    "hls": "http://server/fakepath/playlist.m3u8",
    "hlsStatus": "error",
    "rtmp": {
      "foo": {
        "serverUrl": "rtmps://myfooserver:443/myfooapp",
        "streamName": "myfoostream",
        "status": "error"
      },
      "bar": {
        "serverUrl": "rtmp://mybarserver:443/mybarapp",
        "streamName": "mybarstream",
        "status": "error"
      }
    }
  },
  "settings": {
    "hls": {
      "dvr": false,
      "lowLatency": false
    }
  },
  "status": "failed",
  "reason": "internal server failure"
}

Erholung

1. Erhalten Sie die "failed" Status-Callback.
2. Warten Sie, bis die Clients die Verbindung zur Sitzung wiederhergestellt haben (auf connectionCreated Veranstaltungen, oder Teilnehmer an Umfragen).
3. Eine neue Übertragung starten:

app.post('/callbacks/vonage/broadcast', (req, res) => {
  const { status, reason, sessionId } = req.body;

  if (status === 'failed' && reason === 'Internal server failure') {
    waitForParticipants(sessionId).then(() => {
      opentok.startBroadcast(sessionId, broadcastOptions, (err, broadcast) => {
        if (err) console.error('Failed to restart broadcast:', err);
        else notifyViewersOfNewStreamUrl(broadcast.broadcastUrls);
      });
    });
  }

  res.sendStatus(200);
});

Das ist wichtig: Die HLS-URL ändert sich bei jeder neuen Übertragung. Stellen Sie sicher, dass alle Player oder nachgeschalteten Systeme, die den Stream nutzen, mit der neuen URL aktualisiert werden.

Störung bei SIP-Anrufen

Wenn durch einen Ausfall des SIP-Gateways eine aktive Verbindungsstrecke unterbrochen wird, wird die SIP-Verbindung beendet und die Plattform sendet callDestroyed an Ihren Endpunkt für die Sitzungsüberwachung mit reason_message: "Unexpected Clearing".

Callback-Nutzdaten

{
  "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "applicationId": "123456",
  "event": "callDestroyed",
  "reason_code": "703",
  "reason_message": "Unexpected Clearing",
  "timestamp": 1718000050000,
  "call": {
    "id": "<conference-id>",
    "connectionId": "<sip-ot-connection-id>",
    "createdAt": 1470257688143
  }
}

Erholung

app.post('/callbacks/vonage/session', (req, res) => {
  const { event, reason_message, call, sessionId } = req.body;

  if (event === 'callDestroyed' && reason_message === 'Unexpected Clearing') {
    // Re-initiate the SIP call
    const sipUri = getSipUriForCall(call.id);
    opentok.dial(sessionId, token, sipUri, sipOptions, (err, newCall) => {
      if (err) console.error('SIP redial failed:', err);
      else console.log('SIP call re-established:', newCall.id);
    });
  }

  res.sendStatus(200);
});

Untertitel-Störung

Wenn die Untertitel-Engine ausfällt, wird die Live-Transkription unterbrochen und die Untertitel-Sitzung wird als "failed". Ein Status-Callback wird an die URL für den Status Ihrer Untertitel gesendet.

Callback-Nutzdaten

{
  "captionsId": "<captionsId>",
  "projectId": "<applicationId>",
  "sessionId": "<sessionId>",
  "status": "failed",
  "createdAt": 1651253477,
  "updatedAt": 1651253837,
  "duration": 360,
  "languageCode": "en-US",
  "reason": "Internal server failure",
  "provider": "aws-transcribe",
  "event": "sessionStatus"
}

Erholung

app.post('/callbacks/vonage/captions', (req, res) => {
  const { status, reason, sessionId } = req.body;

  if (status === 'failed' && reason === 'Internal server failure') {
    // Restart captions for the session
    fetch(`https://video.api.vonage.com/v2/project/${PROJECT_ID}/captions`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${jwt}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ sessionId, token: generateToken(sessionId) })
    })
    .then(res => res.json())
    .then(data => console.log('Captions restarted:', data.captionsId))
    .catch(err => console.error('Failed to restart captions:', err));
  }

  res.sendStatus(200);
});

Bewährte Praktiken

• Überprüfen Sie immer die reason Feld, aber verlassen Sie sich nicht ausschließlich darauf. Zwar gehen Störungen in der Regel mit "Internal server failure", sollte Ihre Wiederherstellungslogik alle unerwarteten "failed" Status oder <something>Destroyed Ereignis als potenzielle Störung der Plattform.
• Implementieren Sie idempotente Wiederherstellungshandler. Callbacks können mehrmals ausgelöst werden. Verwenden Sie die Ressourcen-ID (archive.id, captionsId, session.id), um Duplikate zu entfernen.
• Verwenden Sie Warnungen vor der Drehung. Die sessionNotification Veranstaltung (mit remainingTime: 3600 oder 14400) informiert Sie im Voraus über geplante Rotationen. Nutzen Sie diese Funktion, um Archive, Sendungen und Untertitel vor der Rotation ordnungsgemäß zu beenden und so einen abrupten "forceDisconnected" Kündigung.
• Alle Störungsereignisse protokollieren mit ihrer gesamten Nutzlast zur Analyse nach dem Vorfall. Die timestamp Das Feld dient als Referenzwert für die Berechnung der Wirkungsdauer.
• Für Sitzungen sollten Sie „Session Migration“ bevorzugen. Durch die Aktivierung der Sitzungsmigration wird der Auswirkungsbereich von Ausfällen des Media Routers drastisch reduziert, da Clients transparent auf einen funktionsfähigen Server umgeleitet werden. Siehe Server-Rotation und Sitzungsmigration.
• Benachrichtigungen einrichten für "Internal server failure" Callbacks. Ein sprunghafter Anstieg bei Internal server failure Ereignisse, die sich über mehrere Sitzungen erstrecken, sind ein frühes Anzeichen für einen umfassenderen Plattformausfall.

Siehe auch

• Überwachung von Sitzungen
• Server-Rotation und Sitzungsmigration
• Leitfaden zur Archivierung
• Sendeplan
• Leitfaden zur SIP-Anbindung
• Leitfaden zu Live-Untertiteln