Utilisation 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 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 , et insects. 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 tape bird au lieu de birds , vous avez maintenant une nouvelle balise, et la vidéo n'appartient pas à votre birds 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 à la birds 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 label nature
  • q=labels:/nature/birds - retourne le birds sous-groupe des nature vidéos
  • q=labels:/nature/birds/shore_birds - retourne le shore_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 :

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.