Ein Video hochladen

Video-Upload-Funktion der REST-API

Die Video-Upload-Funktion der REST-API ist nützlich für die Erstellung eines benutzerdefinierten Upload-Portals oder einer Benutzeroberfläche und für Systemintegratoren zur Synchronisierung von VideoManager Pro mit einem Content-Management-System.

Hochladen mit der API

Das Hochladen mit der API erfolgt über Chunking. Sie können optional Metadaten wie einen Titel, eine Beschreibung und Schlüsselwörter hinzufügen. Sie können auch die Channel-ID und die Gruppen-ID festlegen, denen das hochgeladene Video zugewiesen wird.

Um ein Video über die REST-API hochzuladen:

1. Erstellen Sie eine Videoentität (mit einem Dateinamen) in einem spezifizierten VideoManager.

2. Rufen Sie die Upload-URL vom Endpunkt der Anlagenverwaltung ab.

3. Laden Sie das Video hoch.

In den folgenden Kapiteln wird beschrieben, wie die einzelnen Schritte mithilfe von cURL ausgeführt werden, um die Verwendung in den Beispielen zu veranschaulichen.

URLs

Die URLs in den Methoden in den folgenden Kapiteln beziehen sich auf die allgemeine Live-Instanz von movingimage. Kunden, die VideoManager Pro auf einer benutzerdefinierten Domain verwenden, müssen die URLs entsprechend anpassen.

Erstellen einer neuen Videoentität

Um den Upload-Prozess zu starten, müssen Sie zunächst eine Videoentität erstellen. Die Erstellung der Entität ermöglicht es Ihnen, die Video-ID zu erfassen, die Sie benötigen, um den Upload Ihres Videos abzuschließen.

Request

curl -v -X POST -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Content-Type: application/json" -d "{ 'title': '<VIDEO_TITLE>', 'description': '<DESCRIPTION_OF_VIDEO>', 'keywords': ['<FOO>', '<BAR>'], 'group': <ID_OF_OWNER_GROUP>, 'channel': <ID_OF_CHANNEL>, 'fileName': '<FILENAME>', 'autoPublish': true }" https://api.video-cdn.net/v1/vms/<VIDEOMANAGER_ID>/videos/

Parameter

• VIDEOMANAGER_ID Integer mandatory: ID des VideoManagers, auf den Sie das Video hochladen möchten.

• Headers

  • ACCESS_TOKEN String mandatory: Zugriffstoken (siehe „Authentifizierung“ für weitere Informationen).

• JSON Body

  • title String optional: Titel des Videos

  • description String optional: Beschreibung des Videos

  • keywords List of Strings optional: Schlüsselwörter des Videos

  • group Integer optional: ID der Besitzergruppe

  • channel Integer optional: ID des Channels

  • fileName String mandatory: Dateiname des Videos (siehe Hinweis zum Suffix unten)

  • autoPublish Boolean optional: Bei „true“ wird das Video automatisch veröffentlicht, nachdem der Upload abgeschlossen ist und das 360p mp4 transkodiert wurde.d.

Suffix des Dateinamens

Das Suffix des Dateinamens wird verwendet, um den Mime-Typ zu bestimmen. In der folgenden Tabelle sind alle unterstützten Suffixe aufgeführt.

Response

201 CREATED Die Standortdaten der Kopfzeile der Antwort geben eine URL zurück, die die neu erstellte Video-ID enthält. Sie benötigen diese Video-ID für den nächsten Schritt.

Location: https://api.video-cdn.net/v1/vms/<VIDEOMANAGER_ID>/videos/<VIDEO_ID>

Abrufen der Upload-URL

Nachdem die Videoentität erfolgreich erstellt wurde, müssen Sie die Upload-URL abrufen.

Request

curl -v -X GET -H "Authorization: Bearer <ACCESS_TOKEN>" https://api.video-cdn.net/v1/vms/<VIDEOMANAGER_ID>/videos/<VIDEO_ID>/url

Parameter

• VIDEOMANAGER_ID Integer mandatory: Die ID des VideoManagers, in dem die neue Videoentität im ersten Schritt erstellt wurde.

• VIDEO_ID String mandatory: Die Video-ID, die das System für die neue Entität erstellt hat (siehe „Erstellen einer neuen Video-Entität“).

• Headers

  • ACCESS_TOKEN String mandatory: Zugriffstoken (Zugriffs- und Refreshtoken).

Response

201 CREATED

Die Upload-URL wird im HTTP-Antwort-Header unter location zurückgesendet.

Response Format

Location: https://asset-in.video-cdn.net/chunks/vms/<VIDEOMANAGER_ID>/videos/<VIDEO_ID>?bucketId=<INTERNAL_BUCKET_ID>&fileId=<INTERNAL_FILE_ID>&userId=<USER_ID>&__token__=<EXPIRY_TIME>~<HEX_VALUE>

Hinweise

• Die Werte <INTERNAL_BUCKET_ID>, <INTERNAL_FILE_ID>, <USER_ID>, <EXPIRY_TIME> und <HEX_VALUE> sind systemgeneriert und dürfen nicht geändert werden.

• Das Zeichen zwischen <EXPIRY_TIME> und <HEX_VALUE> ist eine Tilde (~), kein Bindestrich.

Die URL hat ein zeitlich begrenztes Token, das vier Stunden lang gültig ist. Das bedeutet, dass ein Fehler auftritt, wenn das Hochladen des Videos länger als vier Stunden dauert. Führen Sie in diesem Fall diese Anforderung erneut aus, um eine neue Upload-URL zu generieren.

Chunked Upload mit Retry Handling

Die movingimage REST API hat ein Ratenlimit von 100 Anfragen pro Minute. Alle Anfragen, die dieses Limit überschreiten, werden abgelehnt.

Um Ihr Video hochzuladen, können Sie die Chunked-Upload-Methode mit Retry-Handling verwenden. Bei dieser Methode wird das Video in einer Reihe kleinerer Teile hochgeladen, und alle fehlgeschlagenen Teile werden erneut versucht.

Schritte

1. Generieren Sie die Upload-URL.

2. Zerlegen Sie das Video in kleinere Teile.

3. Hochladen der einzelnen Chunks, wobei alle fehlgeschlagenen Chunks erneut versucht werden.

4. Wenn alle Teile hochgeladen wurden, ist das Video vollständig.

Tipps zur Optimierung

• Verwenden Sie eine große Anzahl kleiner Chunks. Dies erhöht die Wahrscheinlichkeit, dass der Upload erfolgreich ist, selbst wenn einige der Chunks fehlschlagen.

• Implementieren Sie Retry-Handling mit einer Backoff-Strategie. Das bedeutet, dass Sie zwischen den einzelnen Wiederholungsversuchen eine immer längere Zeitspanne abwarten sollten. Dadurch wird verhindert, dass die API mit zu vielen Anfragen überlastet wird.

• Begrenzen Sie die Anzahl der Wiederholungsversuche für jeden Chunk. So verhindern Sie, dass Sie in einer Endlosschleife stecken bleiben, wenn der Chunk nicht hochgeladen werden kann.

Beispiel eines Chunked-Upload-Request

curl -X POST -H "Mi24-Upload-Total-Chunks: 10" -H "Mi24-Upload-Current-Chunk: 1" -H "Content-Type:application/octet-stream" --data-binary "@/<FILENAME>" "<UPLOAD_URL>"

Response codes

• 201 CREATED: Der Chunk wurde erfolgreich hochgeladen.

• 200 OK: Der Chunk wurde bereits hochgeladen.

• 4XX ERROR: Die Anfrage ist aufgrund eines clientseitigen Fehlers fehlgeschlagen.

• 5XX ERROR: Die Anforderung ist aufgrund eines serverseitigen Fehlers fehlgeschlagen.

Wenn der Antwortcode nicht 201 CREATED ist, wird der Chunk erneut versucht. Die Strategie zur Behandlung von Wiederholungsversuchen ist Ihnen überlassen, aber es ist wichtig, zwischen jedem Wiederholungsversuch eine zunehmend längere Zeit zu warten, um eine Überlastung der API zu vermeiden.

Retry handling

Wenn die Antwort auf eine Chunk-Upload-Anforderung nicht 201 CREATED lautet, muss der Chunk erneut versucht werden. Dies kann aus verschiedenen Gründen geschehen, wie zum Beispiel:

• Fehler in der Internetverbindung

• Abgelaufenes Upload-Token

• Ratenbegrenzung

• Zeitüberschreitung beim Empfang einer Antwort von der API

Um zu vermeiden, dass diese Situationen Ihren Upload unterbrechen, sollten Sie in Ihrem Code Retry-Handling implementieren. Dies bedeutet, dass Sie:

1. Identifizieren Sie die Bedingungen, die zum Scheitern eines Chunks führen würden. Zum Beispiel könnten Sie es erneut versuchen, wenn der Antwortcode nicht 201 CREATED lautet.

2. Implementieren Sie eine Backoff-Strategie. Das bedeutet, dass Sie zwischen den einzelnen Wiederholungsversuchen eine inkrementell längere oder zufällige Zeitspanne abwarten sollten. Dadurch wird verhindert, dass Sie die API mit zu vielen Anfragen überlasten.

3. Legen Sie eine Obergrenze für die Anzahl der Wiederholungsversuche fest. So können Sie verhindern, dass Sie in einer Endlosschleife stecken bleiben, wenn der Chunk nicht hochgeladen werden kann.

Hier sind einige Beispiele für Backoff-Strategien:

• Fester Backoff: Warten Sie eine feste Zeitspanne zwischen den einzelnen Wiederholungsversuchen ab, z. B. 1 Sekunde.

• Exponentieller Backoff: Es wird eine exponentiell längere Zeitspanne zwischen den einzelnen Wiederholungsversuchen abgewartet, z. B. 1, 2, 4, 8, 16, ... Sekunden.

• Randomisiertes Backoff: Warten auf eine zufällige Zeitspanne zwischen jedem Wiederholungsversuch, z. B. zwischen 1 und 5 Sekunden.

Die beste Backoff-Strategie für Ihre spezifischen Anforderungen hängt von der Häufigkeit der Fehler und der Zeit ab, die Sie bereit sind, auf den Abschluss des Uploads zu warten.

Java 11 Chunk Upload Beispiel

package mi.uploader;
 
import java.io.*;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
 
public class App {
 
    public static Integer CHUNK_SIZE = 2_097_152;
    public static Integer MAX_RETRIES = 10;
 
    public static HttpClient client = HttpClient.newBuilder()
            .version(HttpClient.Version.HTTP_1_1)
            .followRedirects(HttpClient.Redirect.NORMAL)
            .connectTimeout(Duration.ofSeconds(20))
            .build();
 
    public static void main(String[] args) throws IOException, InterruptedException {
 
        /*
         Step 1. https://doc.movingimage.com/display/LT/Creating+a+Video+Entity
         Step 2. https://doc.movingimage.com/display/LT/Getting+the+Upload+URL
         Step 3. Upload
         */
 
        URI url = URI.create("{URL obtained via API}");
        File f = new File("sample_600s_25fps_1080.mp4");
        InputStream inputStream = new FileInputStream(f);
 
        long totalChunks = calculateChunks(f.length());
 
 
        for (int i = 1; i <= totalChunks; i++) {
 
            byte[] data = new byte[CHUNK_SIZE];
 
            inputStream.read(data);
 
            int statusCode = 0;
            int retryAttempts = 0;
            do {
                if (statusCode >= 500) {
                    Thread.sleep(2000);
                }
 
                if (retryAttempts++ >= MAX_RETRIES) {
                    throw new RuntimeException("Upload failed. Please try again later.");
                }
 
                HttpRequest request = HttpRequest.newBuilder()
                        .POST(HttpRequest.BodyPublishers.ofByteArray(data))
                        .uri(url)
                        .setHeader("Mi24-Upload-Total-Chunks", String.valueOf(totalChunks)) // add request header
                        .setHeader("Mi24-Upload-Current-Chunk", String.valueOf(i)) // add request header
                        .build();
 
                HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
 
                statusCode = response.statusCode();
 
                System.out.println("Status: "+statusCode);
 
            } while (statusCode >= 500);
 
        }
 
        System.out.println("Done");
 
    }
 
    public static long calculateChunks(long fileSize) {
 
        long remainder = fileSize % CHUNK_SIZE;
        int totalChunks = Math.toIntExact(fileSize / CHUNK_SIZE);
 
        if (remainder > 0) {
            totalChunks = totalChunks + 1;
        }
 
        return totalChunks;
    }
}