Introducción a la Media API

Product
Video Cloud
Aplicable a roles
Desarrollador
Versión
Brightcove 5
Módulos
Media API
Edición
Todas
Creado por Chris Howell.

Este documento contiene un resumen de Media API de Video Cloud.

Media API es una interfaz de programación de aplicaciones (API) basada en REST ("Representational State Transfer") que permite acceder a los contenidos y metadatos de una cuenta de Video Cloud. Al tratarse de una API basada en REST, puede accederse a Media API desde una amplia variedad de puntos de aplicaciones web, no solo desde la aplicación cliente, sino también desde páginas web generadas dinámicamente o, por ejemplo, desde procesos de sincronización del lado del servidor.

Para evitar accesos no autorizados a los metadatos de su cuenta, Video Cloud protege el acceso a la API mediante tokens que usted debe entregar como parámetros al ejecutar llamadas a la API. Al igual que otras APIs basadas en web, Video Cloud genera los tokens por usted, y usted los protege.

Para empezar, lo primero que debe hacer es obtener los tokens para su cuenta. Media API no está disponible para los clientes de Video Cloud Express con planes de suscripción $99 o $199. Los clientes suscritos al plan Video Cloud Express de $499 disponen de tokens aptos para los métodos de lectura de la Media API, mientras que los clientes de las versiones Pro y Enterprise de Video Cloud disponen de la Media API completa.

Esta descripción general le permitirá familiarizarse con Media API y le explicará:

Interioridades de Media API

REST, o Representational State Transfer, es una forma estándar de acceder a los datos almacenados en un sistema remoto a través de HTTP. Está relacionado con SOAP y es una de las tecnologías presentes en los servicios web. Su función principal es abstraer el trabajo del sistema remoto en la transferencia de su estado (o información). Todo lo que su código necesita entender es el formato de los datos que se devuelven.

Media API dispone de métodos de lectura y de escritura.

  • Read API se compone de una serie de métodos que realizan una variedad de solicitudes a nuestros servidores (que están almacenados en caché para mejorar el rendimiento) y devuelven series de datos en DTOs u objetos de transferencia de datos. Por ejemplo, find_all_videos es un método de API que devuelve una lista de VideoDTOs, donde cada VideoDTO contiene los metadatos de un vídeo específico. Los datos devueltos están formateados como cadenas JSON o como XML formateados con MRSS. JSON (JavaScript Object Notation) es una forma ligera de transferir objetos complejos como cadenas y casi todos los lenguajes modernos cuentan con un gran número de bibliotecas accesibles al público para transformar cadenas JSON en objetos nativos. MRSS (Media Really Simple Syndication) es un módulo RSS que se utiliza para la sindicación de archivos multimedia (audio, vídeo e imágenes) en fuentes RSS.
  • Write API se compone de una serie de métodos que crean, actualizan o eliminan vídeos y listas de reproducción. Por ejemplo, create_video es un método de Write API que permite pasar un archivo de vídeo junto con sus metadatos asociados para crear un vídeo en una cuenta de Video Cloud.

Llamadas a métodos Media API

Las llamadas a métodos que utilizan REST son básicamente solicitudes HTTP GET (para métodos de lectura) o solicitudes POST (para métodos de escritura) a una URL particular en servidores de Video Cloud. La solicitud incluye el nombre del método al que está llamando, junto con sus argumentos de entrada, que se pasan en forma de parámetros en la URL. El cuerpo de la respuesta HTTP contiene los resultados de la llamada HTTP como cadena JSON o como XML formateado con MRSS. Todas las llamadas a Media API utilizan la dirección URL base http://api.brightcove.com/services. El acceso a los Servicios de Video Cloud a través de direcciones IP no se admite y debería evitarse en todos los casos. Las direcciones IP de Video Cloud pueden cambiar en cualquier momento sin previo aviso; un cambio puede causar que fallen los sistemas que intenten acceder mediante la dirección IP.

 

Nota importante para los editores japoneses

 

Si usted es un cliente de Brightcove KK, nuestra empresa conjunta japonesa, deberá utilizar otra dirección URL para acceder a la Media API. Todas sus llamadas a la Media API deberán comenzar por http://api.brightcove.co.jp, y no por http://api.brightcove.com.

Las llamadas a métodos también requieren un token. Video Cloud proporciona los tokens para las cuentas y éstos le proporcionan acceso a su cuenta mediante la API. Existen tokens distintos para métodos de lectura y métodos de escritura en la API. Añada su token a la llamada como parámetro de dirección URL, such as token=[tokenString], donde tokenString es su token con codificación URL. Recuerde que los tokens de Media API normalmente acaban en uno o más puntos (.). Asegúrese de incluir los puntos cuando utilice los tokens de la API, ya que es fácil perderlos al copiar y pegar. Los tokens de la API se pueden ver y administrar en la página Información de la cuenta: Configuración de la cuenta: Gestión de la API de Video Cloud Studio, que también ofrece un botón para enviar por correo electrónico un token o copiarlo al portapapeles. Para más información sobre tokens, consulte Administración de tokens de Media API.

Por ejemplo, para recuperar todos los vídeos de su cuenta, haga una solicitud HTTP como ésta:

http://api.brightcove.com/services/library?command=find_all_videos
&token=0Z2dtxTdJAxtbZ-d0U7Bhio2V1Rhr5Iafl5FFtDPY8E.

Esta solicitud funciona, y puede probarla aquí. Verá cómo se imprimen los resultados de la llamada rápidamente. Se trata de una llamada directa al método. El valor devuelto está sin procesar y sin formatear. En los ejemplos, verá maneras de tomar los datos devueltos y darles forma de maneras útiles para una aplicación. (Nota: Esta llamada utiliza una cuenta demo. Para utilizar su propia cuenta, indique su propio token de lectura en el argumento &token).

Nota importante para los editores japoneses

 

Integración de la API en su aplicación

Como las solicitudes de Media API son llamadas HTTP simples, puede incluirlas en cualquier lugar de su aplicación. Cualquier lenguaje popular para la web, tanto para aplicaciones de servidor como de cliente, permite generar solicitudes HTTP. Es lo que se utiliza para incluir llamadas de API en su aplicación. Además, los experimentados desarrolladores de Video Cloud han creado SDKs (kits de desarrollo de software) para la mayoría de lenguajes populares orientados a web que se pueden incluir en las aplicaciones como clases nativas para acceder fácilmente a la API. Consulte SDKs de Video Cloud para ver una lista actualizada de los SDKs disponibles para la Media API. Visite también Open Source @ Brightcove, una iniciativa apoyada por la comunidad, en la que encontrará una amplia variedad de aplicaciones, SDKs y herramientas para la plataforma de Video Cloud en una ubicación central.

Es probable que su solicitud se realice bajo demanda, por ejemplo al cargar una página, cuando un usuario hace clic en un botón o cuando ocurre algún otro evento. Para gestionar esto, deberá incluir la solicitud HTTP en una función y llamarla en respuesta a algún evento programático, como un evento onClick. También deberá gestionar la respuesta y, si no trabaja en JavaScript, transformar la cadena JSON o salida MRSS en objetos nativos para poder trabajar con los datos. Tenga en cuenta que JSON no devuelve los datos de forma fiable en un orden particular; sugerimos utilizar un analizador JSON para encontrar los campos con los que desee trabajar.

Con los métodos de Write API puede crear una aplicación de cliente que integra su cuenta Video Cloud con su sistema de gestión de contenidos. También puede escribir una aplicación de sobremesa que se ejecuta localmente y no requiere un servidor entre el cliente y Video Cloud. Otra arquitectura posible podría ser con un cliente Flash mediante la pila HTTP de Flash. También podría utilizar Adobe AIR, el nuevo cliente de sobremesa de Adobe, para crear una aplicación de carga de sobremesa en base Flash.

Parámetros de la API

Las llamadas básicas de Read API, como find_all_videos, pueden refinarse con parámetros adicionales. La referencia de API enumera el conjunto completo, pero aquí solo se muestra un resumen de las posibilidades:

  • Pagine los resultados de la búsqueda. Puede optar por devolver páginas de datos si espera un número grande de resultados. Puede definir el tamaño de la página y seleccionar que se devuelva una página específica. El tamaño máximo de la página es normalmente 100; si no define el tamaño de la página, los resultados se devolverán en páginas de 100.
  • Seleccione los campos que desea que se devuelvan. En la mayoría de los casos de uso únicamente necesitará campos de datos específicos, como los campos name y shortDescription. Puede hacer que la API devuelva solo estos campos para optimizar el tiempo de la llamada.
  • Orden. Puede especificar que se aplique un orden al resultado, que puede ser alfabéticamente, según la fecha de creación, la fecha de publicación, la fecha de modificación, el recuento de reproducciones de la semana anterior o el total de reproducciones.

Las llamadas de Write API básicas, como create_video, toman parámetros que añaden los metadatos al vídeo que está creando. También existen métodos de Write API para crear, actualizar y eliminar listas de reproducción y para crear puntos de referencia, imágenes y sobreimpresiones de logotipos.

Trabajar con JSON

Al trabajar con cadenas JSON, asegúrese de que utiliza la sintaxis JSON apropiada. Los valores de las cadenas van entre comillas, pero no los números y valores booleanos. Por ejemplo, en lo que sigue, create_video, token y filename son cadenas, mientras que create_multiple_renditions es un booleano:

{"method": "create_video",
"params": {"token" : "riBfgveLvpRb-rHGiBBouSAXs-Q8NmphGxt0z04kE.",
  "video" : {"id":38,"name":"Cookies!","shortDescription":"yumyumyumyum tasty!"},
  "filename":"miamiMoon.mov",
  "create_multiple_renditions" : true}}

Revise la Referencia de Media API para conseguir la firma correcta de todos los métodos que utilice, así como los ejemplos de Media API. Para más información sobre JSON, visite json.org.

Almacenamiento en caché

Para mejorar el rendimiento, las llamadas a API se almacenan en caché en los servidores de Video Cloud. Cada vez que se ejecuta una llamada, Video Cloud comprueba primero la memoria caché. Si la llamada no está almacenada en caché o la memoria caché ha caducado, la llamada pasa directamente a la base de datos y Video Cloud devuelve los resultados y también los almacena en caché. La memoria caché caduca al cabo de 5 minutos. Si realiza llamadas adicionales dentro de esa ventana, los resultados provendrán de la memoria caché y no de la base de datos.

El almacenamiento en caché no refleja los cambios que puedan producirse en su biblioteca mediante Video Cloud Studio o mediante la carga por lotes. Los cambios realizados en su biblioteca que afectarían a una llamada no se reflejarán en los resultados de la llamada hasta que caduque la caché. Tenga esto en cuenta al comprobar su código; la API podría estar funcionando correctamente, incluso en el caso de que no vea los resultados correctos.

Tratamiento de errores

La API intentará encontrar errores comunes, como un video_id que no existe, y tratarlos de una forma adecuada para el código. La mayoría de errores se devuelven como cadenas JSON, con un parámetro de error como éste:

{"error": "an unknown error occurred while processing your request ","código":100}

Si su salida es MRSS, los errores se incluyen en un elemento <error> que incluye un código y mensaje de error.

Siempre que sea posible, su código debería tratar y gestionar los errores de forma interna, evitando que el usuario final se vea enfrentado a mensajes crípticos o a una página en blanco. Al tratar el parámetro "error" del objeto de resultado (una vez analizada sintácticamente la respuesta con JSON) se le informará de la posible causa del problema para que pueda solucionarlo correctamente, por ejemplo programando un mensaje de error inteligible para el usuario final.

Los mensajes de error devueltos por Media API contienen un código de error numérico, utilizado para clasificar los errores por tipos. Para más información, consulte Referencia de mensajes de error.

Administración de tokens y seguridad

Guarde su token de forma segura, ya que proporciona acceso a su biblioteca. Esto es especialmente importante si se plantea realizar llamadas a la API en el lado del cliente. Cualquiera de los que visitan su web puede "visualizar el código fuente" y ver el token de la API, que después podría utilizar para obtener sus metadatos, incluidos, potencialmente, los enlaces directos a sus activos.

Consulte Media API: Mejores prácticas de seguridad para más detalles y estrategias para mantener sus tokens seguros.

Limitaciones de Media API

En general, cualquier cosa que se pueda hacer con un vídeo o con una lista de reproducción en el módulo multimedia de Video Cloud Studio también se puede hacer con APIs de Media Write. Hay algunas excepciones. Las siguientes propiedades de vídeos no se pueden definir ni modificar mediante APIs de Media Write:

  • El indicador de sindicación viral
  • Cortinillas
  • Indicador "Forzar solicitudes de anuncios"

Ejemplos de Media API

Hemos creado muchos ejemplos de Media API para mostrarle las diferentes maneras de usar Media API. También hay ejemplos de uso en la Referencia de Media API.

Información relacionada

Ahora que ha leído esta introducción, consulte el resto de documentación sobre Media API: