Quelldatei-Upload-API für dynamische Aufnahme

Einleitung

Für die Aufnahme per Quelldatei-Upload stellt Brightcove einen S3-Bucket bereit, in den Sie Ihre Videos und Asset-Dateien hochladen können, und Dynamic Ingest ruft dann das Video aus dem S3-Bucket auf die gleiche Weise wie aus Ihrem eigenen S3-Bucket oder Ihrer eigenen URL ab. Das folgende Diagramm zeigt den Unterschied zwischen den Workflows für die einfache dynamische Aufnahme und die Aufnahme mit Quelldatei-Upload.

FAQ

Wie lange werden Videos vorübergehend gespeichert und wann werden die URLs dafür ungültig?: Videos werden 24 Stunden nach dem Hochladen aus dem temporären Speicher entfernt und die URLs für sie sind danach nicht mehr gültig.
Wie lange werden die S3-Anmeldeinformationen von der zurückgegeben? Dynamic Ingest API gültig?: Die S3-Anmeldeinformationen sind auch nach dem Senden durch die API 24 Stunden lang gültig.
Werden Videodateien nach 24 Stunden physisch aus dem S3-Bucket gelöscht?: Ja
Werden Videos nach erfolgreicher Aufnahme aus dem S3-Bucket gelöscht?: Alle Videos werden nach 24 Stunden aus dem temporären Speicher gelöscht, unabhängig davon, ob sie erfolgreich aufgenommen wurden oder nicht.
Können die Videos im Zwischenspeicher von jemandem, der die URL hat, öffentlich zugänglich gemacht werden?: Nein
Gibt es eine Möglichkeit, das Video ohne Sicherheitsanmeldeinformationen im temporären Speicher herunterzuladen oder anzuzeigen?: Nein
Werden die Sicherheitsanmeldeinformationen für den Zugriff auf den temporären Speicher mit anderen Brightcove-Kunden geteilt?: Nein, jeder Kunde, der den temporären Speicher verwendet, erhält eindeutige Sicherheitsanmeldeinformationen.
Können andere Brightcove-Kunden mit ihren eigenen Sicherheitsanmeldeinformationen auf meine Videos im temporären Speicher zugreifen?: Nein, Sicherheitsanmeldeinformationen bieten nur Zugriff auf die Videos, die Sie in den temporären Speicher verschoben haben.
In welcher Region befindet sich der S3-Bucket für Datei-Uploads?: US-EAST-1 (dies ist behoben).

Quelldateinamen

Um Probleme beim Zugriff auf Videos und Assets im Brightcove Player zu vermeiden, sollten Sie keine Sonderzeichen in Quelldateinamen verwenden, sei es in Videos, Bildern oder Textspuren (WebVTT-Dateien). Dies gilt auch für Remote-Assets. Dateinamen sollten nur Folgendes enthalten:

Einzelbyte Buchstaben (Groß- oder Kleinschreibung)
Zahlen
Bindestriche (-) und Unterstriche (_)
Räume wenn sie URL-kodiert sind

Authentifizierung

Der einfachste Weg, um Client-Anmeldeinformationen für Dynamic Ingest zu erhalten, ist über die Studio-Admin-Seite für die API-Authentifizierung. Für die API-Berechtigungen benötigen Sie mindestens:

CMS > Video lesen
Dynamische Aufnahme > Erstellen
Dynamische Aufnahme > Push-Dateien (das ist die neue API zum Hochladen von Quelldateien)

Die Authentifizierung für Brightcove-API-Anforderungen für die pushbasierte Aufnahme erfordert eine zusätzliche Berechtigung gegenüber denen für andere dynamische Ingest-Anfragen:

      video-cloud/upload-urls/read

Der vollständige Satz von Berechtigungen, die für das Hochladen von Quelldateien erforderlich sind, ist:

video-cloud/video/erstellen
Video-Cloud/Video/Lesen
Video-Cloud/Video/Update
video-cloud/URLs hochladen/lesen

Diese Berechtigungen sind verfügbar in Studio. Alternativ können Sie Client-Anmeldeinformationen zur Verwendung der Quelldatei-Upload-API direkt von der OAuth-API abrufen, indem Sie wie folgt eine POST-Anfrage stellen:

Anfrage-URL

      https://oauth.brightcove.com/v4/client_credentials

Header

Authorization: BC_TOKEN {YOUR_BC_TOKEN}
Inhaltstyp: application/json

Anfragetext

{
  "type": "credential",
  "maximum_scope": [
  {
    "identity": {
      "type": "video-cloud-account",
      "account-id": {YOUR_ACCOUNT_ID}
    },
    "operations": [
      "video-cloud/upload-urls/read",
      "video-cloud/video/create",
      "video-cloud/video/read",
      "video-cloud/video/update",
      "video-cloud/ingest-profiles/profile/write",
      "video-cloud/ingest-profiles/account/write",
      "video-cloud/ingest-profiles/profile/read",
      "video-cloud/ingest-profiles/account/read"
    ]
  }
  ],
  "name": "Source File Upload Credentials"
}

API-Anfragen

An der pushbasierten Aufnahme sind vier API-Anfragen beteiligt:

CMS-API-POST-Anfrage zum Erstellen des Videoobjekts in Video Cloud (wie bei der Pull-basierten Aufnahme)
Dynamic Ingest GET-Anfrage zum Abrufen der Brightcove S3-Bucket-URLs
PUT-Anfrage zum Hochladen der Quelldatei in den Brightcove S3-Bucket
Dynamic Ingest POST-Anfrage zum Ingest der Quelldatei (wie bei der Pull-basierten Aufnahme)

Diese Anforderungen werden in den folgenden Abschnitten detailliert beschrieben.

CMS-API-Anfrage

Das CMS API Die Anforderung ist dieselbe wie bei jeder Dynamic Ingest-Operation, um ein neues Video hinzuzufügen. Diese Anfrage ist erforderlich, um ein neues Video aufzunehmen. Wenn Sie ein vorhandenes Video ersetzen oder Assets hinzufügen, ist dieser Schritt nicht erforderlich. Stattdessen verwenden Sie die vorhandene Video-ID in den anderen Anfragen.

Anfragesyntax

Das ist ein POST Anfrage zu:

      https://cms.api.brightcove.com/v1/accounts/{ACCOUNT_ID}/videos

Parameter

URL-Parameter für die Anfrage:

{ACCOUNT_ID}- Ihre Konto-ID

Anfragetext

Der Anfragetext besteht aus einem JSON-Objekt, das die name (erforderlich) und andere Metadaten für das Video (optional):

{
  "name": "My Video"
}

Siehe die API-Referenz für Details.

Header

Die HTTP-Header, die Sie in die Anfrage einschließen müssen, sind:

Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

Antwort

Die Antwort ist ein JSON-Objekt, das die Videometadaten enthält. Das wichtige Element für den Rest der dynamischen Ingest-Operationen ist das id, das Sie {VIDEO_ID} in den Anfragen an die Ingest-API ersetzen.

Anfrage für S3-URLs

Die erste Anfrage an die Ingest-API ruft die Informationen ab, die Sie benötigen, um Ihre Quelldatei(en) in den Brightcove S3-Bucket zu PUTIEREN und dann von dort in Video Cloud aufzunehmen.

Anfragesyntax

Das ist ein GET Anfrage zu:

https://ingest.api.brightcove.com/v1/accounts/{ACCOUNT_ID}/videos/{VIDEO_ID}/upload-urls/{SOURCE_NAME}

Parameter

URL-Parameter für die Anfrage:

{ACCOUNT_ID}- Ihre Konto-ID
{VIDEO_ID}- Die Video-ID wurde von zurückgegeben CMS API Anfrage
{SOURCE_NAME}- der Dateiname der Videoquelle — der Name sollte keine URL-reservierten Zeichen wie ? &, # oder Leerzeichen enthalten

Header

Die HTTP-Header, die Sie in die Anfrage einschließen müssen, sind:

Authorization: Bearer {ACCESS_TOKEN}

Antwort

Die Antwort ist ein JSON-Objekt ähnlich dem folgenden:

{
  "bucket": "ingestion-upload-production",
  "object_key": "57838016001/4752143002001/ed5a5ba0-1d97-4f95-a8ec-cbb786b04a37/greatblueheron.mp4",
  "access_key_id": "ACCESS_KEY_APPEARS_HERE",
  "secret_access_key": "SECRET_ACCESS_KEY_APPEARS_HERE",
  "session_token": "FQoDYXdzEKf//////////wEaDKR0wDgquq/qvkZgbyKOA7URC/9io6cmRBDkhbvxoHIKkPZlK/9YNvdWcESPkm75/2PvU6FV1Mc+/XENPzY8KgvP86MBJNxYLPdkuP1phgHs2Yh2p1KIDcQSCZJ3i6i9m4S14ewjWIugYLYDQi6CG+3fiFwfzbKT5jes1kh24m9BQQIuvVOiM1GLTldyDzlrdDopJkdYd4IEU7FU36CUT7RL/aeMwR2Usk56nwqyqkkQHPmvqmGyiLdrD3OrIbUU+6+ZP4usS9dbV3eAqOWDIk3HCN+Kuc9f/eUWhY21ftNDXWgasqQqXwPRs3T1i/hoiIKODbzr8F",
  "signed_url": "https://ingestion-upload-production.s3.amazonaws.com/57838016001/4752143002001/ed5a5ba0-1d97-4f95-a8ec-cbb786b04a37/greatblueheron.mp4?AWSAccessKeyId=ACCESS_KEY_HERE&Expires=1475673952&Signature=%2Fsr5cV%2FVOfGCBkodol9xQIKlbu4%3D",
  "api_request_url": "https://ingestion-upload-production.s3.amazonaws.com/57838016001/4752143002001/ed5a5ba0-1d97-4f95-a8ec-cbb786b04a37/greatblueheron.mp4"
}

Die Punkte in der Antwort sind:

bucket- der S3-Bucket-Name
object_key- der Objektschlüssel für den Datei-Upload (wird beim Aufbau der Ziel-URL für mehrteilige Uploads verwendet)
access_key_id- den Zugangsschlüssel, der zur Authentifizierung der Upload-Anfrage verwendet wird (wird für mehrteilige Uploads verwendet)
secret_access_key- der geheime Zugriffsschlüssel, der zur Authentifizierung der Upload-Anfrage verwendet wird (wird für mehrteilige Uploads verwendet)
session_token- ein kurzlebiges AWS-Token, das die Möglichkeit bietet, in das Zielobjekt zu schreiben
signed_url- dies ist eine kurze S3-URL, in die Sie Ihre Quelldatei (en) einfügen können, wenn Sie relativ kleine Videos haben und keinen mehrteiligen Upload implementieren
api_request_url- Dies ist die URL, die Sie in Ihre Dynamic Ingest POST-Anfrage für die Master-URL oder URL für die Assets image/text_tracks aufnehmen

Es wird empfohlen, den mehrteiligen Upload mit dem AWS SDK für die von Ihnen verwendete Sprache zu verwenden. SDKs sind für viele Sprachen verfügbar, darunter Java, .NET, Ruby, PHP, Python, JavaScript, Go und C++. Siehe die AWS-Entwicklerblog für mehr Informationen.

Wenn Sie einen mehrteiligen Upload implementieren, sind die folgenden Dokumente und der Beispielcode hilfreich:

Hier ist ein einfaches Beispiel in PHP:

<? php
  // AWS SDK (für Push-Ingests)
  erfordern 'vendor / aws-autoloader.php';
  
  benutze Aws \\ S3 \\ S3Client;
  verwende Aws\ S3\ MultipartUploader;
  verwende Aws\ Exception\ MultipartUploadException;
  
  /**
    * Erhalten Sie S3-Informationen wie oben in diesem Dokument beschrieben
    * Der folgende Code setzt voraus, dass er als $ s3response dekodiert wurde
    * und dass $ filePath der lokale Pfad zur Asset-Datei ist
    * /
  
  s3 = neuer S3Client ([
      'version' => 'neueste',
      'region' => 'us-east-1',
      'Anmeldeinformationen' => Array (
          'key' => $ s3response-> access_key_id,
          'secret' => $ s3response-> secret_access_key,
          'Zeichen'	 => $ s3response-> session_token
      )
  ]);
  $ params = array (
      'Bucket' => $ s3response-> s3-> Bucket,
      'key' => $ s3response-> s3-> object_key
  );
  $ uploader = neuer MultipartUploader ($ this-> s3, $ filePath, $ params);
  versuche {
      $ uploadResponse = $ uploader-> upload ();
  } catch (MultipartUploadException $ e) {
      echo $ e-> getMessage (). "\\ n";
  }
? >

PUT-Quelldatei(en) auf S3

Nachdem Sie die S3-URLs erhalten haben, stellen Sie eine PUT-Anfrage, um Ihre Videodatei hochzuladen, wobei Sie die signed_url als Ziel verwenden.

Sie können Folgendes verwenden Locken Befehl zum Testen der PUT-Operation:

      curl -X PUT "SIGNED_URL_GOES_HERE" --upload-file FILE_PATH_FOR_LOCAL_ASSET_GOES_HERE

Wenn Sie Postman verwenden, um die Datei an S3 zu senden, müssen Sie den Content-Type-Header deaktivieren:

Stellen Sie außerdem sicher, dass Sie den Body-Typ auf Binär ändern und Ihre Videodatei zum Hochladen auswählen:

Single- vs. Multipart-Upload

AWS erlaubt einzelne Uploads für Dateien bis zu einer Größe von 5 GB (es gibt keine anderen Beschränkungen der Dateigröße). Bei größeren Dateien müssen Sie mehrteilige Uploads verwenden. Obwohl der Single-Part-Upload etwas einfacher einzurichten ist, empfehlen wir, wann immer möglich, den Multipart-Upload zu verwenden. Hier sind die Unterschiede zwischen den beiden:

Beim Hochladen eines einzelnen Teils wird das Video als eine einzige Datei hochgeladen. Das Hochladen einzelner Teile ist auf Dateigrößen von 5 GB oder weniger beschränkt. Wenn der Upload aus irgendeinem Grund unterbrochen wird, müssen Sie von vorne beginnen.
Beim mehrteiligen Upload wird die Datei in Blöcken übertragen. Dies ist effizienter, da beim Hochladen mehrere Verbindungen genutzt werden können. Wenn der Upload unterbrochen wird, kann er mit den verbleibenden Blöcken dort fortgesetzt werden, wo er aufgehört hat.

Dynamische Aufnahmeanfrage

Nachdem Ihre Datei in den Brightcove S3-Bucket hochgeladen wurde, stellen Sie eine normale dynamische Aufnahmeanforderung, um die Datei von ihrem S3-Speicherort aufzunehmen.

Anfragesyntax

Das ist ein POST Anfrage zu:

      https://ingest.api.brightcove.com/v1/accounts/{ACCOUNT_ID}/videos/{VIDEO_ID}/ingest-requests

Parameter

URL-Parameter für die Anfrage:

{ACCOUNT_ID}- Ihre Konto-ID
{VIDEO_ID}- Die Video-ID wurde von zurückgegeben CMS API Anfrage

Anfragetext

Der Anfragetext besteht aus einem JSON-Objekt, das die master (erforderliche) Details für den Aufnahmejob. Die url für die master wird sein api_request_url von der Anfrage nach den S3-Bucket-Informationen zurückgegeben

      {
      "master": {
          "url": "https://ingestion-upload-prod.s3.amazonaws.com/12345/5678/3712cd37504911ab06a77a26a387ce/source.mp4"
      },
      "profile": "multi-platform-standard-static",
      "capture-images": true
      }

Siehe die API-Referenz für Details.

Header

Die HTTP-Header, die Sie in die Anfrage einschließen müssen, sind:

Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

Antwort

Die Antwort enthält die job_id für die Ingest-Anfrage, mit der Sie den Status verfolgen können über Benachrichtigungen.

Beispielcode

Um Ihnen den Einstieg in die Push-basierte dynamische Aufnahme zu erleichtern, haben wir einige Beispiel-Apps in Java und Python erstellt. Sie finden sie auf unserem Github-Site.