CMS /Playback API: Búsqueda de videos v1

Introducción

En este tema, aprenderá a hacer lo siguiente:

• Crea y limita una búsqueda básica usando el q parámetro
• Ordenar resultados de búsqueda
• Buscar usando términos requeridos y excluidos
• Utilice una búsqueda entre comillas para hacer coincidir los términos exactos y las palabras múltiples
• 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 el CMS API o las Playback API.

CMS API

Al utilizar la búsqueda con el CMS API, 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 las credenciales del cliente y usarlas para recuperar los tokens de acceso, consulte la Descripción general de Brightcove OAuth.
• No hay límite en la cantidad máxima de videos devueltos por una búsqueda, pero sí se aplica la limitación de velocidad.
• Los resultados de búsqueda incluyen todos los videos en su cuenta, ya sean jugables o no, y / o restringidos geográficamente.

Para detalles de solicitud / respuesta de API, vea el Obtener videos sección de la CMS API Referencia.

Playback API

Al utilizar la búsqueda con el Playback API, se aplica lo siguiente:

• Solicitudes de búsqueda con el Playback API requiere una clave de política que es habilitado para búsqueda.
• Hay un límite en la cantidad máxima de videos devueltos por una búsqueda.
• Los resultados de búsqueda solo mostrarán videos reproducibles (videos con state:inactive será ignorado).
• Las búsquedas imponen restricciones a la política de reproducción, como omitir videos geo-restringidos de los resultados.
• El almacenamiento en caché de resultados proporciona tasas de solicitud más altas y respuestas más rápidas, y no hay limitación de velocidad.

Para detalles de solicitud / respuesta de API, vea el Obtener videos sección de la Playback API Referencia.

Búsqueda básica

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

      q={search terms}

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

Soporte de búsqueda derivados. Stemming es la asignación 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 videos que tienen "ejecución" o "ejecución" en los campos especificados. Sería no coincide con "rune" porque "rune" no tiene "run" como su 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 nombrado 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 por un valor de bird.

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

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

Los campos de búsqueda compatibles son:

Notas

• ^{[2 1-]} Si es no posible buscar videos que tengan un campo personalizado que no tenga valor o un valor de null, porque a menos que el campo tenga un valor, no se incluye en absoluto en los metadatos del video.
• ^{[2 2-]} cuando creas un nuevo video, el complete la propiedad se configura automáticamente en false. Tan pronto como exista una versión para el video, la complete la propiedad se configurará automáticamente en true.
• ^{[2 3-]} Las siguientes limitaciones se aplican a la búsqueda de videos eliminados:
  • Buscar videos eliminados es -sólo- disponible usando el CMS API; El Playback API va a no devolver videos eliminados
  • Solo los videos eliminados durante los días anteriores de 10 (la hora actual menos 10 días) serán devueltos

Clasificación de resultados de búsqueda

La sort El parámetro le permite ordenar los resultados de una solicitud de obtención de videos. Puede ordenar de la siguiente manera:

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

Cuando no se clasifican 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í .

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

Términos requeridos / excluidos

Puede marcar un término de búsqueda según corresponda (los videos devueltos DEBEN coincidir) o excluidos (los videos devueltos NO deben coincidir). Esto se controla con un URI-codificado + (%2B) or - signo inmediatamente anterior al término.

Debes codificar + as %2B cuando se usa para indicar un término requerido.

Ejemplo: esta solicitud devuelve videos que TIENEN un valor de sea pero NO tienen un valor de lake en el objeto tags campo.

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

Vea Combinando criterios de búsqueda a continuación para ver cómo usar la sintaxis requerida / excluida para hacer cumplir la lógica AND para múltiples términos de búsqueda.

Combinado con otros params

Búsqueda (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 objeto 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 arriba, pero además ordena esos resultados por campo updated_at y luego limita los resultados a solo videos 10.

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

Términos de búsqueda citada

De forma predeterminada, una búsqueda hará coincidir palabras similares con sus términos de búsqueda. Si desea hacer coincidir varias palabras, simplemente ajuste 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 estar dando 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"
            
          

Múltiples palabras

Ejemplo: tenga en cuenta que esta solicitud devuelve videos que tienen un valor de sea or mammal en el objeto 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 campos personalizados se tratan como cadenas. Por ejemplo, si tiene un campo personalizado de tipo lista que puede tomar los valores true or 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 tengan my_boolean_field establecido en true).

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

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

Rangos 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 videos con un updated_at valor entre Aug 1, 2012 y October 8, 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 de arriba.

      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 apoyamos una dirección ( + or -) 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 un tiempo determinado, o hacer coincidir todas las fechas desde un tiempo determinado, deje un extremo del rango.

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

      q=updated_at:-2days..
      
      

Ejemplo: buscar todos los videos modificados a partir de agosto 11, 2013:

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

NOW operador para las fechas de programación

Para la schedule.starts_at y schedule.ends_at, puedes usar NOW como un valor de fecha. Este es un operador conveniente 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 chismes, que se actualizaron entre August 1, 2010 y October 8, 2010. Luego ordena los datos de respuesta 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 sintaxis requerida / excluida para devolver videos que tienen todos 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 'bar' y también pueden tener foo en el nombre. Si desea devolver solo aquellos 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 videos que tienen foo en el nombre, pero haz no tiene la etiqueta 'bar', debe buscar 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

Búsqueda por estado

Puede 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 los videos eliminados en los últimos días de 10 (la hora actual menos los días de 10), y solo a través de CMS API (no la Playback API).

Stemming

Stemming es compatible, pero no búsquedas parciales de palabras Por ejemplo, q=name:ban debería 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 / Personajes 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 estar codificados 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 debe incluir un término, debe codificar el + as %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 comillas literales correctamente, por lo que es más seguro codificar "foo" as %22foo%22

Para solicitudes únicas, puede usar Brightcove Learning's codificador de cadena para codificar tus cadenas de búsqueda. Para las aplicaciones, deberá encontrar una función de codificación URI en el idioma que está utilizando.

Clip de términos de búsqueda

Los clips son videos creados a partir de secciones de otros videos. Los clips pueden ser generados por Brightcove Social, y otros medios estarán disponibles en el futuro. Existen algunos términos de búsqueda especiales que puede usar para buscar 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

Ciertas 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 hay una lista de palabras que la búsqueda ignora:

"a", "an", "y", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into "," es "," it "," no "," no "," de "," on "," o "," tal "," ese "," el "," su "," luego ", "there", "these", "they", "this", "to", "was", "will", "with"

Problemas conocidos

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

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