API de carga de archivos de origen para ingesta dinámica

Introducción

Para la ingesta a través de la carga de archivos fuente, Brightcove proporciona un depósito de S3 al que puede cargar sus vídeos y archivos de activos, y Dynamic Ingest luego extrae el vídeo del bucket de S3 de la misma manera que lo haría desde su propio depósito de S3 o URL. El siguiente diagrama muestra la diferencia entre los flujos de trabajo para la ingesta dinámica básica y la ingesta con la carga del archivo fuente.

Preguntas frecuentes (FAQ)

¿Cuánto tiempo se almacenan temporalmente los vídeos y cuándo se vuelven inválidas las URL de ellos?: Los vídeos se eliminan del almacenamiento temporal después de 24 horas después de su carga, y las URL de ellos ya no son válidas después de eso.
¿Cuánto tiempo son Dynamic Ingest API válidas las credenciales de S3 devueltas por el?: Las credenciales de S3 también son válidas durante 24 horas después de que la API las envíe.
¿Los archivos de vídeo se eliminan físicamente del depósito de S3 después de 24 horas?: Sí
¿Se eliminan los vídeos del depósito de S3 después de haber sido ingeridos correctamente?: Todos los vídeos se eliminan del almacenamiento temporal después de 24 horas, independientemente de que se hayan ingerido correctamente o no.
¿Puede acceder públicamente a los vídeos almacenados temporalmente por alguien que tenga la URL?: No
¿Hay alguna forma de descargar o ver el video en un almacenamiento temporal sin credenciales de seguridad?: No
¿Las credenciales de seguridad para acceder al almacenamiento temporal se comparten con otros clientes de Brightcove?: No, cualquier cliente que utilice el almacenamiento temporal recibe credenciales de seguridad únicas.
¿Hay alguna forma de que otros clientes de Brightcove puedan acceder a mis vídeos en almacenamiento temporal utilizando sus propias credenciales de seguridad?: No, las credenciales de seguridad solo proporcionan acceso a los vídeos que introdujo al almacenamiento temporal.
¿En qué región reside el bucket S3 para cargas de archivos?: US-EAST-1 (esto es fijo).

Nombres de archivo de origen

Para evitar problemas al acceder a vídeos y recursos en Brightcove Player, debe evitar el uso de caracteres especiales en los nombres de archivo de origen, ya sean vídeos, imágenes o pistas de texto (archivos WebVTT). Esto también se aplica a los activos remotos. Los nombres de archivo solo deben incluir lo siguiente:

Letrasde un byte (mayúsculas o minúsculas)
Números
guiones (-) y guiones bajos (_)
Espacios si están codificados en URL

Autenticación

La forma más fácil de obtener credenciales de cliente para la ingesta dinámica es a través de la página Administrador de Studio para Autenticación de API. Para los permisos de API, necesita al menos:

Lectura de > vídeo del CMS
>Creación dinámica de ingesta
Archivos > Push de ingesta dinámica (esta es la nueva API de carga de archivos de origen)

La autenticación para las solicitudes de API de Brightcove para la ingestión basada en push requiere un permiso adicional sobre los de otras solicitudes de ingesta dinámica:

      video-cloud/upload-urls/read

El conjunto completo de permisos necesarios para la carga del archivo fuente es:

nube de vídeo/vídeo/crear
nube de vídeo/vídeo/lectura
video-nube/vídeo/actualización
nube de vídeo/subir URLs/leer

Estos permisos están disponibles en Studio. Alternativamente, puede obtener credenciales de cliente para utilizar la API de carga del archivo fuente directamente desde la API de OAuth realizando una solicitud POST de la siguiente manera:

URL de solicitud

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

Encabezados

Authorization: BC_TOKEN {YOUR_BC_TOKEN}
Tipo de contenido: aplicación/json

Cuerpo de solicitud

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

Solicitudes de API

Hay cuatro solicitudes API involucradas en la ingestión basada en push:

Solicitud POST de API de CMS para crear el objeto de vídeo en Video Cloud (igual que para la ingestión basada en extracción)
Solicitud GET de ingesta dinámica para obtener las URL del depósito de Brightcove S3
Solicitud PUT para cargar el archivo fuente en el depósito de Brightcove S3
Solicitud POST de ingesta dinámica para ingerir el archivo fuente (igual que para la ingestión basada en extracción)

Estas solicitudes se detallan en las secciones siguientes.

Solicitud de API de CMS

La CMS API solicitud es la misma que para cualquier operación de ingesta dinámica para agregar un nuevo vídeo. Esta solicitud es necesaria para ingerir un nuevo video. Si está reemplazando o agregando activos a un vídeo existente, no necesitará este paso; en su lugar, utilizará el identificador de vídeo existente en las otras solicitudes.

Sintaxis de solicitud

Esta es una solicitud para:POST

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

Parámetros

Parámetros de URL para la solicitud:

{ACCOUNT_ID} - su ID de cuenta

Cuerpo de solicitud

El cuerpo de la solicitud consta de un objeto JSON que contiene el name (obligatorio) y otros metadatos para el vídeo (opcional):

      {
      "name": "My Video"
      }

Consulte la Referencia de API para obtener más detalles.

Encabezados

Los encabezados HTTP que debe incluir con la solicitud son:

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

Respuesta

La respuesta será un objeto JSON que contenga los metadatos de vídeo. El elemento importante para el resto de las operaciones de ingesta dinámica es el id, que sustituirá por el {VIDEO_ID} en las solicitudes a la API de ingesta.

Solicitud de URL de S3

La primera solicitud a la API de Ingest recuperará la información que necesita para COLOCAR los archivos de origen en el depósito de Brightcove S3 y luego ingerir desde allí en Video Cloud.

Sintaxis de solicitud

Esta es una solicitud para:GET

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

Parámetros

Parámetros de URL para la solicitud:

{ACCOUNT_ID} - su ID de cuenta
{VIDEO_ID} - el id de vídeo devuelto de la CMS API solicitud
{SOURCE_NAME}- el nombre de archivo de la fuente de video - el nombre no debe contener caracteres reservados para la URL, como ? , & , # o espacios

Encabezados

Los encabezados HTTP que debe incluir con la solicitud son:

Authorization: Bearer {ACCESS_TOKEN}

Respuesta

La respuesta será un objeto JSON similar al siguiente:

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

Los elementos de la respuesta son:

bucket - el nombre del cubo S3
object_key - la clave de objeto para la carga del archivo (utilizada en la construcción de la URL de destino para cargas multiparte)
access_key_id - la clave de acceso utilizada para autenticar la solicitud de carga (utilizada para cargas multiparte)
secret_access_key - la clave de acceso secreta utilizada para autenticar la solicitud de carga (utilizada para cargas multiparte)
session_token : un token de AWS de corta duración que proporciona la capacidad de escribir en el objeto de destino
signed_url - esta es una URL de S3 abreviada a la que puede PONER su archivo (s) fuente (s) si tiene videos relativamente pequeños y no está implementando la carga multiparte
api_request_url - esta es la URL que incluirá en su solicitud POST de ingesta dinámica para la URL maestra o url para los activos image/text_tracks

Se recomienda utilizar la carga multiparte con AWS SDK para el idioma que esté utilizando. Los SDK están disponibles para muchos idiomas, incluyendo Java, .NET, Ruby, PHP, Python, JavaScript, Go y C++. Consulte el blog para desarrolladores de AWS para obtener más información.

Si está implementando la carga multiparte, los siguientes documentos y código de ejemplo serán útiles:

Aquí hay un ejemplo simple en PHP:

      <?PHP
      //AWS SDK (para ingestas de inserción)
      requerir 'vendor/aws-autoloader.php';
      
      usar Aws\ S3\ S3Client;
      usar Aws\ S3\ MultiPartuploader;
      usar Aws\ Exception\ MultiPartuploadeXception;
      
      /**
       * obtener información de S3 como se describe anteriormente en este documento
       * el siguiente código asume que ha sido decodificado como $ s3response
       * y que $FilePath es la ruta local al archivo de activos
       */
      
      s3 = nuevo S3Client ([
          'versión' = > 'latest',
          'región' = > 'us-este-1',
          'credencials' = > array (
              'clave' = > $s3response- > access_key_id,
              'secreto' = > $s3response- > secret_access_key,
              'token'	 = > $s3response- > session_token
          )
      ]);
      $params = array (
          'cubo '= > $s3response- > s3- > cubo,
          'clave' = > $s3response- > s3- > object_key
      );
      $uploader = nuevo MultiPartuploader ($this- > s3, $filePath, $params);
      probar {
          $uploadResponse = $uploader- > upload ();
      } captura (MultiPartuploadeXception $e) {
          echo $e- > getMessage (). «\ n»;
      }
      ?>

Archivo (s) fuente (s) PUT (s) a S3

Después de obtener las URL de S3, realiza una solicitud PUT para cargar el archivo de vídeo, utilizando signed_url como destino.

Puede utilizar el siguiente comando curl para probar la operación PUT:

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

Carga única frente a varias partes

AWS permite cargas de una sola parte para archivos de hasta 5 GB de tamaño (no hay otros límites en cuanto al tamaño de archivo). En el caso de archivos más grandes, debe utilizar cargas multiparte. Aunque la carga de una sola parte es algo más fácil de configurar, recomendamos utilizar la carga multiparte siempre que sea posible. Aquí están las diferencias entre los dos:

La carga de una sola parte carga el vídeo todo como un solo archivo. La carga de una sola pieza está limitada a tamaños de archivo de 5 GB o menos. Si la carga se interrumpe por algún motivo, debe comenzar de nuevo.
La carga multiparte empuja el archivo en fragmentos. Esto es más eficiente porque la carga puede aprovechar múltiples conexiones. Además, si la carga se interrumpe, puede reanudarse donde lo dejó con los trozos restantes.

Solicitud de ingesta dinámica

Una vez que el archivo se haya cargado en el depósito de Brightcove S3, debe realizar una solicitud ordinaria de ingesta dinámica para ingerir el archivo desde su ubicación S3.

Sintaxis de solicitud

Esta es una solicitud para:POST

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

Parámetros

Parámetros de URL para la solicitud:

{ACCOUNT_ID} - su ID de cuenta
{VIDEO_ID} - el id de vídeo devuelto de la CMS API solicitud

Cuerpo de solicitud

El cuerpo de la solicitud consta de un objeto JSON que contiene los detalles master (necesarios) para el trabajo de ingesta. El url para el master será el api_request_url devuelto por la solicitud de la información del depósito de S3

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

Consulte la Referencia de API para obtener más detalles.

Encabezados

Los encabezados HTTP que debe incluir con la solicitud son:

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

Respuesta

La respuesta contendrá el job_id para la solicitud de ingesta, lo que le permite realizar un seguimiento del estado a través de Notificaciones.

Código de muestra

Para ayudarle a comenzar con la ingesta dinámica basada en push, hemos creado algunas aplicaciones de ejemplo en Java y Python. Puede encontrarlos en nuestro sitio de Github.

Contenido de la página

API de carga de archivos de origen para ingesta dinámica

Introducción

Preguntas frecuentes (FAQ)

Nombres de archivo de origen

Autenticación

URL de solicitud

Encabezados

Cuerpo de solicitud

Solicitudes de API

Solicitud de API de CMS

Sintaxis de solicitud

Parámetros

Cuerpo de solicitud

Encabezados

Respuesta

Solicitud de URL de S3

Sintaxis de solicitud

Parámetros

Encabezados

Respuesta

Archivo (s) fuente (s) PUT (s) a S3

Carga única frente a varias partes

Solicitud de ingesta dinámica

Sintaxis de solicitud

Parámetros

Cuerpo de solicitud

Encabezados

Respuesta

Código de muestra