soporte Contactar con Soporte | Estadoestado del sistema del sistema
Contenido de la página

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

    En este tema, aprenderá a buscar vídeos en su cuenta mediante la API de CMS. CMS API Proporciona una forma programática de buscar vídeos en la biblioteca de Video Cloud. En este tema se proporciona información detallada sobre la sintaxis de búsqueda. Nota: esta es la sintaxis de búsqueda original; le recomendamos que utilice la sintaxis de búsqueda de vídeo v2más simple.

    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.

    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

    [ 1-1] Nota: la búsqueda por id se incluye para obtener coherencia, pero una búsqueda en q=id:12345 devolverá exactamente los mismos resultados que la solicitud https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/12345
    [ 1-2] Si tiene un campo personalizado de tipo lista y desea devolver vídeos que tengan uno de varios valores, puede hacerlo así:

    Supongamos que tiene un campo llamado color que puede tomar los valores: red , green , yellow , o blue. Desea buscar vídeos que tengan ese campo establecido en el valor green o blue:

          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:

    Campos de búsqueda admitidos
    Campo Valores legales
    name cadenas de texto suelto o entrecomillado
    text cadenas o cadenas entre comillas (busca en,, y)namedescriptionlong_description
    tags cadenas o cadenas entre comillas (varias etiquetas deben estar delimitadas por comas)
    custom_fields cadenas o cadenas entre comillas (busca en todos los campos personalizados - también puede usar un nombre interno de campo personalizado específico) [2-1]
    reference_id cadena o cadena entre comillas
    state ACTIVE, INACTIVE, PENDING, DELETED [2-3]
    updated_at intervalo de fechas
    created_at intervalo de fechas
    schedule.starts_at intervalo de fechas
    schedule.ends_at intervalo de fechas
    published_at intervalo de fechas
    complete [ 2-2] true o false

    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.

    Términos requeridos/excluidos
    ejemplo codificado en URL significado
    +foo %2Bfoo los videos DEBEN incluir el término foo en el name , description , long_description , tags , reference_id o custom_fields
    +custom_fields:foo %2Bcustom_fields:foo vídeo DEBE incluir el valor foo de algún campo personalizado
    +foo -bar %2Bfoo%20-bar los videos DEBEN incluir el término foo pero NO debe incluir el término bar en el name , description , long_description , tags , reference_id o custom_fields
    +name:foo -name:bar %2Bname:foo%20-name:bar Los videos DEBEN incluir el término foo , pero NO debe incluirlo bar en el name

    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.

    Ejemplos de formato de fecha
    formato (formato codificado URI) significado
    2015-08-01T 06:15:00 Z Esto representa una hora en UTC.
    2012-08-01 Esto representa la medianoche de un día en UTC. El ejemplo es equivalente a 2012-08-01T 00:00:00 Z
    -1d La hora actual menos 1 día. (véase más adelante)

    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:

    Muestras de fecha relativa
    q param para fechas Significado
    q=updated_at ፦1día.. AHORA vídeos actualizados desde hace 1 día hasta el día actual
    q=created_at ፦2días vídeos añadidos hace 2 días
    q=updated_at ፦4hours.. AHORA vídeo actualizado desde hace 4 horas hasta la hora actual
    q=created_at ፦60minutos.. vídeos añadidos desde hace 60 minutos a la hora actual
    q=created_at:2016-01-01.. -1d vídeos creados desde enero 1, 2015 hasta hace un día
    q=updated_at ፦14d.. AHORA vídeos en las últimas dos semanas

    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:

    Ejemplos de datos de planificación
    desde/hasta params Codificado por URI Significado
    ?q=schedule.starts_at:.. AHORA ?q=schedule.starts_at:.. AHORA starts_at es desde el principio del tiempo hasta este momento
    ?Q=schedule.starts_at:ahora ?Q=schedule.starts_at:ahora starts_at es a partir de este momento
    ?Q=schedule.ends_at:Ahora.. ?Q=schedule.ends_at:Ahora.. ends_at es desde este momento hasta el final del tiempo
    ?q=+schedule.starts_at:.. AHORA +schedule.ends_AT:Ahora.. ?Q=%2BSchedule.starts_at:.. ahora% 20% 2bSchedule.ends_AT:Ahora.. starts_at antes de este momento y fins_at después de este momento (el video está programado este momento)

    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

    Muestras: Combinación de términos
    Cadena de búsqueda sin codificar Cadena de búsqueda codificada por URI Significado
    q=foo bar q=foo%20bar los artículos devueltos tienen «foo» O «bar»
    q=foo +bar q=foo%20%2Bbar los artículos devueltos deben tener «bar», pueden tener «foo»
    q=+foo bar q =%2Bfoo%20bar Los artículos devueltos deben tener «foo», pueden tener «bar»
    q=+foo +bar q=%2Bfoo%20%2Bbar El artículo devuelto debe tener «foo» Y «bar»
    q=-foo +bar q=-foo%20%2Bbar El artículo devuelto debe tener «barra» Y no tener «foo»
    Búsquedas de varias etiquetas
    q=tags:bee,bop q=tags:bee,bop devuelve vídeos con la etiqueta «abeja» O «bop»
    q=tags:bee tags:bop q=tags:bee%20tags:bop devuelve vídeos con la etiqueta «abeja» O «bop»
    q=+tags:bee tags:bop q=%2Btags:bee%20tags:bop todos los vídeos devueltos deben tener la etiqueta «bee»; también pueden tener la etiqueta «bop»
    q=+tags:bee +tags:bop q=%2Btags:bee%20%2Btags:bop todos los vídeos devueltos tendrán la etiqueta «abeja» Y la etiqueta «bop»

    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.


    Última actualización de la página el 24 oct 2020