Paper Contacter le support | état du système L'état du système
Contenu de la page

    CMS /Playback API: Recherche de vidéos v1

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

    Introduction

    Dans cette rubrique, vous allez apprendre à faire ce qui suit:

    • Créer et limiter une recherche de base en utilisant le q paramètre
    • Trier les résultats de la recherche
    • Rechercher en utilisant les termes requis et exclus
    • Utilisez une recherche citée pour faire correspondre des termes exacts et des mots multiples
    • Rechercher dans les 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 le CMS API ou le Playback API.

    CMS API

    Lorsque vous utilisez la recherche avec le CMS API, les règles suivantes 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 d'informations sur l'obtention des informations d'identification des clients et leur utilisation pour récupérer les jetons d'accès, voir Présentation de Brightcove OAuth.
    • Le nombre maximal de vidéos renvoyées à partir d'une recherche n'est pas limité, mais la limitation de débit 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éolocalisées.

    Pour les détails de demande / réponse d'API, consultez la Obtenez des vidéos l'article de l' CMS API Référence.

    Playback API

    Lorsque vous utilisez la recherche avec le Playback API, les règles suivantes s'appliquent:

    • Rechercher des demandes avec le Playback API exiger une clé de politique qui est activé pour la recherche.
    • Il y a un limite sur le nombre maximum de vidéos renvoyées à partir d'une recherche.
    • Les résultats de la recherche ne renverront que les vidéos jouables (vidéos avec state:inactive sera ignoré).
    • Les recherches appliquent des restrictions de stratégie de lecture, telles que l'omission de vidéos géolocalisées dans les 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 limitation de débit.

    Pour les détails de demande / réponse d'API, consultez la Obtenez des vidéos l'article de l' Playback API Référence.

    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 en URL, séparés par un espace.

    Rechercher des soutiens découlant. Stemming est la cartographie d'un mot au mot racine et d'autres mots qui proviennent de la même racine. Par exemple, une recherche sur "run" devrait correspondre à des vidéos qui ont "couru" ou "couru" dans le (s) champ (s) spécifié (s). Ce serait ne sont pas correspond à "rune" parce que "run" 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 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] Remarque: la recherche par identifiant est incluse pour la cohérence, mais une recherche sur q=id:12345 retournera exactement les mêmes résultats que la demande 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 contenant l'une des valeurs suivantes, procédez comme suit:

    Disons que vous avez un champ appelé color cela peut prendre les valeurs: red, green, yellowou blue. Vous souhaitez rechercher des vidéos dont le champ est défini sur la valeur green or blue:

          q=color:green%20color:blue

    Exemple: Cette requête renvoie des vidéos ayant une valeur de 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 qualificateur pour un terme de recherche, tel que q=name:bird, la requête va chercher la vidéo name champ pour une valeur de bird.

    Exemple: Cette requête renvoie des vidéos ayant une valeur de wildlife de 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 pris en charge
    Champ Valeurs légales
    name chaînes ou chaînes de caractères
    texte chaînes ou chaînes entre guillemets (recherche dans name, description long_description)
    tags chaînes ou chaînes entre guillemets (plusieurs balises doivent être délimitées par des virgules)
    custom_fields chaînes ou guillemets (recherche tous les champs personnalisés - vous pouvez également utiliser un champ personnalisé spécifique interne prénom) [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 or false

    Notes

    • [2-1] De plus, il est ne sont pas possible de rechercher des vidéos qui ont un champ personnalisé qui n'a pas de valeur ou une valeur de null, car à moins que le champ n'ait reçu une valeur, il n'est pas du tout inclus dans les métadonnées vidéo.
    • [2-2] lorsque vous créez une nouvelle vidéo, le complete la propriété est automatiquement définie sur false. Dès qu'une interprétation 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 uniquement. disponible en utilisant le CMS API; la Playback API seront ne sont pas retourner des vidéos supprimées
      • Seulement les vidéos supprimées au cours des jours 10 précédents (l'heure actuelle moins 10 jours) seront retournées

    Tri des résultats de recherche

    La sort Ce paramètre vous permet de trier les résultats d’une requête 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 le tri n’est pas explicite par le biais de l'utilisation de sort, les résultats seront triés selon un algorithme appelé Fréquence de terme / Fréquence de document inverse ou TF-IDF. Voir ici pour plus d’informations.

    Par exemple, disons que vous cherchez sur les termes coastal,city et il y a des vidéos 120 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, en accordant une plus grande importance au terme qui apparaît le plus fréquemment dans votre vidéothèque dans son ensemble.

    Termes requis / exclus

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

    Vous devez encoder + as %2B lors de son utilisation pour indiquer un terme requis.

    Conditions requises / exclues
    exemple codé en url sens
    +foo %2Bfoo les vidéos DOIVENT inclure le terme foo de name, description, long_description, tags, reference_id or custom_fields
    +custom_fields:foo %2Bcustom_fields:foo la 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 de name, description, long_description, tags, reference_id or custom_fields
    +name:foo -name:bar %2Bname:foo%20-name:bar les vidéos DOIVENT inclure le terme foo mais ne doit PAS inclure le terme bar de name

    Exemple: cette demande renvoie des vidéos qui ont une valeur de sea mais ne pas avoir une valeur de lake de tags champ.

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

    découvrir Combinaison de critères de recherche ci-dessous pour voir comment utiliser la syntaxe requise / exclue pour appliquer ET logique pour plusieurs termes de recherche.

    Combiné avec d'autres paramètres

    Recherche (en utilisant le q paramètre) peut être combiné à d’autres paramètres tels que sort, limit pour 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 demande renvoie des vidéos qui doivent avoir une valeur de bar de tag terrain et peut avoir un name contenant la valeur foo

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

    Exemple: cette demande renvoie les mêmes vidéos que ci-dessus, mais trie également ces résultats par champ. updated_at et limite ensuite les résultats aux vidéos 10 uniquement.

          .../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 à vos termes de recherche. Si vous voulez faire correspondre plusieurs mots, mettez simplement le terme entre guillemets.

    La plupart des navigateurs et d’autres agents traitent les guillemets littéraux ("...") correctement, mais si vous rencontrez un cas où les termes de recherche entre guillemets ne semblent pas donner des 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 sur 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 or mammal de 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 un tag. 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 de champs personnalisés sont traitées comme des chaînes. Par exemple, si vous avez un champ personnalisé de type liste pouvant prendre les valeurs true or false, la recherche cherchera ces chaînes, pas les valeurs booléennes (dans de nombreux langages de programmation, 1 pour 0 peut être utilisé indifféremment avec true pour false comme valeurs booléennes, mais en recherchant q=my_boolean_field:1 ne retournera pas les vidéos qui ont my_boolean_field ajuster à true).

    Exemple: Cette requête renvoie des vidéos ayant une valeur de animal de subject champ personnalisé.

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

    Plages de dates

    Si vous recherchez 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 va rechercher toutes les vidéos avec un updated_at valeur entre août 1, 2012 et Octobre 8, 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.

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

    Dates relatives

    Pour les dates relatives, nous soutenons une direction ( + or -) 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 les suivantes: minutes, heures, jours.

    Exemples:

    Échantillons de date relative
    q param pour les dates Sens
    q = updated_at: -1day..NOW vidéos mises à jour de 1 jour à jour
    q = created_at: -2days vidéos ajoutées il y a 2 jours
    q = updated_at: -4hours..NOW vidéo mise à jour de 4 heures à l'heure actuelle
    q = created_at: -60minutes .. vidéos ajoutées depuis 60 minutes à l'heure actuelle
    q = created_at: 2016-01-01 ..- 1d vidéos créées de janvier 1, 2015 à il y a un jour
    q = updated_at: -14d..NOW vidéos au cours des deux dernières semaines

    Plages ouvertes

    Si vous voulez faire correspondre toutes les dates jusqu'à une heure donnée, ou faire correspondre toutes les dates depuis un moment donné, laissez une extrémité de la plage.

    Exemple: Rechercher toutes les vidéos modifiées dans les derniers jours 2

          q=updated_at:-2days..
          
          

    Exemple: Recherche de toutes les vidéos modifiées à partir de août 11, 2013:

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

    NOW opérateur pour les dates d'horaire

    Pour le schedule.starts_at pour schedule.ends_at, Vous pouvez utiliser NOW comme une valeur de date. Il s'agit d'un opérateur pratique qui vous permet de configurer une requête dynamique en fonction de la date et de l'heure actuelles. Quelques exemples:

    Exemples de données de planification
    de / vers les params URI codé Sens
    ? q = schedule.starts_at: .. MAINTENANT ? q = schedule.starts_at: .. MAINTENANT starts_at est depuis le début du temps jusqu'à ce moment
    ? q = schedule.starts_at: NOW ? q = schedule.starts_at: NOW starts_at est à partir de ce moment
    ? q = schedule.ends_at: MAINTENANT .. ? q = schedule.ends_at: MAINTENANT .. ends_at est à partir de ce moment jusqu'à la fin des temps
    ? q = + schedule.starts_at: .. NOW + schedule.ends_at: NOW .. ? q =% 2Bschedule.starts_at: .. MAINTENANT% 20% 2Bschedule.ends_at: NOW .. starts_at avant ce moment et se termine_at après ce moment (la vidéo est programmée pour ce moment)

    Combiner les critères de recherche

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

    Exemple: Cette requête recherche des vidéos avec un name valeur de potins, qui ont été mis à jour entre Août 1, 2010 et Octobre 8, 2010. Il trie ensuite les données de réponse en 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 termes

    Utilisez le syntaxe requise / exclue pour retourner 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 peut aussi avoir foo dans le nom. Si vous souhaitez renvoyer uniquement les vidéos qui ont foo dans le nom ET le tag '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 fais ne sont pas avoir le tag 'barre', vous chercherez sur:

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

    Exemples

    Échantillons: combinaison des termes
    Chaîne de recherche non codée Chaîne de recherche codée par URI Sens
    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", peuvent avoir "foo"
    q=+foo bar q =%2Bfoo%20bar les articles retournés doivent avoir "foo", peuvent 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"
    Recherches de tags multiples
    q=tags:bee,bop q=tags:bee,bop renvoie des vidéos avec le tag "abeille" OU "bop"
    q=tags:bee tags:bop q=tags:bee%20tags:bop renvoie des vidéos avec le tag "abeille" OU "bop"
    q=+tags:bee tags:bop q=%2Btags:bee%20tags:bop toutes les vidéos renvoyées doivent porter la balise "bee"; ils peuvent aussi avoir la balise "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 effectuant une recherche sur id:

    Exemple: cette demande renvoie des vidéos avec des identifiants. 123456789, 987654321 pour 48376387

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

    Recherche par état

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

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

    Notes

    • La recherche de vidéos SUPPRIMÉES n’est disponible que pour les vidéos supprimées au cours des derniers jours 10 (heure actuelle moins les jours 10), et uniquement par le biais du menu déroulant. CMS API (pas le Playback API).

    Stemming

    L'étalement est supporté, mais ne sont pas recherches partielles de mots. Par exemple, q=name:ban devrait retourner 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

    La CMS API gère 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 comme suit: %20. (Non codé + Les panneaux peuvent également remplacer les espaces, mais cela peut entraîner une confusion dans vos requêtes. + 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 littéral + signer ou utiliser le + pour indiquer que les vidéos renvoyées doivent inclure un terme, vous devez encoder le + as %2B:

      Rechercher des vidéos qui doivent contenir "two+two" dans le champ du nom

      q=name:two%2Btwo

      Rechercher des 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 de les encoder "foo" as %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 devez trouver une fonction d'encodage URI dans la langue que vous utilisez.

    Termes de recherche de clip

    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éseaux sociaux Brightcoveet d'autres moyens seront disponibles dans le futur. Il existe des termes de recherche spéciaux que vous pouvez utiliser pour rechercher des clips générés dans un compte:

    • q=%2Bis_clip:true - renvoie uniquement les 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 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", "and", "are", "as", "à", "être", "mais", "par", "pour", "si", "dans", "dans" "," est "," il "," non "," non "," de "," sur "," ou "," tel "," que "," le "," leur "," alors ", "là", "ces", "ils", "ceci", "à", "était", "va", "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: pour éviter les résultats de recherche en double, utilisez toujours un sort paramètre dans vos demandes de recherche.


    Dernière mise à jour de la page le 24 oct.2020