CMS / API de reproducción: Búsqueda de vídeos v1

Introducción

En este tema, aprenderá a hacer lo siguiente:

• Cree y limite una búsqueda básica usando el q parámetro
• Ordenar resultados de búsqueda
• Buscar utilizando términos obligatorios y excluidos
• Utilice una búsqueda entre comillas para hacer coincidir 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 función de búsqueda se puede utilizar con el CMS API o la API de reproducción.

API de CMS

Al utilizar 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 contiene sus tokens de acceso. Para obtener detalles sobre cómo obtener credenciales de cliente y usarlas para recuperar tokens de acceso, consulte la Descripción general de Brightcove OAuth.
• No hay límite en la cantidad máxima de videos devueltos de una búsqueda, pero se aplica una limitación de velocidad.
• Los resultados de la búsqueda incluyen todos los videos de su cuenta, ya sean reproducibles o no, y / o restringidos geográficamente.

Para obtener detalles sobre la solicitud / respuesta de la API, consulte la Obtener videos sección de la Referencia de la API de CMS.

API de reproducción

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 política que sea habilitado para búsqueda.
• Hay un límite en el número máximo de videos devueltos de una búsqueda.
• Los resultados de la búsqueda solo mostrarán videos que se puedan reproducir (videos con state:inactive será ignorado).
• Las búsquedas hacen cumplir las restricciones de la política de reproducción, como la omisión de videos restringidos geográficamente 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 sobre la solicitud / respuesta de la API, consulte la Obtener videos sección de la Referencia de la API de reproducción.

Búsqueda básica

Para realizar una búsqueda de términos en su biblioteca de medios, use el q parámetro.

      q={search terms}

Los términos de búsqueda que especifique deben ser una lista de términos codificados en URL separados por un espacio.

Soportes de búsqueda derivando. La derivación es el mapeo de una palabra a la raíz de la palabra y otras palabras que provienen de la misma raíz. Por ejemplo, una búsqueda en "ejecutar" debe coincidir con los videos que tienen "en ejecución" o "en ejecución" en los campos especificados. Sería no coincide 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 , la solicitud buscará ese valor en los siguientes campos:

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

Notas

      q=color:green%20color:blue

Ejemplo: Esta solicitud devuelve videos que tienen un valor de bird en al menos 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 q=name:bird , la solicitud buscará el video name campo para un valor de bird.

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

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

Los campos de búsqueda admitidos son:

Notas

• ^[2-1] Es no posible buscar videos que tienen un campo personalizado que no tiene valor o un valor de null , porque a menos que se le haya dado un valor al campo, no se incluye en los metadatos del video.
• ^[2-2] cuando creas un nuevo video, el complete la propiedad se establece automáticamente en false. Tan pronto como exista una versión del video, el complete la propiedad se establecerá automáticamente en true.
• ^[2-3] Las siguientes limitaciones se aplican a la búsqueda de videos ELIMINADOS:
  • La búsqueda de videos eliminados es solo disponible usando la API de CMS; la API de reproducción no devolver videos eliminados
  • Solo los videos eliminados durante los 10 días anteriores (la hora actual menos 10 días) serán devueltos

Clasificación de los resultados de la búsqueda

La sort El parámetro le permite ordenar los resultados de una solicitud de obtención de videos. 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 inversa o TF-IDF. Ver aquí para más información.

Por ejemplo, supongamos que busca los términos coastal,city y hay 120 videos en su cuenta que tienen esos términos en algún lugar de los metadatos del video ( name , description , tags , etc.) y que también coincidan con los criterios de clasificación de los resultados (por ejemplo, todos tienen el mismo schedule_starts_at fecha y hora). El nivel de resultados de un video lo determina la frecuencia con la que uno o ambos términos aparecen en los metadatos, y se le da mayor importancia al término que aparece con más frecuencia en la biblioteca de videos en su conjunto.

Términos obligatorios / excluidos

Puede marcar un término de búsqueda como requerido (los videos devueltos DEBEN coincidir) o excluidos (los videos devueltos NO deben coincidir). Esto se controla con un código URI. + (%2B) o - Firmar inmediatamente antes del término.

Debes codificar + como %2B al usarlo para indicar un término requerido.

Ejemplo: Esta solicitud devuelve videos que TIENEN un valor de sea pero NO tiene un valor de lake en el tags campo.

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

Ver Combinando criterios de búsqueda a continuación para ver cómo utilizar la sintaxis requerida / excluida para aplicar la lógica Y para varios términos de búsqueda.

Combinado con otros parámetros

Buscar (usando 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 videos que deben tener un valor de bar en el tag campo y puede tener un name conteniendo valor foo

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

Ejemplo: Esta solicitud devuelve los mismos videos que el anterior, pero además clasifica esos resultados por el campo updated_at y luego limita los resultados a solo 10 videos.

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

Términos de búsqueda citados

De forma predeterminada, una búsqueda hará coincidir palabras similares con sus 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 resultados correctos, intente reemplazar las comillas con %22 (%22...%22)

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

Esto también funciona cuando se busca en un campo específico:

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

Varias palabras

Ejemplo: Tenga en cuenta que esta solicitud devuelve videos 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

Pero, la siguiente solicitud devuelve solo aquellos videos 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 videos.

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

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

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

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

Intervalos de fechas

Si está buscando en un campo de fecha, puede especificar una fecha específica o un rango de fechas, usando 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 videos 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 eliminando 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 admitidos

Los formatos de fecha admitidos incluyen UTC y relativo.

Fechas relativas

Para fechas relativas admitimos una dirección ( + o - ) seguido 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 abiertos

Si desea hacer coincidir todas las fechas hasta una hora determinada, o hacer coincidir todas las fechas desde una hora determinada, deje un extremo del rango.

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

      q=updated_at:-2days..
      
      

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

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

NOW operador para fechas de programación

Para schedule.starts_at y schedule.ends_at , puedes usar 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 videos con un name valor de chisme , que se actualizaron entre el 1 de agosto de 2010 y el 8 de octubre de 2010. Luego 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

Combinando términos

Utilizar el sintaxis requerida / excluida para devolver videos que tienen todas de 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á videos que tienen la etiqueta "barra" y también pueden tener foo en el nombre. Si desea devolver solo los videos que tienen foo en el nombre Y la etiqueta 'barra', debe buscar en:

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

Del mismo modo, si desea devolver solo los videos que tienen foo en el nombre, pero haz no tiene la etiqueta 'bar', buscaría en:

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

Ejemplos

Buscar videos específicos

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

Ejemplo: Esta solicitud devuelve videos con ID 123456789 , 987654321 y 48376387

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

Buscar por estado

Puedes realizar o filtrar búsquedas por el estado del video usando el parámetro:

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

Notas

• ^[3] La búsqueda de videos BORRADOS solo está disponible para videos eliminados en los últimos 10 días (la hora actual menos 10 días), y solo a través del CMS API (no la API de reproducción).

Derivado

Se admite la derivación, pero no búsquedas de palabras parciales. Por ejemplo, q=name:ban debe devolver videos 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

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

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

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

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

• Para buscar un literal + firmar o usar el + para indicar que los videos devueltos deber incluir un término, debe codificar el + como %2B:

  Buscando videos que deben contener "two+two" en el campo de nombre

  q=name:two%2Btwo

  Buscando videos que deben contener "heron" en el campo de 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 únicas, puede utilizar Brightcove Learning's codificador de cadena para codificar sus cadenas de búsqueda. Para 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 videos creados a partir de secciones de otros videos. Los clips pueden ser generados por Redes sociales de Brightcove , y otros medios estarán disponibles en el futuro. Hay algunos términos de búsqueda especiales que puede utilizar para encontrar clips generados en una cuenta:

• q=%2Bis_clip:true- devuelve solo clips
• q=%2Bis_clip:false- devuelve solo no clips
• q=%2Bclip_source_video_id:video_id- devuelve clips generados a partir del video especificado

Palabras ignoradas

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

"a", "una", "y", "son", "como", "en", "ser", "pero", "por", "para", "si", "en", "en "," es "," eso "," no "," no "," de "," en "," o "," tal "," ese "," el "," su "," entonces ", "allí", "estos", "ellos", "esto", "a", "estaba", "será", "con"

Problemas conocidos

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

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