Introduction
Les étiquettes sont similaires aux balises. Vous pouvez les ajouter à des vidéos, puis les utiliser pour rechercher un groupe de vidéos ou elles présentent des avantages distincts :
-
Les étiquettes sont créées au niveau du compte et appliquées aux vidéos.
Ceci est particulièrement important si votre objectif est d'organiser votre vidéothèque. Par exemple, si vous essayez d'organiser vos vidéos à l'aide de balises, vous pouvez créer des balises telles que
birds
,fish
, etinsects
. Ensuite, il est facile de rechercher et de trouver toutes vos vidéos d'oiseaux et de créer une playlist intelligente pour elles. Mais si un utilisateur ajoute une nouvelle vidéo accidentellement tapebird
au lieu debirds
, vous avez maintenant une nouvelle balise, et la vidéo n'appartient pas à votrebirds
collection.Si vous créez une étiquette appelée à la
birds
place, seule cette étiquette peut être ajoutée à une vidéo. Vous ne pouvez pas ajouter accidentellement l'étiquette inexistante à labirds
place. -
Les étiquettes sont créées en tant que chemin hiérarchique, par exemple
/nature/birds/shore_birds
.Cela signifie que vous pouvez rechercher (ou créer une liste de lecture basée) sur un chemin partiel ou complet :
q=labels:/nature
- retourne toutes les vidéos qui ont le labelnature
q=labels:/nature/birds
- retourne lebirds
sous-groupe desnature
vidéosq=labels:/nature/birds/shore_birds
- retourne leshore_birds
sous-groupe des/nature/birds
vidéos
Création et gestion d'étiquettes
Les libellés de votre compte peuvent être créés et gérés à l'aide du CMS API /v1/accounts/{account_id}/labels
points de terminaison.
Notez que tous les points de terminaison de l'API indiqués ci-dessous seraient ajoutés à l'URL de base du CMS :
https://cms.api.brightcove.com
Création d'une étiquette
De nouvelles étiquettes peuvent être créées en envoyant le chemin complet dans une POST
requête :
Exemple de point de terminaison de demande
/v1/accounts/1234567890/labels
Corps de demande d'échantillon
{
"path": "/nature/birds/shore_birds/"
}
Notez que toutes les étiquettes du chemin d'accès qui n'existent pas encore seront créées. Si vous voulez ajouter un autre groupe de forest_birds
, vous enverrez :
{
"path": "/nature/birds/forest_birds/"
}
Cette fois, seul le forest_birds
sous-label, sera créé, depuis nature
et existe birds
déjà.
De même, si vous souhaitez ajouter un nouveau sous-groupe sandpipers
à shore_birds
, vous enverrez :
{
"path": "/nature/birds/shore_birds/sandpipers"
}
Exemple de réponse
{
"path": "/nature/birds/shore_birds/sandpipers/"
}
Obtenir des étiquettes
Vous pouvez obtenir toutes les étiquettes d'un compte en envoyant une GET
demande :
Exemple de point de terminaison de demande
/v1/accounts/1234567890/labels
Exemple de réponse
{
"account_id": "57838016001",
"labels": [
"/nature/birds/",
"/nature/birds/shore_birds/",
"/nature/birds/forest_birds/",
"/nature/mammals/seamammals/"
],
"version": 4
}
Mise à jour d'une étiquette
Pour mettre à jour une étiquette, vous envoyez une PATCH
demande à :
/v1/accounts/{account_id}/labels/by_path/{path}
Exemple de point de terminaison de demande
/v1/accounts/1234567890/labels/by_path//nature/birds/shore_birds
Corps de demande d'échantillon
{
"new_label": "coastal_birds"
}
Notez que la new_label
valeur remplacera le dernier élément de l' {path}
inclus dans la requête. Donc, si au lieu de cela vous /birds
vouliez remplacer par /avian
, la requête et le corps ressembleraient à ceci :
Point de terminaison
/v1/accounts/1234567890/labels/by_path//nature/birds/
Corps de la requête
{
"new_label": "avian"
}
Après cette demande, le coastal_birds
chemin deviendrait /nature/wildlife/avian/coastal_birds
. Le chemin changerait pour toutes les sous-étiquettes additionnées dans la hiérarchie, donc /nature/birds/forest_birds
deviendrait /nature/wildlife/avian/forest_birds
La réponse inclura le nombre d'étiquettes mises à jour.
Exemple de réponse
{
"path": "/nature/avian",
"labels_updated": "2"
}
Supprimer une étiquette
La suppression d'une étiquette utilise une DELETE
demande envoyée au même point de terminaison que la demande de mise à jour. Seul le chemin se terminant par cette sous-étiquette (et les chemins comportant des sous-étiquettes supplémentaires) seront supprimés, tandis que les étiquettes de niveau supérieur sont conservées.
Par exemple, disons que vous avez ces trois chemins d'étiquettes :
/nature/wildlife/avian/coastal_birds
/nature/wildlife/avian/coastal_birds/sandpipers
/nature/wildlife/avian/forest_birds
L'envoi d'une DELETE
requête à /v1/accounts/1234567890/labels/by_path//nature/wildlife/avian/coastal_birds
supprimerait les premiers chemins ci-dessus, mais cela n'affecterait pas le troisième.
Ajout et mise à jour d'étiquettes aux vidéos
Ajoutez des étiquettes aux vidéos sous la forme d'un tableau de chemins d'étiquettes complets :
[
"/nature/wildlife/avian/coastal_birds",
"/nature/wildlife/avian/coastal_birds/sandpipers"
]
Le tableau d'étiquettes peut être inclus dans une demande de création vidéo (POST) ou une demande de mise à jour vidéo (PATCH).
Pour mettre à jour les étiquettes vidéo, envoyez le tableau de vidéos complet mis à jour dans une demande de mise à jour vidéo (PATCH). Ainsi, par exemple, pour ajouter le /nature/wildlife/avian/forest_birds
, vous enverriez le tableau :
[
"/nature/wildlife/avian/coastal_birds",
"/nature/wildlife/avian/coastal_birds/sandpipers",
"/nature/wildlife/avian/forest_birds"
]
Recherche de vidéos par étiquettes
Vous pouvez rechercher des vidéos labels
tout comme vous le pouvez par d'autres champs pris en charge pour la recherche. Comme mentionné dans l'introduction, l'ajout de sous-étiquettes au chemin de recherche filtre les résultats de recherche :
Exemple de recherche | Ce qu'il retourne |
---|---|
q=labels:/nature |
Toutes les vidéos avec label paths commençant par /nature |
q=labels:/nature/wildlife |
Toutes les vidéos avec label paths commençant par /nature/wildlife |
q=labels:/nature/wildlife/avian |
Toutes les vidéos avec label paths commençant par /nature/wildlife/avian |
Contraintes
- Un maximum de 10 000 étiquettes peuvent être ajoutées à un compte
- La recherche par étiquettes est actuellement prise en charge par la syntaxe de recherche v1 uniquement
- Les étiquettes ne sont pas incluses dans les métadonnées vidéo partagées avec un affilié à l'aide du partage de médias.