API de téléchargement de fichier source pour l'ingest dynamique

Introduction

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

FAQ

Combien de temps les vidéos sont-elles stockées temporairement et quand les URL pour elles devenent-elles invalides ?: Les vidéos sont supprimées du stockage temporaire après 24 heures après leur téléchargement, et les URL pour elles ne sont plus valides après cela.
Combien de temps les informations d'identification S3 sont-elles renvoyées par le Dynamic Ingest API valide ?: Les informations d'identification S3 sont également valides pendant 24 heures après leur envoi par l'API.
Les fichiers vidéo sont-ils physiquement supprimés du compartiment S3 après 24 heures ?: Oui
Les vidéos sont-elles supprimées du compartiment S3 après leur ingestion ?: Toutes les vidéos sont supprimées du stockage temporaire après 24 heures, qu'elles aient été ingérées avec succès ou non.
Les vidéos en stockage temporaire peuvent-elles être consultées publiquement par quelqu'un qui possède l'URL ?: Non
Existe-t-il un moyen de télécharger ou de visualiser la vidéo dans un stockage temporaire sans informations d'identification de sécurité ?: Non
Les informations d'identification de sécurité permettant d'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 les autres clients de Brightcove d'accéder à mes vidéos dans un stockage temporaire à l'aide de leurs propres identifiants de sécurité ?: Non, les informations d'identification de sécurité fournissent uniquement l'accès aux vidéos que vous avez poussées vers le stockage temporaire.
Quelle région réside le compartiment S3 pour les téléchargements de fichiers ?: US-EAST-1 (ceci est fixe).

Noms des fichiers source

Pour éviter les problèmes d'accès aux vidéos et aux ressources dans Brightcove Player, vous devez éviter d'utiliser des caractères spéciaux dans les noms de fichiers source, qu'il s'agisse de vidéos, d'images ou de pistes de texte (fichiers WebVTT). Cela s'applique également aux actifs distants. Les noms de fichiers ne doivent inclure que les éléments suivants :

Lettresà un octet (majuscules ou minuscules)
Numéros
Trets (-) et traits de soulignement (_)
Espaces s'ils sont encodés par URL

Authentification

Le moyen le plus simple d'obtenir les informations d'identification client pour Dynamic Ingest est via la page Admin Studio pour l'authentification API. Pour les autorisations API, vous devez au moins :

Lecture > vidéo CMS
Ingeste dynamique > Créer
Fichiers > Push Ingest dynamique (il s'agit de la nouvelle API de téléchargement de fichier source)

L'authentification pour les demandes d'API Brightcove pour l'ingestion basée sur le push nécessite une autorisation supplémentaire par rapport à celles pour d'autres requêtes Dynamic Ingest:

      video-cloud/upload-urls/read

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

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

Ces autorisations sont disponibles dans Studio. Vous pouvez également obtenir des informations d'identification client pour utiliser l'API de téléchargement de fichier source directement à partir de l'API OAuth en effectuant une requête POST comme suit :

URL de demande

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

En-têtes

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

Corps de la requête

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

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

Demande POST de l'API CMS pour créer l'objet vidéo dans Video Cloud (même que pour l'ingestion basée sur l'extraction)
Demande GET d'ingest dynamique pour obtenir les URL du compartiment Brightcove S3
Demande PUT pour télécharger le fichier source dans le compartiment Brightcove S3
Requête POST d'ingestion dynamique pour ingérer le fichier source (même que pour l'ingestion basée sur l'extraction)

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

Demande d'API CMS

La CMS API demande est la même que pour toute opération Dynamic Inquest pour ajouter une nouvelle vidéo. Cette demande est requise pour ingérer une nouvelle vidéo. Si vous remplacez ou ajoutez des ressources à une vidéo existante, vous n'aurez pas besoin de cette étape - à la place, vous utiliserez l'identifiant vidéo existant dans les autres requêtes.

Syntaxe de requête

Il s'agit d'une POST demande pour :

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

Paramètres

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

{ACCOUNT_ID} - votre identifiant de compte

Corps de la requête

Le corps de la requête se compose d'un objet JSON contenant les métadonnées name (obligatoires) et d'autres métadonnées pour la vidéo (facultatif) :

      {
      "name": "My Video"
      }

Consultez la référence de l'API pour plus de détails.

En-têtes

Les en-têtes HTTP que vous devez inclure avec 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 vidéo. L'élément important pour le reste des opérations d'Ingestion dynamique est le id, que vous remplacerez {VIDEO_ID} dans les requêtes à l'API Ingestion.

Demande d'URL S3

La première requête à l'API Inquest récupère les informations dont vous avez besoin pour PLACER vos fichiers source dans le compartiment Brightcove S3, puis l'ingérera dans Video Cloud.

Syntaxe de requête

Il s'agit d'une GET demande pour :

      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} - votre identifiant de compte
{VIDEO_ID} - l'identifiant vidéo retourné à partir de la CMS API requête
{SOURCE_NAME} - le nom de fichier source vidéo - le nom ne doit pas contenir de caractères réservés à l'URL tels que ? , & , # ou espaces

En-têtes

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

Authorization: Bearer {ACCESS_TOKEN}

Réponse

La réponse sera un objet JSON similaire 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 les suivants :

bucket - le nom du compartiment S3
object_key - la clé d'objet pour le téléchargement du fichier (utilisée dans la construction de l'URL de destination pour les téléchargements en plusieurs parties)
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 S3 abrégé que vous pouvez mettre vos fichiers source si vous avez des vidéos relativement petites et n'implémentez pas le téléchargement en plusieurs parties
api_request_url - c'est l'URL que vous inclurez dans votre requête POST Dynamic Inquest pour l'URL principale ou l'URL pour les actifs image/text_tracks

Il est recommandé d'utiliser le téléchargement en plusieurs parties à l'aide du kit SDK AWS pour la langue que vous utilisez. Les kits SDK sont disponibles pour de nombreux langages, y compris Java, .NET, Ruby, PHP, Python, JavaScript, Go et C++. Consultez le blog AWS Developer pour plus d'informations.

Si vous implémentez le téléchargement en plusieurs parties, les documents et exemples de code suivants seront utiles :

Voici un exemple simple en PHP :

      <?php
      //SDK AWS (pour les ingestion push)
      requiert 'vendor/aws-autoloader.php' ;
      
      utiliser Aws \ S3 \ S3Client ;
      utiliser Aws \ S3 \ MultiPartuploader ;
      utiliser Aws \ Exception \ MultiPartuploadException ;
      
      /**
       * obtenir les informations S3 comme décrit ci-dessus dans ce document
       * le code ci-dessous suppose qu'il a été décodé comme $s3response
       * et que $FilePath est le chemin d'accès local au fichier d'actifs
       */
      
      s3 = nouveau S3Client ([
          'version' = > 'dernière',
          'region' = > 'us-est-1',
          'Credentials' = > tableau (
              'key' = > $s3response- > access_key_id,
              'secret' = > $s3response- > secret_access_key,
              'token'	 = > $s3response- > session_token
          )
      ]) ;
      $params = tableau (
          'bucket' = > $s3response- > s3- > compartiment,
          'key' = > $s3response- > s3- > object_key
      ) ;
      $uploader = nouveau MultiPartuploader ($this- > s3, $filePath, $params) ;
      essayez {
          $uploadResponse = $uploader- > upload () ;
      } catch (MultiPartuploadException $e) {
          echo $e- > getMessage (). «  \ n » ;
      }
      ?>

Fichier (s) source (s) PUT vers S3

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

Vous pouvez utiliser la commande curl suivante pour tester l'opération PUT :

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

Chargement en un seul ou en plusieurs parties

AWS autorise les téléchargements en une seule partie pour des fichiers d'une taille maximale de 5 Go (il n'y a pas d'autres limites quant à la taille des fichiers). Pour les fichiers volumineux, vous devez utiliser des téléchargements en plusieurs parties. Bien que le téléchargement en une seule partie soit un peu plus facile à configurer, nous vous recommandons d'utiliser le téléchargement en plusieurs parties chaque fois que possible. Voici les différences entre les deux :

Le téléchargement en une seule partie télécharge la vidéo sous la forme d'un seul fichier. Le téléchargement d'une seule partie 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 à zéro.
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 s'était arrêté avec les morceaux restants.

Demande d'ingestion dynamique

Une fois que votre fichier a été téléchargé dans le compartiment Brightcove S3, vous effectuez une requête ordinaire d'ingest dynamique pour l'ingérer à partir de son emplacement S3.

Syntaxe de requête

Il s'agit d'une POST demande pour :

      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} - votre identifiant de compte
{VIDEO_ID} - l'identifiant vidéo retourné à partir de la CMS API requête

Corps de la requête

Le corps de la requête se compose d'un objet JSON contenant les détails master (obligatoires) pour le travail d'ingest. Le url pour le master sera api_request_url renvoyé par la demande pour les informations du compartiment S3

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

Consultez la référence de l'API pour plus de détails.

En-têtes

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

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

Réponse

La réponse contiendra la requête job_id pour l'ingest, ce qui vous permet de suivre l'état via les notifications.

Exemple de code

Pour vous aider à démarrer avec Dynamic Ingest basé sur push, nous avons créé des exemples d'applications en Java et Python. Vous pouvez les trouver sur notre site Github.

Contenu de la page

API de téléchargement de fichier source pour l'ingest dynamique

Introduction

FAQ

Noms des fichiers source

Authentification

URL de demande

En-têtes

Corps de la requête

Demandes API

Demande d'API CMS

Syntaxe de requête

Paramètres

Corps de la requête

En-têtes

Réponse

Demande d'URL S3

Syntaxe de requête

Paramètres

En-têtes

Réponse

Fichier (s) source (s) PUT vers S3

Chargement en un seul ou en plusieurs parties

Demande d'ingestion dynamique

Syntaxe de requête

Paramètres

Corps de la requête

En-têtes

Réponse

Exemple de code