Travailler avec des étiquettes

Introduction

Les étiquettes sont similaires aux balises. Vous pouvez les ajouter à des vidéos, puis les utiliser pour rechercher un groupe de vidéos, mais elles présentent des avantages distincts :

Les libellés sont créés au niveau du compte et appliqués aux vidéos.
Ceci est particulièrement important si votre objectif est d'organiser votre bibliothèque de vidéos. Par exemple, si vous essayez d'organiser vos vidéos à l'aide de balises, vous pouvez créer des balises telles que birds , fish , et insects. Ensuite, il est facile de rechercher et de trouver toutes vos vidéos d'oiseaux et de créer une liste de lecture intelligente pour eux. Mais si un utilisateur qui ajoute une nouvelle vidéo tape accidentellement bird à la place de birds , vous avez maintenant un nouveau tag et la vidéo n'appartient pas à votre birds collection.

Si vous créez une étiquette appelée birds à la place, seule cette étiquette peut être ajoutée à une vidéo. Vous ne pouvez pas ajouter accidentellement l'étiquette inexistante birds au lieu.
Les étiquettes sont créées sous forme de chemin hiérarchique, comme /nature/birds/shore_birds.
Cela signifie que vous pouvez rechercher (ou créer une playlist basée sur) un chemin partiel ou complet :
- q=labels:/nature- renvoie toutes les vidéos qui ont le label nature
- q=labels:/nature/birds- renvoie le birds sous-groupe de la nature vidéos
- q=labels:/nature/birds/shore_birds- renvoie le shore_birds sous-groupe de la /nature/birds vidéos

Création et gestion des é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 d'API indiqués ci-dessous seront 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 un POST demander:

Exemple de point de terminaison de requête

/v1/accounts/1234567890/labels

Exemple de corps de requête

{
  "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 souhaitez ajouter un autre groupe de forest_birds , vous enverriez :

{
  "path": "/nature/birds/forest_birds/"
}

Cette fois, seuls les forest_birds sous-étiquette, sera créé, car nature et birds existe déjà.

De même, si vous souhaitez ajouter un nouveau sous-groupe sandpipers à shore_birds , vous enverriez :

{
  "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 un GET demander:

Exemple de point de terminaison de requête

/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
}

Mettre à jour une étiquette

Pour mettre à jour une étiquette, vous envoyez un PATCH demande à:

/v1/accounts/{account_id}/labels/by_path/{path}

Exemple de point de terminaison de requête

/v1/accounts/1234567890/labels/by_path//nature/birds/shore_birds

Exemple de corps de requête

{
  "new_label": "coastal_birds"
}

Notez que le new_label valeur remplacera le dernier élément dans le {path} inclus dans la demande. Donc si à la place vous vouliez remplacer /birds avec /avian , la requête et le corps ressembleraient à ceci :

Point de terminaison

/v1/accounts/1234567890/labels/by_path//nature/birds/

Corps de la demande

{
  "new_label": "avian"
}

Après cette demande, le coastal_birds chemin deviendrait /nature/avian/coastal_birds. Le chemin changerait pour tout ajout de sous-étiquettes dans la hiérarchie, donc /nature/birds/forest_birds deviendrait /nature/avian/forest_birds

La réponse inclura le nombre d'étiquettes qui ont été mises à jour.

Exemple de réponse

{
  "path": "/nature/avian",
  "labels_updated": "2"
}

Supprimer une étiquette

La suppression d'une étiquette utilise un 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 qui ont des sous-étiquettes supplémentaires) seront supprimés, tandis que les étiquettes de niveau supérieur sont conservées.

Par exemple, supposons que vous ayez ces trois chemins d'étiquettes :


      /nature/wildlife/avian/coastal_birds
      /nature/wildlife/avian/coastal_birds/sandpipers
      /nature/wildlife/avian/forest_birds

Envoi d'un DELETE demande à /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.

Ajouter et mettre à jour des étiquettes aux vidéos

Ajoutez des libellés aux vidéos sous la forme d'un tableau de chemins de libellés complets :

[
      "/nature/wildlife/avian/coastal_birds",
      "/nature/wildlife/avian/coastal_birds/sandpipers"
]

Le tableau d'étiquettes peut être inclus dans un demande de création de vidéo (POST) ou un demande de mise à jour vidéo (PATCH).

Pour mettre à jour les étiquettes vidéo, envoyez le tableau de vidéos complet et mis à jour dans un 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 libellés

Vous pouvez rechercher des vidéos en labels tout comme vous pouvez le faire avec 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 la recherche :

Recherche par exemples d'étiquettes
Exemple de recherche	Ce que ça renvoie
`q=labels:/nature`	Toutes les vidéos avec des chemins d'étiquette commençant par `/nature`
`q=labels:/nature/wildlife`	Toutes les vidéos avec des chemins d'étiquette commençant par `/nature/wildlife`
`q=labels:/nature/wildlife/avian`	Toutes les vidéos avec des chemins d'étiquette commençant par `/nature/wildlife/avian`

Contraintes

Un maximum de 10 000 étiquettes peut être ajouté à un compte
Les étiquettes ne peuvent être gérées qu'à l'aide de l'API. Il n'y a actuellement aucune option dans l'interface utilisateur
La recherche par libellés est actuellement prise en charge par le Syntaxe de recherche v1 uniquement
Les étiquettes sont ne pas inclus dans les métadonnées vidéo qui sont partagées avec un affilié à l'aide Partage médiatique.