Travailler avec des étiquettes

Introduction

Les libellés sont similaires aux balises. Vous pouvez les ajouter à des vidéos, puis les utiliser pour rechercher un groupe de vidéos ou 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 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 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 elles. Mais si un utilisateur ajoutant une nouvelle vidéo tape accidentellement bird au lieu de birds, vous avez maintenant une nouvelle balise et la vidéo n'appartient pas à votre birds collecte.

  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 en tant que chemin hiérarchique, tel que /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 l'étiquette nature
  • q=labels:/nature/birds - renvoie le birds sous-groupe du nature vidéos
  • q=labels:/nature/birds/shore_birds - renvoie le shore_birds sous-groupe du /nature/birds vidéos

Créer et gérer 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 finaux.

Notez que tous les points de terminaison d'API indiqués ci-dessous seraient ajoutés à l'URL de base du CMS:

https://cms.api.brightcove.com

Créer une étiquette

De nouvelles étiquettes peuvent être créées en envoyant le chemin complet dans un POST demande:

Exemple de point de terminaison de demande

/v1/accounts/1234567890/labels

Exemple de corps de requête

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

Notez que tous les étiquettes dans le chemin qui n'existent pas déjà seront créées. Si vous souhaitez ajouter un autre groupe de forest_birds, vous enverriez:

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

Cette fois, seul le forest_birds sous-étiquette, sera créée, 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 tous les libellés d'un compte en envoyant un 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
}

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 demande

/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 value remplacera le dernier élément de la {path} inclus dans la demande. Donc si à la place tu voulais remplacer /birds grâce à /avian, la requête et le corps ressembleraient à ceci:

Endpoint

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

Demander un corps

{
  "new_label": "avian"
}

Après cette demande, le coastal_birds le chemin deviendrait /nature/wildlife/avian/coastal_birds. Le chemin changerait pour toutes les sous-étiquettes d'ajout dans la hiérarchie, donc /nature/birds/forest_birds deviendrait /nature/wildlife/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'étiquette:

      /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 n'affecterait pas le troisième.

Ajouter et mettre à jour des libellés 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 un demande de création de vidéo (POST) ou d’un demande de mise à jour de la vidéo (PATCH).

Pour mettre à jour les libellés des vidéos, envoyez le tableau de vidéos complet et mis à jour dans un demande de mise à jour de la 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 par labels tout comme vous pouvez le faire pour d'autres champs pris en charge pour la recherche. Comme mentionné dans l'introduction, l'ajout de sous-libellés au chemin de recherche filtre les résultats de la recherche:

Limites

• Un maximum de 10,000 libellés peut être ajouté à un compte
• La recherche par libellés est actuellement prise en charge par le Syntaxe de recherche v1 uniquement
• Les étiquettes sont ne sont pas incluses dans les métadonnées vidéo partagées avec un affilié à l'aide de Partage de médias.