CMS/API de reproducción: Vídeos Buscar v1

Introducción

En este tema, aprenderá cómo hacer lo siguiente:

• Crear y limitar una búsqueda básica utilizando el q parámetro
• Ordenar resultados de búsqueda
• Buscar utilizando términos requeridos y excluidos
• Usar una búsqueda entre comillas para que coincida con términos exactos y varias palabras
• Buscar en campos personalizados
• Buscar campos de fecha con una fecha específica y con rangos
• Combinar criterios de búsqueda

Uso de API

La funcionalidad de búsqueda se puede utilizar con CMS API o con la API de reproducción.

CMS API

Cuando se utiliza la búsqueda con la API de CMS, se aplica lo siguiente:

• Todas las solicitudes (incluida la búsqueda) requieren un encabezado de autorización que contenga sus tokens de acceso. Para obtener información detallada sobre cómo obtener credenciales de cliente y usarlas para recuperar tokens de acceso, consulte la descripción general de OAuth de Brightcove.
• No hay límite en el número máximo de vídeos devueltos de una búsqueda, pero sí se aplica un límite de velocidad.
• Los resultados de búsqueda incluyen todos los vídeos de tu cuenta, sean reproducibles o no, y/o georestringidos.

Para obtener detalles de solicitud/respuesta de API, consulte la sección Obtener vídeos de la Referencia de API de CMS.

Playback API

Cuando se utiliza la búsqueda con la API de reproducción, se aplica lo siguiente:

• Las solicitudes de búsqueda con la API de reproducción requieren una clave de directiva que esté habilitada para la búsqueda.
• Existe un límite en el número máximo de vídeos devueltos de una búsqueda.
• Los resultados de búsqueda solo devolverán vídeos que se puedan reproducir (los vídeos con state:inactive serán ignorados).
• Las búsquedas aplican restricciones de directivas de reproducción, como omitir vídeos con restricciones geográficas de los resultados.
• El almacenamiento en caché de los resultados proporciona tasas de solicitud más altas y respuestas más rápidas, y no hay limitación de velocidad.

Para obtener detalles de solicitud/respuesta de API, consulte la sección Obtener vídeos de la Referencia de la API de reproducción.

Búsqueda básica

Para realizar una búsqueda de términos en la biblioteca multimedia, utilice el q parámetro.

      q={search terms}

Los términos de búsqueda que especifique deben ser una lista codificada por url de términos separados por un espacio.

La búsqueda admite la derivación. Stemming es el mapeo de una palabra a la palabra raíz y otras palabras que provienen de la misma raíz. Por ejemplo, una búsqueda en «ejecutar» debe coincidir con los vídeos que tengan «corriendo» o «corriendo» en los campos especificados. No coincidiría con «runa» porque «runa» no tiene «ejecutar» como raíz.

Cuando no proporciona ningún calificador para un término de búsqueda, como q=bird, por ejemplo, la solicitud buscará ese valor en los siguientes campos:

• id [1-1]
• name
• description
• long_description
• text ( no es un campo de metadatos reales, sino un pseudo-campo que puede usar para buscar el name , description , y long_description - por ejemplo q=text:bird)
• tags
• reference_id
• custom_fields ( busca todos los campos personalizados)
• custom_field_name ( busca un campo personalizado específico con nombre)^[1-2]

Notas

      q=color:green%20color:blue

Ejemplo: Esta solicitud devuelve vídeos que tienen un valor de al menos bird en uno de los campos enumerados anteriormente.

      https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=bird 

Limitar la búsqueda a una propiedad específica

Cuando proporciona un calificador para un término de búsqueda, como, por ejemplo q=name:bird, la solicitud buscará en el name campo de vídeo un valor de bird.

Ejemplo: Esta solicitud devuelve vídeos que tienen un valor de wildlife en el name campo.

      https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=name:wildlife

Las búsquedas se realizan en los campos siguientes:

Notas

• ^{[ 2-1]} No es posible buscar vídeos que tengan un campo personalizado que no tenga valor o valor de null, porque a menos que se le haya dado un valor al campo, no es incluidos en los metadatos de vídeo en absoluto.
• ^{[ 2-2]} Al crear un nuevo vídeo, la complete propiedad se establece automáticamente en false. Tan pronto como exista una copia para el vídeo, la complete propiedad se establecerá automáticamente en true.
• ^{[ 2-3]} Las siguientes limitaciones se aplican a la búsqueda de vídeos ELIMINADOS:
  • La búsqueda de vídeos eliminados solo está disponible mediante la API de CMS; la API de reproducción no devolverá vídeos eliminados
  • Solo se devolverán los vídeos eliminados durante los 10 días anteriores (el tiempo actual menos 10 días)

Clasificación de los resultados de búsqueda

El sort parámetro le permite ordenar los resultados de una solicitud de obtención de vídeos. Puede ordenar por lo siguiente:

• reference_id
• name
• created_at
• published_at
• updated_at
• schedule.starts_at
• schedule.ends_at
• state
• plays_total
• plays_trailing_week

Cuando no se ordenan explícitamente los resultados mediante el uso de sort, los resultados se ordenarán de acuerdo con un algoritmo conocido como Frecuencia de Término/Frecuencia de Documento Inverso o TF-IDF. Consulte aquí para obtener más información.

Por ejemplo, supongamos que busca en los términos coastal,city y hay 120 videos en su cuenta que tienen esos términos en algún lugar de los metadatos de vídeo ( name , description , tags, etc.) y que también coinciden con los criterios de clasificación para los resultados (por ejemplo, todos tienen la misma schedule_starts_at fecha/hora). La altura de los resultados que aparece un vídeo viene determinada por la frecuencia con la que aparecen uno o ambos términos en los metadatos, con mayor peso dado al término que aparece con mayor frecuencia en la biblioteca de vídeos como un todo.

Términos obligatorios/excluidos

Puede marcar un término de búsqueda como "obligatorio" (el resultado de la búsqueda DEBE contener los vídeos que cumplan ese criterio) o como "excluido" (el resultado de la búsqueda debe mostrar los vídeos que NO lo cumplan). Esto se controla con una codificación URI + (%2B) o - signo inmediatamente anterior al término.

Debe codificar + como %2B cuando lo use para indicar un término requerido.

Ejemplo: Esta solicitud devuelve vídeos que TIENEN un valor de sea pero NO tienen un valor de lake en el tags campo.

      https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=%2Btags:sea%20-tags:lake

Consulte Combinación de criterios de búsqueda a continuación para ver cómo utilizar la sintaxis obligatoria/excluida para aplicar la lógica AND para varios términos de búsqueda.

Combinado con otros parámetros

Búsqueda (utilizando el q parámetro) se puede combinar con otros parámetros tales como sort , limit y offset. Todos los parámetros de URL están separados por &. El orden de los parámetros no importa.

Ejemplos

Ejemplo: Esta solicitud devuelve vídeos que deben tener un valor de bar en el tag campo y pueden tener un valor name que contenga foo

      .../videos?q=name:foo%20%2Btags:bar&sort=updated_at

Ejemplo: Esta solicitud devuelve los mismos vídeos que anteriormente, pero además ordena los resultados por el campo updated_at y luego limita los resultados a solo 10 vídeos.

      .../videos?sort=updated_at&q=name:foo%20%2Btags:bar&limit=10

Términos de búsqueda citados

De forma predeterminada, la función de búsqueda busca palabras que coincidan con los términos de búsqueda. Si desea hacer coincidir varias palabras, simplemente envuelva el término entre comillas.

La mayoría de los navegadores y otros agentes tratarán las comillas literales ("...") correctamente, pero si se encuentra con un caso en el que los términos de búsqueda citados no parecen devolver los resultados correctos, intente reemplazar las comillas con %22 (%22...%22)

            
              q="foo" or q=%22foo%22
              q="foo%20bar" or q=%22foo%20bar%22
            
          

Este sistema también funciona en campos determinados:

            
              q=name:"home"
              q=name:"home%20run"
            
          

Múltiples palabras

Ejemplo: Observe que esta solicitud devuelve vídeos que tienen un valor de sea o mammal en el tags campo.

      https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=tags:sea,mammal

Sin embargo, la siguiente solicitud devuelve sólo aquellos vídeos que tienen una etiqueta sea,mammal.

      https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=tags:"sea,mammal"

Campos personalizados

Puede buscar en cualquier campo personalizado que haya definido para sus vídeos.

      q=my_field:foo
      q=my_field:"foo"

Nota: todos los valores de campo personalizados se tratan como cadenas. Por ejemplo, si tiene un campo personalizado de tipo lista que puede tomar los valores true o false , buscar buscará esas cadenas, no valores booleanos (en muchos lenguajes de programación, 1 y se 0 puede usar indistintamente con true y false como valores booleanos, pero la búsqueda en q=my_boolean_field:1 no devuelve vídeos que se han my_boolean_field configurado en true).

Ejemplo: Esta solicitud devuelve vídeos que tienen un valor de animal en el campo subject personalizado.

      https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=subject:animal

Rango de fechas

Si está buscando en un campo de fecha, puede especificar una fecha específica o un rango de fechas, utilizando dos períodos para separar las fechas de inicio y finalización (q=updated_at:2018-01-01..2018-02-01).

Esto buscará todos los vídeos con un updated_at valor entre el 1 de agosto de 2012 y el 8 de octubre de 2012. Aquí estamos especificando cada fecha en formato UTC.

      q=updated_at:2012-08-01T00:00:00Z..2012-10-08T23:59:59Z

Puede simplificar esta búsqueda soltando los componentes de tiempo. Lo siguiente es equivalente a la búsqueda anterior.

      q=updated_at:2012-08-01..2012-10-08

Formatos de fecha compatibles

Los formatos de fecha admitidos incluyen UTC y relativo.

Fechas relativas

Para fechas relativas, apoyamos una dirección ( + o - ) seguida de un número, seguido de una duración. Las fechas relativas siempre se miden a partir de la hora actual. Las duraciones legales son: minutos, horas, días.

Ejemplos:

Rangos sin fecha final definida

Si desea buscar todas las fechas desde o hasta un momento dado, deje sin definir un extremo del rango.

Ejemplo: Buscar todos los videos modificados en los últimos 2 días

      q=updated_at:-2days..
      
      

Ejemplo: Buscar todos los videos modificados a partir del 11 de agosto de 2013:

      q=updated_at:2013-08-11T00:00:00Z..
      
      

NOW operador para fechas programadas

Para schedule.starts_at y schedule.ends_at , puede utilizar NOW como valor de fecha. Este es un operador de conveniencia que le permite configurar una consulta dinámica basada en la fecha y hora actual. Un par de ejemplos:

Combinar criterios de búsqueda

Puede combinar criterios para búsquedas complejas.

Ejemplo: Esta solicitud busca vídeos con name valor de chismes , actualizados entre el 1 de agosto de 2010 y el 8 de octubre de 2010. A continuación, ordena los datos de respuesta por updated_at fecha en orden descendente.

      q=%2Bname:gossip%20%2Bupdated_at:2010-08-01..2010-10-08&sort=-updated_at

Combinación de términos

Utilice la sintaxis obligatoria/excluida para devolver vídeos que tengan todos los términos especificados.

Por ejemplo, si busca en:

      q=name:foo +tags:bar (URI-encoded: q=name:foo%20%2Btags:bar)

la respuesta contendrá vídeos que tienen la etiqueta 'barra' y que también pueden tener foo en el nombre. Si quieres devolver solo aquellos vídeos que tengan foo en el nombre Y la etiqueta 'barra', debes buscar en:

      (unencoded) q=+name:foo +tags:bar (URI-encoded) q=%2Bname:foo%20%2Btags:bar

Del mismo modo, si desea devolver solo vídeos que tengan foo en el nombre, pero que no tengan la etiqueta 'barra', busque en:

      (unencoded) q=+name:foo -tags:bar (encoded) q=%2Bname:foo%20-tags:bar

Ejemplos

Buscar vídeos específicos

Si desea limitar su búsqueda a un conjunto específico de vídeos, puede hacerlo buscando en id:

Ejemplo: Esta solicitud devuelve vídeos con identificadores 123456789, 987654321 y 48376387

      q=id:123456789%20id:987654321%20id:48376387

Buscar por estado

Puede realizar o filtrar búsquedas por el estado del vídeo utilizando el parámetro:

      q=state:ACTIVE( | INACTIVE | PENDING | DELETED)[3]

Notas

• ^{[ 3]} Buscar vídeos BORRADOS solo está disponible para los vídeos eliminados en los últimos 10 días (el tiempo actual menos 10 días), y solo a través de CMS API(no la API de reproducción).

Staming

Se admite el Stemming, pero no las búsquedas parciales de palabras. Por ejemplo, q=name:ban debe devolver vídeos con los nombres "Parking Ban Announced " o "Parking to be Banned " o "City Banning Parking " pero no ""Bank Holiday" o "Bandit Captured».

Espacios/Caracteres Especiales

El CMS API generalmente maneja caracteres especiales en las cadenas de búsqueda, con un par de excepciones:

• Los espacios no están permitidos y deben codificarse como %20. ( + Los signos sin codificar también pueden reemplazar espacios, pero esto puede provocar confusión en sus consultas, ya que también + puede indicar que se requiere un término. Consulte sintaxis obligatoria/excluida)

  Por ejemplo, para buscar «mi video favorito» en el nombre:

  q=name:"my%20favorite%20video"

• Para buscar un + signo literal o utilizar el + para indicar que los vídeos devueltos deben incluir un término, debe codificar + como %2B:

  Búsqueda de vídeos que deben contener "two+two" en el campo Nombre

  q=name:two%2Btwo

  Búsqueda de vídeos que deben contener "heron" en el campo Nombre

  q=%2Bname:heron

• Es posible que algunos agentes no manejen las comillas literales correctamente, por lo que es más seguro codificar "foo" como %22foo%22

Para solicitudes puntuales, puede utilizar el codificador de cadenas de Brightcove Learning para codificar las cadenas de búsqueda. En el caso de las aplicaciones, deberá encontrar una función de codificación URI en el idioma que está utilizando.

Términos de búsqueda de clips

Los clips son vídeos creados a partir de secciones de otros vídeos. Brightcove Social puede generar clips y otros medios estarán disponibles en el futuro. Hay algunos términos de búsqueda especiales que puedes usar para buscar clips generados en una cuenta:

• q=%2Bis_clip:true - devuelve solo clips
• q=%2Bis_clip:false - devuelve sólo los que no son clips
• q=%2Bclip_source_video_id:video_id - devuelve clips generados a partir del vídeo especificado

Palabras ignoradas

Ciertas palabras se ignoran en las cadenas de búsqueda porque son tan comunes que es probable que devuelvan muchos resultados no relacionados con lo que realmente está buscando. A continuación se muestra una lista de palabras que son ignoradas por la búsqueda:

«a», «un», «y», «son», «como», «en», «ser», «pero», «por», «para», «si», «en», «en», «es», «es», «es», «no», «no», «de», «en», «o», «tal», «que», «el», «su», «entonces», «allí», «estos», «ellos», «esto», «a», «era», «voluntad», «con»

Problemas conocidos

• Resultados duplicados: en algunos casos, algunos elementos de los resultados de búsqueda pueden aparecer más de una vez.

  Solución alternativa: para evitar resultados de búsqueda duplicados, utilice siempre un sort parámetro en las solicitudes de búsqueda.