Descripción general: API de CMS

En este tema, obtendrá una descripción general de la API de CMS. La CMS API proporciona acceso de lectura sin caché a los datos. Esto es importante para los flujos de trabajo de publicación urgentes porque realiza cambios en los videos y las listas de reproducción con el CMS API y lea rápidamente los datos para verificar que sean correctos.

Referencia de API

También vea el Referencia de API.

Información general

URL base

La URL base para el CMS API es:

        https://cms.api.brightcove.com/v1

Ruta de la cuenta

En todos los casos, las solicitudes se realizarán para un Video Cloud Cuenta. Por lo tanto, siempre agregarás el término accounts seguido del ID de tu cuenta a la URL base:

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

Autenticación

La autenticación para las solicitudes requiere un Authorization header :

        Authorization: Bearer {access_token}

La access_token es un token de acceso OAuth2 temporal que debe obtenerse del Brightcove OAuth Servicio. Para obtener más detalles, consulte la Descripción general de Brightcove OAuth.

La forma más sencilla de crear credenciales de cliente es a través de las páginas de administración de Brightcove Studio. Para obtener instrucciones detalladas, consulte Administrar las credenciales de autenticación de API

Operaciones

Cuando solicite credenciales de cliente, tendrá que especificar el tipo de acceso a la cuenta u operaciones que desea. La siguiente es una lista de las operaciones admitidas actualmente para el CMS API :

Datos de video:
video-cloud/video/read
video-cloud/video/create
video-cloud/video/update
video-cloud/video/delete
o
video-cloud/video/all
video-cloud/video/assets/delete (Solo es necesario si desea eliminar los maestros digitales; tenga en cuenta que no puedo obtenga este permiso cuando cree credenciales en Studio. Debe realizarse a través de la API de OAuth o la Aplicación de muestra creada por Brightcove Learning Services.)
Datos de la lista de reproducción:
video-cloud/playlist/read
video-cloud/playlist/create
video-cloud/playlist/update
video-cloud/playlist/delete
o
video-cloud/playlist/all
Notificaciones:
- video-cloud/notifications/all(para Notificaciones)

Limitación de velocidad

Esto CMS API proporciona acceso de lectura sin caché a los datos. Esto es importante para los flujos de trabajo de publicación urgentes porque realiza cambios en los videos y las listas de reproducción con el CMS API y lea rápidamente los datos para verificar que sean correctos.

La CMS API no es apropiado para el uso de tiempo de ejecución a gran escala (como acceder a videos en una página web pública de alto tráfico). Para aplicaciones de alto tráfico, debe usar una interfaz en caché como: el Playback API , Galería, Reproductores o los SDK nativos.

Para asegurar el desempeño de la Video Cloud sistema, no más de 20 llamadas simultáneas al CMS API están permitidos por cuenta. La frecuencia de acceso debe ser inferior a 10 solicitudes por segundo.

Si se integrarán varias aplicaciones al CMS API para una cuenta, estas aplicaciones deben tener una lógica de retroceso y reintento para manejar instancias en las que se alcanzan límites de simultaneidad o límites de tasa.

Si se excede el límite de tasa o de simultaneidad, 429 - TOO_MANY_REQUESTS se devolverá el error.

Conflictos de ID de referencia

Para asegurar la unicidad de los identificadores de referencia, el CMS API bloquea la identificación hasta 3 minutos después de cualquier operación en el video al que está asignado. Esto puede provocar que se devuelvan errores 409 cuando intentas reintentar una solicitud que falla demasiado rápido, o cuando intentas reutilizar una identificación de referencia demasiado pronto después de eliminar el video al que se asignó previamente. Ver el Referencia de mensaje de error para más detalles.

Límite de recursos de video

Hay un límite de 1,000 activos por video. Los activos incluyen reproducciones, pistas de audio, pistas de texto e imágenes, así como el master digital. Las representaciones y las imágenes rara vez suman más de 10-15 activos, por lo que incluso si tuviera pistas de audio y de texto separadas para 150 idiomas diferentes, aún tendría menos de 350 activos.

Notas de uso

La CMS API está destinado a integraciones y flujos de trabajo de publicación. No puede realizar llamadas del lado del cliente a esta API desde una página web pública, ya que hacerlo implicaría exponer sus credenciales de cliente para la API (por ese motivo, la API no está habilitada para CORS). Puede realizar llamadas desde una aplicación del lado del cliente (web), siempre que enrute las llamadas de la API a través de un proxy del lado del servidor. Brightcove Learning Services proporciona varios aplicaciones de muestra que utilizan este enfoque, y un guía para crear este tipo de aplicación.

Si va a recuperar todos sus videos o grandes conjuntos de videos, asegúrese de ver la nota sobre grandes conjuntos de datos.

Evite las URL codificadas de forma rígida

Las URL de miniaturas, carteles, archivos de video y otros medios nunca deben codificarse en sus páginas o aplicaciones. La CMS API siempre devolverá las URL actuales para los archivos multimedia, pero las URL en sí están sujetas a cambios. Deberías usar el CMS API ( o Playback API ) solicita recuperar estas URL cada vez que se carga la página, o almacenarlas en caché durante no más de seis horas.

Almacenamiento en caché de URL de imágenes y videos

Puede almacenar en caché las URL de videos e imágenes para mejorar el rendimiento de la página, pero la caché debe actualizarse con regularidad. Si almacena en caché las URL que recupera para mejorar el rendimiento de sus páginas, asegúrese de actualizar la caché repitiendo las llamadas a la API al menos una vez cada seis horas.

Métodos

Actualmente, la API admite los siguientes tipos de solicitudes:

GET
POST
PATCH
PUT
DELETE

Parámetros

Tenga en cuenta que todos los parámetros son Opcional. Excepto donde se indique, se aplican a GET solicitudes de videos y listas de reproducción.

Parámetros de solicitud GET
Parámetro	Descripción
`q`	Cadena de consulta para búsquedas: consulte Sintaxis de búsqueda para más información
`limit`	Número de videos que se devolverán: debe ser un número entero entre 1 y 100. Predeterminado: 20
`offset`	Número de videos para omitir (para resultados de paginación). Debe ser un número entero positivo. Predeterminado: 0
`sort`	Una cadena que especifica el campo por el que ordenar. Empezar con `-` ordenar descendente. Si un valor para `q` se proporciona, entonces el orden predeterminado es por "puntuación" (relevancia de los resultados de la búsqueda para la consulta original). Si no hay valor para `q` se proporciona, entonces el orden predeterminado es por `updated_at` descendente. Los siguientes campos son válidos para ordenar: `name` , `reference_id` , `created_at` , `published_at` , `updated_at` , `schedule_starts_at` , `schedule_ends_at` , `state` , `plays_total` , y `plays_trailing_week`

Buscar videos

Brightcove's CMS API proporciona una forma programática de buscar videos en su Video Cloud Biblioteca.

Para realizar búsquedas básicas y complejas en sus datos de video, utilizará el q parámetro:

        https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q={search terms}

Para obtener detalles sobre cómo buscar videos, consulte la Buscar videos documento.

Para las listas de reproducción, los valores admitidos para la cadena de búsqueda son más limitados. Actualmente puedes buscar por type , name , description , y reference_id. A continuación, se muestran algunos ejemplos de búsquedas válidas:

q=type:EXPLICIT
q=type:ACTIVATED_OLDEST_TO_NEWEST
q=type:ALPHABETICAL
q=bears+otters(el nombre, la descripción o el ID de referencia deben contener "osos" o "nutrias")
q=%2Bname:bears+type:EXPLICIT(el nombre debe contener "osos")

Ver Buscar listas de reproducción para más detalles.

Anote el término de búsqueda playable:true/false que puede usar para devolver solo videos que se pueden reproducir (o no):

        https://cms.api.brightcove.com/v1/accounts/:account_id/videos?q=%2Bplayable:true

Esta consulta requiere que los videos devueltos se puedan reproducir (no desactivados, no programados y que no carezcan de representaciones reproducibles).

Si está buscando videos que son no jugable, uso q=%2Bplayable:false.

Resultados de paginación

Utilizar el limit parámetro para especificar cuántos elementos desea devolver en una solicitud, hasta 100. A continuación, puede utilizar el offset parámetro para paginar conjuntos de resultados que son más grandes que el limit. La offset es el número de elementos que se deben omitir.

Por ejemplo, la siguiente búsqueda devuelve videos del 51 al 75 del conjunto de resultados total, asumiendo que el conjunto de resultados total tiene al menos 75 videos:

        /videos?q=updated_at:2014-01-01..2014-06-30&limit=25&offset=50

La limit y offset Los parámetros se pueden usar tanto para videos como para listas de reproducción.

Nota: limit y offset hacer no funciona cuando solicita los videos que pertenecen a una lista de reproducción; esta solicitud siempre devolverá todos los videos en la lista de reproducción.

Mejores prácticas de paginación

Debido a que puede haber operaciones de modificación simultáneas en curso con la API de CMS, se recomienda seguir estos pasos al desplazarse por el conjunto de resultados:

Hacer una count Solicite obtener la cantidad total de videos en su conjunto de resultados.
```
      /accounts/578380111111/counts/videos?q=tags:nature
```
Utilizar el limit y offset parámetros para devolver grupos de datos de su conjunto de resultados.
```
      /accounts/578380111111/videos?q=tags:nature&limit=20&offset=50
```
Tenga en cuenta que algunas páginas pueden tener menos de 20 videos. Sabrá que ha llegado al final del conjunto de resultados cuando haya solicitado tantos videos como en el primero count pedido.

Para resumir, siga recuperando páginas hasta que obtenga un recuento de videos igual al original count solicitud, ya que este número debería pecar de sobreestimación. Pregunta por:

      count / page-size + 1 page

Ordenar los resultados de los videos

Usa el parámetro sort=field_name para especificar cómo se deben ordenar los resultados, puede ordenar tanto los videos como las listas de reproducción. Puede ordenar los siguientes campos de video: ^[1-1]

Prefije el nombre del campo con un signo menos ( sort= -field_name ) en orden descendente.

name
reference_id
created_at
published_at
updated_at
schedule_starts_at(nota: este es el clasificar campo - el el campo de búsqueda es schedule.starts_at )
schedule_ends_at(nota: este es el clasificar campo - el el campo de búsqueda es schedule.ends_at )
state
plays_total ^[1-2]
plays_trailing_week ^[1-2]

Notas

^[1-1] Si no proporciona un valor de clasificación para una llamada de búsqueda de video, los resultados se ordenarán por relevancia. Si no proporciona un valor de clasificación para un GET llamada de videos, los resultados se ordenarán por updated_at descendente.
^[1-2] Puedes ordenar en plays_total o plays_trailing_week , pero estos campos no se incluyen en los resultados

Ordenar los resultados de la lista de reproducción

Puede ordenar las listas de reproducción en los siguientes campos:

name
updated_at(por defecto)

Prefije el nombre del campo con un signo menos ( sort= -field_name ) en orden descendente.

Todos los videos y grandes conjuntos de datos

Si está recuperando todos los videos de su cuenta, o una gran cantidad de videos, hay algunas cosas que debe tener en cuenta:

Puede tener la tentación de utilizar el mayor permitido limit (100), pero es mejor recuperar videos en lotes de 25 o menos para minimizar la posibilidad de que se agote el tiempo de espera de las solicitudes de API
A medida que navega a través de grandes conjuntos de datos, es posible que los datos de video se actualicen durante la operación, lo que podría hacer que los elementos cambien en las respuestas:
- Es posible que vea un elemento repetido en páginas sucesivas.
- Es posible que se pierda un elemento, ya que se ha cambiado a un conjunto de respuestas anterior
Para tener en cuenta la primera posibilidad, su aplicación debe eliminar la lista completa de elementos una vez que haya terminado de recuperar los videos. Para manejar la segunda posibilidad, debe comparar el número total de elementos recuperados (después de la eliminación de duplicados) con el número que esperaba, y luego volver a ejecutar las solicitudes, clasificando los resultados por last_modified_date (descendente); no debería ser necesario recuperar más de un lote para recoger los artículos perdidos.
Puede disminuir la probabilidad de los escenarios en el elemento anterior ordenando los resultados devueltos de manera adecuada. La clasificación predeterminada por Relevancia para búsquedas se basa en un algoritmo complejo que busca combinaciones de palabras clave, etiquetas y valores de campos personalizados. Si está buscando videos basados en múltiples palabras clave, etiquetas y / o campos personalizados, ordenar por relevancia es exactamente lo que desea. Sin embargo, si solo está intentando recuperar todos o una gran parte de sus videos, sort El parámetro explícitamente le dará más control sobre el orden de los elementos devueltos.

Operaciones de video

Las operaciones de video incluyen:

Obtenga un recuento de videos o resultados de búsqueda
Obtener todos los videos
Obtener uno o más videos por id o id de referencia
Crear, recuperar, actualizar y eliminar videos
Buscar videos
Obtenga fuentes de video, imágenes e información maestra digital
Obtén las listas de reproducción a las que pertenece un video
Eliminar el video de todas las listas de reproducción

Los detalles de las operaciones de video se pueden encontrar en el Referencia de API.

Operaciones de lista de reproducción

Las operaciones de la lista de reproducción incluyen:

Obtenga un recuento de listas de reproducción
Obtener todas las listas de reproducción
Crear, actualizar y eliminar listas de reproducción
Obtener un recuento de videos en una lista de reproducción
Obtener los videos en una lista de reproducción

Los detalles de las operaciones de la lista de reproducción se pueden encontrar en el Referencia de API.

Activos

Las operaciones de activos le permiten administrar activos, incluidas representaciones, manifiestos, imágenes y pistas de texto. Para ingerir activos, debe utilizar el Dynamic Ingest API. La POST y PATCH operaciones para el CMS API /assets se puede utilizar para agregar y actualizar activos remotos. CMS API Las operaciones GET funcionarán para ambas cosas activos ingeridos y remotos.

Agregar, actualizar o eliminar representaciones
Agregar, actualizar o eliminar metadatos para el maestro digital
Agregar, actualizar o eliminar manifiestos para tipos de video segmentados como HLS
Agregar, actualizar o eliminar pósters e imágenes en miniatura
Agregar, actualizar o eliminar pistas de texto WebVTT o subtítulos DFXP

Los detalles de las operaciones de activos se pueden encontrar en el Referencia de API.

Operaciones de campo personalizadas

Actualmente hay una operación de campo personalizado:

Obtenga todos los campos personalizados para una cuenta

Los detalles de las operaciones de campo personalizadas se pueden encontrar en el Referencia de API.

Operaciones de carpeta

Las operaciones de carpeta le permiten:

Obtener una lista de carpetas
Crear, actualizar y eliminar carpetas
Obtener una lista de videos en una carpeta
Agregar un video a una carpeta
Eliminar un video de una carpeta

Los detalles de las operaciones de la carpeta se pueden encontrar en el Referencia de API.

Notificaciones

Puedes recibir notificaciones cuando video-change eventos ocurren en su videoteca o master-video-change notificaciones cuando un video compartido actualiza sus activos automáticamente después de que el video maestro lo actualice. Las notificaciones se enviarán a la URL que especifique, que debe apuntar a una aplicación capaz de manejar solicitudes HTTP POST.

Fallas de notificación

El sistema de notificación trata cualquier devolución 4xx o 5xx del servidor del cliente como una falla recuperable. Las devoluciones de llamada fallidas se reintentarán hasta 20 veces, con un retraso que aumenta exponencialmente entre las devoluciones de llamada posteriores. Los primeros reintentos ocurrirán minutos después del intento inicial de devolución de llamada. Si la devolución de llamada continúa fallando y llegamos al vigésimo reintento, la demora del reintento será de unos días.

video-change los eventos son activados por procesos automatizados del sistema, así como por acciones del usuario, por lo que estos eventos no siempre se corresponden con los cambios que realizó en las propiedades del video en Studio o a través de las API.

Cortafuegos

En caso de que su organización tenga una política estricta con respecto a las fuentes de tráfico entrante a través de su firewall, permitimos todas las direcciones IP de la región este de AWS. Esto está sujeto a cambios, por lo que todas las direcciones IP de AWS deben incluirse en la lista blanca. Ver https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html para más información.

Operaciones de notificación

Las operaciones actualmente disponibles para notificaciones son:

Crea suscripciones
Obtenga una o todas las suscripciones
Eliminar una suscripción

Los detalles de las operaciones de notificación se pueden encontrar en el Referencia de API.