API de téléchargement de fichiers source pour l'ingestion dynamique

Introduction

Pour l'ingestion via le téléchargement du fichier source, Brightcove fournit un compartiment S3 dans lequel vous pouvez télécharger vos vidéos et fichiers de ressources, et Dynamic Ingest extrait ensuite la vidéo du compartiment S3 de la même manière que dans votre propre compartiment ou URL S3. Le diagramme ci-dessous montre la différence entre les flux de travail pour l'acquisition dynamique de base et l'ingestion avec le téléchargement du fichier source.

QFP

Combien de temps les vidéos sont-elles stockées temporairement et à quel moment les URL pour elles deviennent-elles invalides?: Les vidéos sont supprimées du stockage temporaire après 24 heures après leur téléchargement et leurs URL ne sont plus valides par la suite.
Combien de temps les informations d’authentification S3 sont-elles renvoyées par le Dynamic Ingest API valide?: Les informations d'identification S3 sont également valables pour les heures 24 après leur envoi par l'API.
Les fichiers vidéo sont-ils physiquement supprimés du compartiment S3 après les heures 24?: Oui
Les vidéos sont-elles supprimées du compartiment S3 après leur intégration réussie?: Toutes les vidéos sont supprimées du stockage temporaire après les heures 24, qu'elles aient été ingérées avec succès ou non.
Les vidéos stockées temporairement peuvent-elles être consultées publiquement par une personne disposant de l'URL?: Non
Est-il possible de télécharger ou d'afficher la vidéo dans un stockage temporaire sans informations d'identification de sécurité?: Non
Les informations d'identification de sécurité pour accéder au stockage temporaire sont-elles partagées avec d'autres clients Brightcove?: Non, tout client utilisant le stockage temporaire reçoit des informations d'identification de sécurité uniques.
Existe-t-il un moyen pour d'autres clients Brightcove d'accéder à mes vidéos dans un stockage temporaire en utilisant leurs propres informations d'identification de sécurité?: Non, les informations d'identification de sécurité fournissent uniquement l'accès aux vidéos que vous avez transférées vers le stockage temporaire.
Dans quelle région le compartiment S3 pour les téléchargements de fichiers réside-t-il?: US-EAST-1 (ceci est corrigé).

Noms de fichiers sources

Pour éviter les problèmes d’accès aux vidéos et aux éléments dans le Brightcove Player, évitez d’utiliser des caractères spéciaux dans les noms de fichier source, que ce soit des vidéos, des images ou des pistes de texte (fichiers WebVTT). Ceci s'applique également aux actifs distants. Les noms de fichiers doivent uniquement inclure les éléments suivants:

Un octet lettres (majuscules ou minuscules)
Nombres
Tirets (-) et traits de soulignement (_)
Les espaces s'ils sont codés en URL

Authentification

La façon la plus simple d'obtenir les informations d'identification du client pour Dynamic Ingest est de la page d'administration de Studio pour l'authentification de l'API. Pour les autorisations d'API, vous devez au moins:

CMS> Lecture de vidéos
Dynamic Ingest> Créer
Dynamic Ingest> Push Files (il s'agit de la nouvelle API de téléchargement de fichiers source)

L'authentification pour les demandes d'API Brightcove pour l'ingestion basée sur la transmission nécessite une autorisation supplémentaire par rapport à celles pour autres demandes d'acquisition dynamique:

      video-cloud/upload-urls/read

L'ensemble complet des autorisations nécessaires pour le téléchargement du fichier source est:

vidéo-nuage / vidéo / créer
vidéo-nuage / vidéo / lecture
video-cloud / vidéo / mise à jour
video-cloud / upload-urls / lire

Ces autorisations sont disponibles dans Studio. Sinon, vous pouvez obtenir les informations d'identification du client pour utiliser l'API de téléchargement du fichier source directement à partir du OAuth API en faisant une demande POST comme suit:

Demander une URL

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

En-têtes

Authorization: BC_TOKEN {YOUR_BC_TOKEN}
Type de contenu: application / json

Demander un corps

      {
      "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"
      }

Demandes d'API

Il y a quatre demandes d'API impliquées dans l'ingestion basée sur le push:

CMS API Requête POST pour créer l'objet vidéo dans Video Cloud (idem que pour l'ingestion basée sur la traction)
Demande Dynamic Ingest GET pour obtenir les URL de compartiment Brightcove S3
Demande PUT pour télécharger le fichier source dans le compartiment Brightcove S3
Demande POST d'ingestion dynamique pour l'ingestion du fichier source (identique à l'ingestion par extraction)

Ces demandes sont détaillées dans les sections qui suivent.

CMS API nécessaire

Le système CMS API La demande est la même que pour toute opération d'acquisition dynamique consistant à ajouter une nouvelle vidéo. Cette demande est requise pour intégrer une nouvelle vidéo. Si vous remplacez ou ajoutez des éléments à une vidéo existante, vous n'aurez pas besoin de cette étape. Vous utiliserez plutôt l'ID de la vidéo existante dans les autres demandes.

Demande de syntaxe

C'est une POST demande à:

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

Paramètres

Paramètres d'URL pour la requête:

{ACCOUNT_ID} - l'identifiant de votre compte

Demander un corps

Le corps de la requête est constitué d'un objet JSON contenant name (obligatoire) et autres métadonnées pour la vidéo (facultatif):

      {
      "name": "My Video"
      }

Voir le Référence de l'API pour en savoir plus.

En-têtes

Les en-têtes HTTP que vous devez inclure dans la requête sont:

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

Réponse

La réponse sera un objet JSON contenant les métadonnées de la vidéo. L'élément important pour le reste des opérations d'acquisition dynamique est le id, que vous substituerez à la {VIDEO_ID} dans les demandes à l'API Ingest.

Demande d'URL S3

La première demande à l'API Ingest récupérera les informations dont vous avez besoin pour METTRE vos fichiers source dans le compartiment Brightcove S3, puis les ingérer à partir de là dans Video Cloud.

Demande de syntaxe

C'est une GET demande à:

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

Paramètres

Paramètres d'URL pour la requête:

{ACCOUNT_ID} - l'identifiant de votre compte
{VIDEO_ID} - l'identifiant vidéo renvoyé de CMS API nécessaire
{SOURCE_NAME} - le nom de fichier de la source vidéo - le nom ne doit pas contenir de caractères réservés à l'URL tels que ?, &, # ou des espaces

En-têtes

Les en-têtes HTTP que vous devez inclure dans la requête sont:

Authorization: Bearer {ACCESS_TOKEN}

Réponse

La réponse sera un objet JSON semblable au suivant:

      {
      "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"
      }

Les éléments de la réponse sont:

bucket - le nom du compartiment S3
object_key - la clé de l'objet pour le téléchargement du fichier (utilisée dans la construction de l'URL de destination pour les téléchargements multiparties)
access_key_id - la clé d'accès utilisée pour authentifier la demande de téléchargement (utilisée pour les téléchargements en plusieurs parties)
secret_access_key - la clé d'accès secrète utilisée pour authentifier la demande de téléchargement (utilisée pour les téléchargements en plusieurs parties)
session_token - un jeton AWS de courte durée qui permet d'écrire sur l'objet cible
signed_url - il s'agit d'une URL abrégée S3 à laquelle vous pouvez insérer vos fichiers source si vous avez des vidéos relativement petites et que vous n'implémentez pas de téléchargement multipart.
api_request_url - il s'agit de l'URL que vous allez inclure dans votre demande Dynamic Ingest POST pour l'URL principale ou pour les actifs image / text_tracks.

Il est recommandé d'utiliser le téléchargement en plusieurs parties à l'aide du kit de développement logiciel AWS SDK pour la langue utilisée. Les SDK sont disponibles dans de nombreuses langues, notamment Java, .NET, Ruby, PHP, Python, JavaScript, Go et C ++. Voir le AWS Developer Blog pour plus d’informations.

Si vous implémentez le téléchargement partitionné, les documents suivants et l'exemple de code seront utiles:

Voici un exemple simple en PHP:

      <?php
      // AWS SDK (for push ingests)
      require 'vendor/aws-autoloader.php';
      
      use Aws\S3\S3Client;
      use Aws\S3\MultipartUploader;
      use Aws\Exception\MultipartUploadException;
      
      /**
       * get S3 information as described above in this doc
       * the code below assumes it has been decoded as $s3response
       * and that $filePath is the local path to the asset file
       */
      
      s3 = new S3Client([
          'version' => 'latest',
          'region'  => 'us-east-1',
          'credentials' => array(
              'key'    => $s3response->access_key_id,
              'secret' => $s3response->secret_access_key,
              'token'	 => $s3response->session_token
          )
      ]);
      $params = array(
          'bucket' => $s3response->s3->bucket,
          'key' => $s3response->s3->object_key
      );
      $uploader = new MultipartUploader($this->s3, $filePath, $params);
      try {
          $uploadResponse = $uploader->upload();
      } catch (MultipartUploadException $e) {
          echo $e->getMessage() . "\n";
      }
      ?>

PUT fichier (s) source à S3

Après avoir obtenu les URL S3, vous faites une demande PUT pour télécharger votre fichier vidéo, en utilisant le signed_url comme destination.

Vous pouvez utiliser ce qui suit boucle commande pour tester l'opération PUT:

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

Téléchargement unique ou multipart

AWS autorise les téléchargements en une partie de fichiers dont la taille ne dépasse pas 5 Go (il n'y a pas d'autre limite de taille de fichier). Pour les fichiers plus volumineux, vous devez utiliser des téléchargements en plusieurs parties. Bien que le téléchargement en une partie soit un peu plus facile à configurer, nous vous recommandons d’utiliser le téléchargement en plusieurs parties lorsque cela est possible. Voici les différences entre les deux:

Le téléchargement en une seule partie télécharge la vidéo en un seul fichier. Le téléchargement d'une seule pièce est limité aux tailles de fichier de 5 Go ou moins. Si le téléchargement est interrompu pour une raison quelconque, vous devez recommencer.
Le téléchargement en plusieurs parties pousse le fichier en morceaux. Ceci est plus efficace car le téléchargement peut tirer parti de plusieurs connexions. De plus, si le téléchargement est interrompu, il peut reprendre là où il se trouvait avec les morceaux restants.

Demande d'ingestion dynamique

Une fois votre fichier téléchargé dans le compartiment Brightcove S3, vous effectuez une demande Dynamic Ingest ordinaire pour ingérer le fichier à partir de son emplacement S3.

Demande de syntaxe

C'est une POST demande à:

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

Paramètres

Paramètres d'URL pour la requête:

{ACCOUNT_ID} - l'identifiant de votre compte
{VIDEO_ID} - l'identifiant vidéo renvoyé de CMS API nécessaire

Demander un corps

Le corps de la requête est constitué d'un objet JSON contenant master (requis) les détails pour le travail d'ingestion. le url pour le master sera l' api_request_url renvoyé par la demande d'informations sur le compartiment S3

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

Voir le Référence de l'API pour en savoir plus.

En-têtes

Les en-têtes HTTP que vous devez inclure dans la requête sont:

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

Réponse

La réponse contiendra la job_id pour la demande d'acquisition, ce qui vous permet de suivre l'état via Notifications.

Exemple de code

Pour vous aider à vous familiariser avec Dynamic Ingest, nous avons créé quelques exemples d'applications en Java et en Python. Vous pouvez les trouver sur notre Site Github.

Contenu de la page

API de téléchargement de fichiers source pour l'ingestion dynamique

Introduction

QFP

Noms de fichiers sources

Authentification

Demander une URL

En-têtes

Demander un corps

Demandes d'API

CMS API nécessaire

Demande de syntaxe

Paramètres

Demander un corps

En-têtes

Réponse

Demande d'URL S3

Demande de syntaxe

Paramètres

En-têtes

Réponse

PUT fichier (s) source à S3

Téléchargement unique ou multipart

Demande d'ingestion dynamique

Demande de syntaxe

Paramètres

Demander un corps

En-têtes

Réponse

Exemple de code