assistance Contacter le support | Étatétat du système du système
Contenu de la page

    CMS/API de lecture : Vidéos Recherche v1

    Dans cette rubrique, vous apprendrez comment rechercher des vidéos dans votre compte à l'aide de l'API CMS. Le CMS API fournit un moyen programmatique de rechercher des vidéos dans votre bibliothèque Video Cloud. Cette rubrique fournit des détails sur la syntaxe de recherche. Remarque : il s'agit de la syntaxe de recherche originale - nous vous recommandons d'utiliser la syntaxe de recherche vidéo v2plus simple.

    Introduction

    Dans cette rubrique, vous apprendrez à faire ce qui suit :

    • Créer et limiter une recherche de base en utilisant le q paramètre
    • Trier les résultats de recherche
    • Recherche en utilisant les termes obligatoires et exclus
    • Utilisez une recherche entre guillemets pour faire correspondre les termes exacts et plusieurs mots
    • Rechercher dans des champs personnalisés
    • Rechercher des champs de date avec une date spécifique et des plages
    • Combiner les critères de

    Utilisation de l'API

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

    API CMS

    Lors de l'utilisation de la recherche avec l'API CMS, les éléments suivants s'appliquent :

    • Toutes les requêtes (y compris la recherche) nécessitent un en-tête d'autorisation contenant vos jetons d'accès. Pour plus d'informations sur la façon d'obtenir des informations d'identification client et de les utiliser pour récupérer des jetons d'accès, consultez la présentation OAuth de Brightcove.
    • Il n'y a pas de limite quant au nombre maximal de vidéos renvoyées à la suite d'une recherche, mais des limites de taux s'appliquent.
    • Les résultats de recherche incluent toutes les vidéos de votre compte, qu'elles soient jouables ou non, et/ou géolimitées.

    Pour plus d'informations sur la demande/réponse de l'API, consultez la section Obtenir des vidéos de la référence API CMS.

    API de lecture

    Lors de l'utilisation de la recherche avec l'API de lecture, les éléments suivants s'appliquent :

    • Les demandes de recherche avec l'API Lecture nécessitent une clé de stratégie qui est activée pour la recherche.
    • Il y a une limite au nombre maximal de vidéos renvoyées à partir d'une recherche.
    • Les résultats de la recherche ne renverront que les vidéos jouables (les vidéos avec state:inactive seront ignorées).
    • Les recherches appliquent des restrictions de stratégie de lecture, telles que l'omission des vidéos géo-restreintes des résultats.
    • La mise en cache des résultats fournit des taux de demandes plus élevés et des réponses plus rapides, et il n'y a pas de limite de taux.

    Pour plus d'informations sur la demande/réponse d'API, reportez-vous à la section Obtenir des vidéos de la référence de l'API de lecture.

    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 codée par URL de termes séparés par un espace.

    La recherche supporte le découpage. Stemming est le mappage d'un mot avec le mot racine et d'autres mots qui proviennent de la même racine. Par exemple, une recherche sur « exécuter » doit correspondre aux vidéos qui ont « running » ou « exécutées » dans le (s) champ (s) spécifié (s). Il ne correspondrait pas à « rune » car « rune » n'a pas « run » comme racine.

    Lorsque vous ne fournissez aucun qualificatif pour un terme de recherche q=bird, par exemple, la demande recherche 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 name , description , et long_description - par exemple q=text:bird)
    • tags
    • reference_id
    • custom_fields ( recherche tous les champs personnalisés)
    • custom_field_name ( recherche un champ personnalisé nommé spécifique)[1-2]

    Notes

    [ 1-1] Note : la recherche par id est incluse pour assurer la cohérence, mais une recherche sur q=id:12345 renvoie exactement les mêmes résultats que la requête https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/12345
    [ 1-2] Si vous avez un champ personnalisé de type liste et que vous souhaitez renvoyer des vidéos qui ont l'une de plusieurs valeurs, vous pouvez le faire comme ceci :

    Supposons que vous ayez un champ appelé color qui peut prendre les valeurs : red , green , yellow , ou blue. Vous souhaitez rechercher les vidéos dont le champ est défini sur la valeur green ou blue:

          q=color:green%20color:blue

    Exemple : Cette demande renvoie les vidéos dont la valeur est comprise bird dans au moins un des champs é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 q=name:bird, par exemple, la demande recherche dans le name champ vidéo une valeur de bird.

    Exemple : Cette demande renvoie les 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 les suivants :

    Champs de recherche supportés
    Champ Valeurs juridiques
    name chaînes de caractères entre guillemets ou non
    texte chaînes ou chaînes guillemets (recherche dans le name, description, et long_description)
    tags chaînes ou guillemets (plusieurs balises doivent être délimitées par des virgules)
    custom_fields chaînes ou chaînes guillemets (recherche tous les champs personnalisés - vous pouvez également utiliser un nom interne de champ personnalisé spécifique) [2-1]
    reference_id chaîne ou chaîne entre guillemets
    state ACTIVE, INACTIVE , PENDING , DELETED [2-3]
    updated_at plage de dates
    created_at plage de dates
    schedule.starts_at plage de dates
    schedule.ends_at plage de dates
    published_at plage de dates
    complete [ 2-2] true ou false

    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 format associé existe pour la vidéo, la complete 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 n'est disponible qu' à l'aide de l'API CMS ; l'API Lecture ne retournera pas les vidéos supprimées
      • Seules les vidéos supprimées au cours des 10 jours précédents (le temps actuel moins 10 jours) seront retournées

    Tri des résultats de recherche

    Le sort paramètre vous permet de trier les résultats d'une requête get pour les vidéos. Vous pouvez trier 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 grâce à l'utilisation de sort, les résultats seront triés selon un algorithme connu sous le nom Fréquence Term Frequency/Inverse Document Frequency ou TF-IDF. Voir ici pour plus d'informations.

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

    Termes obligatoires/exclus

    Vous pouvez exiger qu'un terme soit obligatoire (les vidéos trouvées DOIVENT le mentionner) ou interdit (les vidéos trouvées ne doivent PAS le mentionner). Ceci est contrôlé avec un URI encodé + (%2B) ou - signe immédiatement avant le terme.

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

    Termes requis/exclus
    Exemple encodé en URL sens
    +foo %2Bfoo les vidéos DOIVENT inclure le terme foo dans le name , description , long_description , tags , reference_id ou custom_fields
    +custom_fields:foo %2Bcustom_fields:foo vidéo DOIT inclure la valeur foo pour un champ personnalisé
    +foo -bar %2Bfoo%20-bar les vidéos DOIVENT inclure le terme foo mais ne doit PAS inclure le terme bar dans le name , description , long_description , tags , reference_id ou custom_fields
    +name:foo -name:bar %2Bname:foo%20-name:bar Les vidéos DOIVENT inclure le terme foo mais ne doivent PAS inclure le terme bar dans le name

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

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

    Reportez-vous à la section Combinaison des critères de recherche ci-dessous pour savoir comment utiliser la syntaxe requise/exclue pour appliquer la logique AND pour plusieurs termes de recherche.

    Combiné avec d'autres params

    Recherche (en utilisant le 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 les vidéos qui doivent avoir une valeur de bar dans le tag champ et peuvent avoir une valeur name contenant 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 en plus 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 trouvera des mots semblables à vos termes de recherche. Si vous voulez faire correspondre plusieurs mots, il suffit d'envelopper le terme entre guillemets.

    La plupart des navigateurs et autres agents traitent les guillemets littéraux ("...") correctement, mais si vous rencontrez un cas où les termes de recherche entre guillemets ne semblent pas renvoyer les 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"
                
              

    Mots multiples

    Exemple : Notez que cette requête renvoie des vidéos dont la valeur est 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 renvoie uniquement les vidéos qui ont une balise sea,mammal.

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

    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 de champ personnalisées 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 recherche 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 en tant que valeurs booléennes, mais la recherche q=my_boolean_field:1 sur ne renvoie pas les vidéos qui ont my_boolean_field défini sur true).

    Exemple : Cette demande renvoie des vidéos qui ont une valeur d' animal dans le champ subject 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).

    Ceci recherchera toutes les vidéos ayant une updated_at valeur comprise entre le 1er 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 abandonnant les composants temporel. 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.

    Exemples de format de date
    format (format encodé par URI) sens
    2015-08-01T 06:15:00 Z Cela représente un temps en UTC.
    2012-08-01 Cela représente minuit un jour en UTC. L'exemple est équivalent à 2012-08-01T 00:00:00 Z
    -1d L'heure actuelle moins 1 jour. (voir ci - dessous)

    Dates relatives

    Pour les dates relatives, nous supportons une direction ( + ou - ) suivie 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 :

    Exemples de date relative
    q param pour les dates C'est-à-dire
    q=updated_at ፦1jour.. MAINTENANT vidéos mises à jour de il y a 1 jour au jour courant
    q=created_at ፦2jours vidéos ajoutées il y a 2 jours
    q=updated_at ፦4heures.. MAINTENANT vidéo mise à jour de il y a 4 heures à l'heure actuelle
    q=created_at ፦60minutes.. vidéos ajoutées d'il y a 60 minutes à l'heure actuelle
    q=created_at:2016-01-01.. -1d vidéos créées à partir du 1 janvier 2015 à il y a un jour
    q=updated_at ፦14d.. MAINTENANT vidéos au cours des deux dernières semaines

    Plages ouvertes

    Si vous voulez inclure toutes les dates jusqu'à un moment donné, ou inclure toutes les dates à partir d'un moment donné, effacez la partie de la plage concernée.

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

          q=updated_at:-2days..
          
          

    Exemple : Rechercher toutes les vidéos modifiées le ou après le 11 août 2013 :

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

    NOW opérateur pour les dates du calendrier

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

    Exemples de données de planification
    de/vers params Encodé par URI C'est-à-dire
    ?q=schedule.starts_at :.. MAINTENANT ?q=schedule.starts_at :.. MAINTENANT starts_at est du début des temps à ce moment
    ?Q=schedule.starts_at:Maintenant ?Q=schedule.starts_at:Maintenant starts_at est à partir de ce moment
    ?Q=schedule.ends_at:Maintenant.. ?Q=schedule.ends_at:Maintenant.. ends_at est de ce moment à la fin du temps
    ?q=+schedule.starts_at :.. MAINTENANT +schedule.ends_at:Maintenant.. ?Q=%2BSchedule.starts_at :.. maintenant% 20% 2BSchedule.ends_at:Maintenant.. starts_at avant ce moment et ends_at après ce moment (la vidéo est prévue ce moment)

    Combiner les critères de

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

    Exemple : Cette demande recherche des vidéos ayant une name valeur de potins , qui ont été mises à 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 dans l'ordre décroissant.

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

    Combinaison de

    Utilisez la syntaxe requise/exclue pour renvoyer des vidéos qui ont tous les 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 effectuer une recherche 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 dans le nom, mais qui n'ont pas la balise 'bar', vous feriez une recherche sur :

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

    Exemples

    Échantillons Combinaison des
    Chaîne de recherche non encodée Chaîne de recherche encodée URI C'est-à-dire
    q=foo bar q=foo%20bar les articles retournés ont « foo » OU « bar »
    q=foo +bar q=foo%20%2Bbar les articles retournés doivent avoir « bar », peut avoir « foo »
    q=+foo bar q =%2Bfoo%20bar les articles retournés doivent avoir « foo », peut avoir « bar »
    q=+foo +bar q=%2Bfoo%20%2Bbar article retourné doit avoir « foo » ET « bar »
    q=-foo +bar q=-foo%20%2Bbar article retourné doit avoir « bar » ET ne pas avoir « foo »
    Recherche de plusieurs balises
    q=tags:bee,bop q=tags:bee,bop retourne les vidéos avec le tag « bee » OU « bop »
    q=tags:bee tags:bop q=tags:bee%20tags:bop retourne les vidéos avec le tag « bee » OU « bop »
    q=+tags:bee tags:bop q=%2Btags:bee%20tags:bop toutes les vidéos retournées doivent avoir le tag « bee » ; elles peuvent également avoir le tag « bop »
    q=+tags:bee +tags:bop q=%2Btags:bee%20%2Btags:bop toutes les vidéos retournées auront le tag « bee » ET le tag « bop »

    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 en fonction de l'état de la vidéo en utilisant le 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).

    Stronçage

    Le Stemming est pris en charge, mais pas les recherches partielles de mots. Par exemple, q=name:ban devrait renvoyer les vidéos avec les nomsParking Ban Announced "" ouParking to be Banned "" "City Banning Parking " mais pas "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 codés en tant que %20. ( + Les signes non encodés peuvent également remplacer les espaces, mais cela peut conduire à la confusion dans vos requêtes, car cela + peut également indiquer qu'un terme est requis. Voir syntaxe requise/exclue)

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

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

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

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

      q=name:two%2Btwo

      Recherche de vidéos qui doivent contenir "heron" dans le champ 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" en tant que %22foo%22

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

    Termes de recherche d'éléments

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

    • q=%2Bis_clip:true - Retourne uniquement les clips
    • q=%2Bis_clip:false - retourne 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 communs qu'ils sont susceptibles de renvoyer de nombreux résultats sans rapport avec ce que vous recherchez réellement. Voici une liste de mots qui sont ignorés par la recherche :

    « a », « an », « et », « sont », « comme », « à », « à », « être », « mais », « par », « pour », « si », « dans », « dans », « est », « il », « non », « de », « sur », « ou », « tel », « que », « le », « leur », « puis », « là », « ces », « ils », « ce », « à », « était », « volonté », « avec »

    Problèmes connus

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

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