Rückrufe bei Betriebsstörungen

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.

Übersicht

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 eingestellt auf "forceDisconnected". 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.

Voraussetzungen

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

Für Status-Callbacks zu Archiv, Übertragung 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 läuft, abstürzt, wird die Sitzung beendet und die Plattform sendet eine sessionDestroyed Ereignis an Ihren Endpunkt für die Sitzungsüberwachung.

Callback-Nutzdaten

{
  "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 Ihre Kunden, die Verbindung erneut herzustellen – über Ihren eigenen Signalisierungskanal, per Push-Benachrichtigung oder per 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);
});

Störung im Archiv (Aufzeichnung)

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

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);
});

Störung der Übertragung

Wenn ein Broadcast-Knoten 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);
});

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". Die Verbindungsdaten einer SIP-Verbindung enthalten in der Regel einen sip Kennung, damit Sie diese von den Verbindungen der regulären Teilnehmer unterscheiden können.

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

SIP-Verbindungen durch Überprüfung identifizieren connection.data, dann wählen Sie erneut:

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

  if (event === 'callDestroyed' && reason_message === 'Unexpected Clearing') {
    let connData = {};
    try { connData = JSON.parse(connection.data); } catch (_) {}

    if (connData.sip) {
      // Re-initiate the SIP call
      const sipUri = getSipUriForConnection(connection.id);
      opentok.dial(sessionId, token, sipUri, sipOptions, (err, call) => {
        if (err) console.error('SIP redial failed:', err);
        else console.log('SIP call re-established:', call.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.

Weiterführende Ressourcen

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