CMS/API de lecture : Vidéos Recherche v1

Introduction

Dans cette rubrique, vous apprendrez à effectuer les opérations suivantes :

• Créez et limitez une recherche de base à l'aide du q paramètre
• Trier les résultats de la recherche
• Rechercher en utilisant les termes obligatoires et exclus
• Utilisez une recherche entre guillemets pour faire correspondre des termes exacts et plusieurs mots
• Rechercher sur des champs personnalisés
• Rechercher des champs de date avec une date spécifique et avec des plages
• Combiner les critères de recherche

Utilisation de l'API

La fonctionnalité de recherche peut être utilisée avec CMS API ou avec l'API de lecture.

API CMS

Lorsque vous utilisez la recherche avec l'API CMS, les éléments suivants s'appliquent :

• Toutes les demandes (y compris la recherche) nécessitent un en-tête d'autorisation qui contient vos jetons d'accès. Pour plus de détails sur la façon d'obtenir les informations d'identification client et de les utiliser pour récupérer des jetons d'accès, consultez le Présentation de Brightcove OAuth.
• Il n'y a pas de limite au nombre maximum de vidéos renvoyées par une recherche, mais une limitation du taux s'applique.
• Les résultats de la recherche incluent toutes les vidéos de votre compte, qu'elles soient jouables ou non, et/ou géo-restreintes.

Pour plus de détails sur les requêtes/réponses de l'API, consultez le Obtenir des vidéos partie de la Référence de l'API CMS.

API de lecture

Lorsque vous utilisez la recherche avec l'API Playback, les éléments suivants s'appliquent :

• Les requêtes de recherche avec l'API Playback nécessitent une clé de stratégie qui est activé pour la recherche.
• Il y a un limite sur le nombre maximum de vidéos renvoyées par une recherche.
• Les résultats de la recherche ne renverront que les vidéos lisibles (vidéos avec state:inactive sera ignoré).
• Les recherches appliquent des restrictions de politique de lecture, telles que l'omission des vidéos géo-restreintes dans les résultats.
• La mise en cache des résultats fournit des taux de requêtes plus élevés et des réponses plus rapides, et il n'y a pas de limitation de débit.

Pour plus de détails sur les requêtes/réponses de l'API, consultez le Obtenir des vidéos partie de la Référence de l'API de lecture.

Recherche de base

Pour effectuer une recherche de termes dans votre médiathèque, utilisez le q paramètre.

      q={search terms}

Les termes de recherche que vous spécifiez doivent être une liste de termes codés par URL séparés par un espace.

La recherche supporte le découpage. La racine est le mappage d'un mot à la racine du mot et à d'autres mots qui proviennent de la même racine. Par exemple, une recherche sur « exécuter » doit correspondre aux vidéos contenant « en cours d'exécution » ou « en cours d'exécution » dans le(s) champ(s) spécifié(s). Ce serait ne pas match "rune" car "rune" n'a pas "run" comme racine.

Lorsque vous ne fournissez aucun qualificatif pour un terme de recherche, tel que q=bird , la requête recherchera cette valeur dans les champs suivants :

• id [1-1]
• name
• description
• long_description
• text(pas un vrai champ de métadonnées, mais un pseudo-champ que vous pouvez utiliser pour rechercher le name , description , et long_description - par exemple q=text:bird)
• tags
• reference_id
• custom_fields(recherche dans tous les champs personnalisés)
• custom_field_name ( recherche un champ personnalisé nommé spécifique)^[1-2]

Remarques

      q=color:green%20color:blue

Exemple : Cette requête renvoie des vidéos dont la valeur est bird dans au moins un des domaines énumérés ci-dessus.

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

Limiter la recherche à une propriété spécifique

Lorsque vous fournissez un qualificatif pour un terme de recherche, tel que q=name:bird , la demande recherchera la vidéo name champ pour une valeur de bird.

Exemple : Cette requête renvoie des vidéos dont la valeur est wildlife dans le name champ.

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

Les champs de recherche pris en charge sont :

Remarques

• ^{[ 2-1]} Il n'est pas possible de rechercher des vidéos qui ont un champ personnalisé qui n'a pas de valeur ou de valeur null, car à moins que le champ n'ait reçu une valeur, il n'est pas inclus dans les métadonnées vidéo.
• ^{[ 2-2]} Lorsque vous créez une nouvelle vidéo, la complete propriété est automatiquement définie sur false. Dès qu'un rendu existe pour la vidéo, le complete la propriété sera automatiquement définie sur true.
• ^{[ 2-3]} Les limitations suivantes s'appliquent à la recherche de vidéos SUPPRIMÉES :
  • La recherche de vidéos supprimées est seul disponible à l'aide de l'API CMS ; l'API de lecture ne pas retourner les vidéos supprimées
  • Seul les vidéos supprimées au cours des 10 derniers jours (l'heure actuelle moins 10 jours) seront renvoyées

Tri des résultats de recherche

Les sort Le paramètre vous permet de trier les résultats d'une demande d'obtention de vidéos. Vous pouvez trier sur les éléments suivants :

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

Lorsque vous ne triez pas explicitement les résultats à l'aide de sort , les résultats seront triés selon un algorithme connu sous le nom de fréquence de terme/fréquence de document inverse ou TF-IDF. Voir ici pour plus d'informations.

Par exemple, disons que vous effectuez une recherche sur les termes coastal,city et il y a 120 vidéos dans votre compte qui ont ces termes quelque part dans les métadonnées de la vidéo ( name , description , tags , et ainsi de suite) et qui correspondent également aux critères de tri des résultats (par exemple, ils ont tous le même schedule_starts_at date/heure). La hauteur des résultats d'une vidéo est déterminée par la fréquence à laquelle l'un ou les deux termes apparaissent dans les métadonnées, avec une plus grande importance accordée au terme qui apparaît le plus fréquemment dans votre bibliothèque de vidéos dans son ensemble.

Termes obligatoires/exclus

Vous pouvez marquer un terme de recherche comme requis (les vidéos retournées DOIVENT correspondre) ou exclues (les vidéos retournées ne doivent PAS correspondre). Ceci est contrôlé avec un code URI + (%2B) ou - signe précédant immédiatement le terme.

Vous devez encoder + comme %2B lorsque vous l'utilisez pour indiquer un terme requis.

Exemple : Cette requête renvoie des vidéos qui ONT une valeur de sea mais n'ont PAS une valeur de lake dans le tags champ.

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

Voir Combiner des critères de recherche ci-dessous pour voir comment utiliser la syntaxe requise/exclue pour appliquer la logique AND pour plusieurs termes de recherche.

Combiné avec d'autres paramètres

Rechercher (à l'aide du q paramètre) peut être combiné avec d'autres paramètres tels que sort , limit et offset. Tous les paramètres d'URL sont séparés par &. L'ordre des paramètres n'a pas d'importance.

Exemples

Exemple : Cette requête renvoie des vidéos qui doivent avoir une valeur de bar dans le tag domaine et peut avoir un name contenant de la valeur foo

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

Exemple : Cette requête renvoie les mêmes vidéos que ci-dessus, mais trie également ces résultats par champ updated_at puis limite les résultats à seulement 10 vidéos.

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

Termes de recherche cités

Par défaut, une recherche fera correspondre des mots similaires avec vos termes de recherche. Si vous souhaitez faire correspondre plusieurs mots, placez simplement le terme entre guillemets.

La plupart des navigateurs et autres agents traiteront les guillemets littéraux ("..." ) correctement, mais si vous rencontrez un cas où les termes de recherche cités ne semblent pas renvoyer de résultats corrects, essayez de remplacer les guillemets par %22 (%22...%22)

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

Cela fonctionne également lors de la recherche dans un champ spécifique :

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

Plusieurs mots

Exemple : Notez que cette requête renvoie des vidéos qui ont une valeur de sea ou mammal dans le tags champ.

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

Mais, la requête suivante ne renvoie que les vidéos qui ont une balise sea,mammal.

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

Les champs personnalisés

Vous pouvez effectuer une recherche sur n'importe quel champ personnalisé que vous avez défini pour vos vidéos.

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

Remarque : toutes les valeurs des champs personnalisés sont traitées comme des chaînes. Par exemple, si vous avez un champ personnalisé de type liste qui peut prendre les valeurs true ou false , la recherche recherchera ces chaînes, pas les valeurs booléennes (dans de nombreux langages de programmation, 1 et 0 peut être utilisé de manière interchangeable avec true et false comme valeurs booléennes, mais en cherchant sur q=my_boolean_field:1 ne retournera pas les vidéos qui ont my_boolean_field mis à true).

Exemple : Cette requête renvoie des vidéos dont la valeur est animal dans le subject champ personnalisé.

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

Plages de dates

Si vous effectuez une recherche sur un champ de date, vous pouvez spécifier une date spécifique ou une plage de dates, en utilisant deux périodes pour séparer les dates de début et de fin (q=updated_at:2018-01-01..2018-02-01).

Cela recherchera toutes les vidéos avec un updated_at valeur entre le 1 août 2012 et le 8 octobre 2012. Ici, nous spécifions chaque date au format UTC.

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

Vous pouvez simplifier cette recherche en supprimant les composants de temps. Ce qui suit est équivalent à la recherche ci-dessus.

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

Formats de date pris en charge

Les formats de date pris en charge incluent UTC et relatif.

Dates relatives

Pour les dates relatives, nous prenons en charge une direction ( + ou - ) suivi d'un nombre, suivi d'une durée. Les dates relatives sont toujours mesurées à partir de l'heure actuelle. Les durées légales sont : minutes, heures, jours.

Exemples :

Gammes ouvertes

Si vous souhaitez faire correspondre toutes les dates jusqu'à une heure donnée, ou faire correspondre toutes les dates depuis une heure donnée, laissez de côté une extrémité de la plage.

Exemple : Rechercher toutes les vidéos modifiées au cours des 2 derniers jours

      q=updated_at:-2days..
      
      

Exemple : Recherchez toutes les vidéos modifiées à compter du 11 août 2013 :

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

NOW opérateur pour les dates de planification

Pour schedule.starts_at et schedule.ends_at , vous pouvez utiliser NOW comme valeur de date. Il s'agit d'un opérateur de commodité qui vous permet de configurer une requête dynamique basée sur la date-heure actuelle. Quelques exemples :

Combiner les critères de recherche

Vous pouvez combiner des critères pour des recherches complexes.

Exemple : Cette demande recherche des vidéos avec un name valeur de potins , qui ont été mis à jour entre le 1er août 2010 et le 8 octobre 2010. Il trie ensuite les données de réponse par updated_at date par ordre décroissant.

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

Combiner des termes

Utilisez le syntaxe obligatoire/exclue pour renvoyer des vidéos qui ont tous des termes spécifiés.

Par exemple, si vous effectuez une recherche sur :

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

la réponse contiendra des vidéos qui ont le tag 'bar' et peuvent également avoir foo dans le nom. Si vous souhaitez renvoyer uniquement les vidéos qui ont foo dans le nom ET la balise 'bar', vous devez rechercher sur :

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

De même, si vous souhaitez renvoyer uniquement les vidéos qui ont foo au nom, mais ne ne pas avoir la balise 'bar', vous chercheriez sur :

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

Exemples

Rechercher des vidéos spécifiques

Si vous souhaitez limiter votre recherche à un ensemble spécifique de vidéos, vous pouvez le faire en recherchant sur id:

Exemple : Cette demande renvoie des vidéos avec des identifiants 123456789 , 987654321 et 48376387

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

Recherche par état

Vous pouvez effectuer ou filtrer des recherches par état de la vidéo à l'aide du paramètre :

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

Remarques

• ^{[ 3]} La recherche de vidéos SUPPRIMÉES n'est disponible que pour les vidéos supprimées au cours des 10 derniers jours (l'heure actuelle moins 10 jours), et uniquement via CMS API(pas l'API Lecture).

Racisme

Le radicalisme est pris en charge, mais ne pas recherches partielles de mots. Par exemple, q=name:ban devrait renvoyer des vidéos avec les noms "Parking Ban Announced " ou "Parking to be Banned " ou "City Banning Parking " mais non "Bank Holiday " ou "Bandit Captured".

Espaces/Caractères spéciaux

Le gère CMS API généralement les caractères spéciaux dans les chaînes de recherche, à quelques exceptions près :

• Les espaces ne sont pas autorisés et doivent être encodés comme %20. (non codé + les signes peuvent également remplacer les espaces, mais cela peut entraîner une confusion dans vos requêtes car + peut également indiquer qu'un terme est requis. Voir syntaxe obligatoire/exclue)

  Par exemple, pour rechercher "ma vidéo préférée" dans le nom :

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

• Pour rechercher un littéral + signer ou d'utiliser le + pour indiquer que les vidéos retournées doit inclure un terme, vous devez coder le + comme %2B:

  Recherche de vidéos qui doivent contenir "two+two" dans le champ du nom

  q=name:two%2Btwo

  Recherche de vidéos qui doivent contenir "heron" dans le champ du nom

  q=%2Bname:heron

• Certains agents peuvent ne pas gérer correctement les guillemets littéraux, il est donc plus sûr d'encoder "foo" comme %22foo%22

Pour les demandes ponctuelles, vous pouvez utiliser Brightcove Learning's encodeur de chaîne pour encoder vos chaînes de recherche. Pour les applications, vous devrez trouver une fonction d'encodage URI dans la langue que vous utilisez.

Termes de recherche d'extraits

Les clips sont des vidéos créées à partir de sections d'autres vidéos. Les clips peuvent être générés par Réseau social de Brightcove , et d'autres moyens seront disponibles à l'avenir. Il existe des termes de recherche spéciaux que vous pouvez utiliser pour trouver des clips générés dans un compte :

• q=%2Bis_clip:true- ne renvoie que des clips
• q=%2Bis_clip:false- renvoie uniquement les non-clips
• q=%2Bclip_source_video_id:video_id- renvoie les clips générés à partir de la vidéo spécifiée

Mots ignorés

Certains mots sont ignorés dans les chaînes de recherche car ils sont si courants qu'ils sont susceptibles de renvoyer de nombreux résultats sans rapport avec ce que vous recherchez réellement. Vous trouverez ci-dessous une liste de mots ignorés par la recherche :

"un", "un", "et", "sont", "comme", "à", "être", "mais", "par", "pour", "si", "dans", "dans ", "est", "il", "non", "pas", "de", "sur", "ou", "tel", "que", "le", "leur", "alors", "là", "ces", "ils", "ceci", "à", "était", "sera", "avec"

Problèmes connus

• Résultats en double : dans certains cas, certains éléments des résultats de la recherche peuvent apparaître plusieurs fois.

  Solution de contournement: pour éviter les résultats de recherche en double, utilisez toujours un sort paramètre dans vos requêtes de recherche.