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

Introducción

Para la ingesta a través de la carga de archivos de origen, Brightcove proporciona un depósito S3 al que puede cargar sus videos y archivos de activos, y Dynamic Ingest luego extrae el video del depósito S3 de la misma manera que lo haría desde su propio depósito 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 de origen.

Preguntas más frecuentes

¿Cuánto tiempo se almacenan temporalmente los videos y cuándo dejan de ser válidas sus URL?: Los videos se eliminan del almacenamiento temporal después de 24 horas después de que se cargan y las URL para ellos ya no son válidas después de eso.
¿Por cuánto tiempo devuelven las credenciales de S3 el Dynamic Ingest API ¿válido?: Las credenciales de S3 también son válidas durante 24 horas después de que la API las envía.
¿Se eliminan físicamente los archivos de video del depósito de S3 después de 24 horas?: Sí
¿Se eliminan los videos del depósito de S3 después de que se hayan ingerido correctamente?: Todos los videos se eliminan del almacenamiento temporal después de 24 horas, ya sea que se hayan ingerido correctamente o no.
¿Alguien que tenga la URL puede acceder públicamente a los videos en el almacenamiento temporal?: No
¿Hay alguna forma de descargar o ver el video en el almacenamiento temporal sin credenciales de seguridad?: No
¿Se comparten las credenciales de seguridad para acceder al almacenamiento temporal 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 videos en el almacenamiento temporal utilizando sus propias credenciales de seguridad?: No, las credenciales de seguridad solo brindan acceso a los videos que envió al almacenamiento temporal.
¿En qué región reside el bucket de S3 para la carga de archivos?: US-EAST-1 (esto es fijo).

Nombres de archivos de origen

Para evitar problemas al acceder a videos y activos en Brightcove Player, debe evitar el uso de caracteres especiales en los nombres de los archivos de origen, ya sean videos, 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:

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

Autenticación

La forma más sencilla de obtener credenciales de cliente para Dynamic Ingest es a través de la página de administración de Studio para la autenticación de API. Para los permisos de la API, necesita al menos:

CMS> Lectura de video
Ingesta dinámica> Crear
Ingesta dinámica> Archivos de inserción (esta es la nueva API de carga de archivos de origen)

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

      video-cloud/upload-urls/read

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

video-nube / video / crear
video-nube / video / lectura
video-nube / video / actualización
video-cloud / upload-urls / read

Estos permisos están disponibles en Estudio. Alternativamente, puede obtener credenciales de cliente para usar la API de carga de archivos de origen directamente desde la API de OAuth haciendo una solicitud POST de la siguiente manera:

Solicitar URL

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

Encabezados

Authorization: BC_TOKEN {YOUR_BC_TOKEN}
Tipo de contenido: application/json

Cuerpo de la 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 de API involucradas en la ingestión basada en push:

Solicitud POST de la API de CMS para crear el objeto de video en Video Cloud (igual que para la ingestión basada en extracción)
Solicitud GET de ingesta dinámica para obtener las URL del bucket de Brightcove S3
Solicitud PUT para cargar el archivo de origen en el depósito Brightcove S3
Solicitud POST de ingesta dinámica para ingerir el archivo de origen (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 La solicitud es la misma que para cualquier operación de Ingesta dinámica para agregar un nuevo video. Esta solicitud es necesaria para ingerir un nuevo video. Si está reemplazando o agregando activos a un video existente, no necesitará este paso; en su lugar, usará la identificación de video existente en las otras solicitudes.

Solicitar sintaxis

Esto es un POST solicitud de:

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

Parámetros

Parámetros de URL para la solicitud:

{ACCOUNT_ID}- su identificación de cuenta

Cuerpo de la solicitud

El cuerpo de la solicitud consta de un objeto JSON que contiene el name (obligatorio) y otros metadatos del video (opcional):

{
  "name": "My Video"
}

Ver el Referencia de API para 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 contiene los metadatos del video. 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 Ingest.

Solicitud de URL de S3

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

Solicitar sintaxis

Esto es un GET solicitud de:

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 identificación de cuenta
{VIDEO_ID}- la identificación de video regresó de CMS API pedido
{SOURCE_NAME}- el nombre del archivo fuente de video - el nombre no debe contener ningún carácter reservado 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 depósito de 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 S3 abreviada en la que puede PONER sus archivos de origen si tiene videos relativamente pequeños y no está implementando la carga de varias partes
api_request_url- esta es la URL que incluirá en su solicitud POST de ingesta dinámica para la URL maestra o la URL para los activos de imagen / pistas de texto

Se recomienda que utilice la carga de varias partes con el AWS SDK para el idioma que está usando. Los SDK están disponibles para muchos lenguajes, incluidos Java, .NET, Ruby, PHP, Python, JavaScript, Go y C++. Ver el Blog para desarrolladores de AWS para más información.

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

Aquí hay un ejemplo simple en PHP:

<? php
  // AWS SDK (para ingestas push)
  requiere 'vendor / aws-autoloader.php';
  
  utilice Aws \\ S3 \\ S3Client;
  utilice AWS\\S3\\MultipartUploader;
  utilice Aws \\ Exception \\ MultipartUploadException;
  
  / **
    * obtener información de S3 como se describe arriba en este documento
    * el código a continuación asume que se ha decodificado como $ s3response
    * y que $ filePath es la ruta local al archivo de activos
    * /
  
  s3 = nuevo S3Cliente([
      'version' => 'más reciente',
      'region' => 'us-east-1',
      'credenciales' => matriz (
          'key' => $ s3response-> access_key_id,
          'secret' => $ s3response-> secret_access_key,
          'simbólico'	 => $ s3response-> session_token
      )
  ]);
  $params = array(
      'bucket' => $ s3response-> s3-> bucket,
      'clave' => $ s3response-> s3-> object_key
  );
  $uploader = new MultipartUploader($this->s3, $filePath, $params);
  intentar {
      $uploadResponse = $uploader->upload();
  } catch (MultipartUploadException $e) {
      echo $ e-> getMessage (). "\\norte";
  }
?>

PONER archivo (s) fuente en S3

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

Puede utilizar lo siguiente rizo comando para probar la operación PUT:

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

Si está utilizando Postman para enviar el archivo a S3, deberá desmarque la Tipo de contenido encabezamiento:

También asegúrese de cambiar el tipo de cuerpo a Binario y seleccione su archivo de video para cargar:

Carga de una o varias partes

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

La carga de una sola parte carga el video como un solo archivo. La carga de una sola parte 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 de varias partes empuja el archivo en trozos. Esto es más eficiente porque la carga puede aprovechar múltiples conexiones. Además, si se interrumpe la carga, se puede reanudar donde se quedó con los fragmentos restantes.

Solicitud de ingesta dinámica

Después de que su archivo se haya cargado en el cubo de Brightcove S3, realiza una solicitud de ingesta dinámica normal para ingerir el archivo desde su ubicación S3.

Solicitar sintaxis

Esto es un POST solicitud de:

      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 identificación de cuenta
{VIDEO_ID}- la identificación de video regresó de CMS API pedido

Cuerpo de la solicitud

El cuerpo de la solicitud consta de un objeto JSON que contiene el master (obligatorio) detalles para el trabajo de ingesta. La url Para el master será el api_request_url devuelto por la solicitud de información del bucket de S3

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

Ver el Referencia de API para 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, que le permite realizar un seguimiento del estado a través de Notificaciones.

Código de muestra

Para ayudarlo a comenzar con Dynamic Ingest basado en push, hemos creado algunas aplicaciones de muestra en Java y Python. Puedes encontrarlos en nuestro Sitio de Github.