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 elname
,description
, ylong_description
- por ejemploq=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=id:12345
devolverá exactamente los mismos resultados que la solicitud https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/12345
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:
Campo | Valores legales |
---|---|
name |
cadenas de texto suelto o entrecomillado |
text | cadenas o cadenas entre comillas (busca en,, y)name description long_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 enfalse
. Tan pronto como exista una copia para el vídeo, lacomplete
propiedad se establecerá automáticamente entrue
. - [ 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 | 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.
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:
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:
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
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 Nombreq=name:two%2Btwo
Búsqueda de vídeos que deben contener
"heron"
en el campo Nombreq=%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 clipsq=%2Bis_clip:false
- devuelve sólo los que no son clipsq=%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.