assistance Contacter le support | Étatétat du système du système
Contenu de la page

    Intégrer des API

    Cette rubrique vous aidera à décider quand et comment utiliser les API d'intégration. La décision de choisir entre l'utilisation des API de configuration du lecteur et les API d'intégration est importante et le contenu de ce document vous guidera dans ces décisions.

    Pourquoi utiliser les API d'intégration ?

    Les API incorporées vous permettent de créer plusieurs instances d'un lecteur particulier. Une bonne façon de penser à cette relation joueur/instance est comme une relation parent/enfant. Le solo est le parent, et les joueurs créés avec les API incorporées sont les enfants du joueur parent. Le joueur parent possède la majeure partie des propriétés que vous souhaitez que votre joueur ait, puis vous pouvez utiliser les API incorporées pour personnaliser des sous-ensembles de propriétés sur différents joueurs enfants. Par exemple, vous pouvez charger différents médias ou utiliser différents plugins et styles avec différents joueurs enfants.

    Les diagrammes suivants aident à clarifier la fonctionnalité. En dessous le parent est montré sur la gauche, et deux enfants joueurs sur la droite. Observez que :

    • L'affiche est héritée par les deux enfants
    • La forme du bouton de lecture est héritée par l'enfant supérieur, alors qu'il est remplacé dans l'enfant inférieur
    • L'enfant supérieur ajoute une propriété, dans ce cas une superposition, que le parent n'a pas
    Enfant Adds, propriété
    Enfant Adds, propriété

    Une autre caractéristique puissante de cette relation parent/enfant est que l'héritage est en cours. Le diagramme suivant montre une nouvelle affiche affectée au parent, et les deux enfants hériteront de cette modification de configuration.

    Les enfants héritent des modifications
    Les enfants héritent des modifications

    Quand ne pas utiliser les API d'intégration

    Bien qu'il existe de bonnes raisons d'utiliser les API d'intégration si votre cas d'utilisation en a besoin, il y a aussi de bonnes raisons de rester avec les joueurs réguliers. Voici quelques-unes :

    • Les joueurs enfants ne peuvent pas être modifiés à l'aide de Video Cloud Studio. Vous ne pouvez modifier les joueurs enfants que via l'API de gestion des joueurs. Vous pouvez modifier le lecteur parent d'un lecteur enfant dans Video Cloud Studio, mais une modification apportée au lecteur parent affecte tous les joueurs enfants.
    • La publication d'un lecteur parent peut prendre beaucoup de temps si un grand nombre de joueurs enfants sont associés à ce joueur parent. Chaque joueur enfant est publié séparément, et si vous avez plus de 30 joueurs enfants, vous pouvez vous attendre à quelques retards dans la publication de votre joueur enfant. Ce serait exactement le même cas que de publier 30 joueurs réguliers en même temps.

    Compte tenu des raisons ci-dessus, il peut être logique de commencer par utiliser des joueurs réguliers, puis d'essayer des incorporations lorsque vous voyez le besoin d'enfants joueurs.

    balise vidéo

    Il y a des différences notationnelles entre les joueurs parents et enfants. Le code de lecteur intégré standard dans la page apparaît dans ce format :

        <video-js
          data-account="1507807800001"
          data-player="HiAdwRZ7kK"
          data-embed="default"
          controls=""
          data-application-id=""
          class="vjs-fluid"></video-js>

    L' data-embed attribut détermine si le joueur est parent ou enfant. Si la valeur est default, le joueur est un parent. Si le joueur est un enfant, l' data-embed attribut contiendra l'ID du joueur parent. Voici un exemple de ceci :

    L' data-embed attribut détermine si le joueur est parent ou enfant. Si la valeur est default, le joueur est un parent. Si le joueur est un enfant, l' data-embed attribut contiendra l'ID du joueur parent. Voici un exemple de ceci :

        <video-js
          data-account="1507807800001"
          data-player="HiAdwRZ7kK"
          data-embed="NURK56ZSV"
          data-application-id=""
          class="video-js" controls></video-js>

    Notez que le data-player, c'est-à-dire l'ID du joueur, est le même, mais le est data-embed passé default de l'ID du joueur enfant.

    URL du lecteur enfant

    Comment différenciez-vous le joueur parent et le joueur enfant ? Les URL seront différentes. Par exemple, l'URL d'un lecteur parent est :

        //players.brightcove.net/1507807800001/HiAdwRZ7kK_default/index.min.js

    Après avoir utilisé les API intégrées pour créer un joueur enfant, l'ID du joueur enfant a été ajouté à l'URL du parent, comme indiqué ici :

        //players.brightcove.net/1507807800001/HiAdwRZ7kK_NURK56ZSV/index.min.js

    Cas d'utilisation parent/enfant

    Supposons que vous utilisez plusieurs lecteurs vidéo. Souvent, les caractéristiques communes des joueurs sont presque les mêmes, mais dans quelques cas, vous voulez modifier le joueur pour des cas spéciaux. Vous pouvez créer plusieurs joueurs à l'aide des API de configuration du lecteur avec POST et PATCH des méthodes, mais cela pourrait entraîner des problèmes de maintenance importants. Par exemple, disons que vous vouliez changer l'affiche pour tous les joueurs. Cela signifierait utiliser PATCH sur tous les différents joueurs. Alors que si vous créez des joueurs enfants, vous n'auriez que PATCH le joueur parent, et tous les joueurs enfants auraient automatiquement la nouvelle affiche.

    Processus de création

    Si vous avez fait l' étape par étape : Gestion du lecteur vous avez vu le processus d'utilisation d'instructions curl pour communiquer les méthodes HTTP à l'API Player Management. La même approche sera utilisée ici.

    Pour créer un lecteur, vous avez probablement utilisé quelques méthodes HTTP avec les API de configuration du lecteur, telles que :

    • Créer le lecteur à l'aide d'un POST à https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players
    • Mettre à jour le lecteur à l'aide d'un PATCH à https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/configuration
    • Publier le lecteur mis à jour à l'aide d'un POST à https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/publish

    Une approche similaire sera utilisée pour les joueurs enfants utilisant les API d'intégration. À un niveau très élevé, vous pourrez :

    • Créez un joueur enfant à l'aide d'un POST à https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/incorpore. Remarque : Les joueurs enfants créés avec les API incorporées s'auto-publient lors de la création, il n'est donc pas nécessaire de publier sur la création d'un joueur enfant, uniquement lors de la mise à jour du joueur enfant.
    • Mettre à jour le lecteur enfant PATCH à l'aide d'un à https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/embeds/$embed_id/configuration
    • Publier le lecteur enfant à l'aide d'un POST à https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/embeds/$embed_id/Publish

    Le contenu suivant décrit le processus en détail.

    Créer un joueur enfant

    Pour créer un joueur enfant, vous utilisez une POST méthode HTTP, comme indiqué ici :

        curl /
        --header "Content-Type: application/json" /
        --user $EMAIL /
        --request POST /
        --data '{
        "media": {
        "sources": [
          {
            "src":"http://solutions.brightcove.com/bcls/assets/videos/BirdsOfAFeather.mp4",
            "type":"video/mp4"
          }
        ],
        "poster": {
          "highres":"http://solutions.brightcove.com/bcls/assets/images/BirdsOfAFeather.jpg"
        }
        }
          }' /
        https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/embeds

    Voici un exemple de réponse à la création du joueur enfant :

        {
            "id": "be864624-8d85-4dfc-8fe6-4e9dd4c70417",
            "url": "http://players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c_be864624-8d85-4dfc-8fe6-4e9dd4c70417/index.html",
            "embed_code": "<iframe src='//players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c_be864624-8d85-4dfc-8fe6-4e9dd4c70417/index.html' allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>",
            "embed_in_page": "http://players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c_be864624-8d85-4dfc-8fe6-4e9dd4c70417/in_page.embed",
            "preview_url": "http://preview-players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c/be864624-8d85-4dfc-8fe6-4e9dd4c70417/index.html",
            "preview_embed_code": "<iframe src='//preview-players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c/be864624-8d85-4dfc-8fe6-4e9dd4c70417/index.html' allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>"
        }

    Remarque : Le joueur enfant publie lui-même lors de la création, il n'est donc pas nécessaire de publier le joueur enfant après la création. Vous devez toujours publier lecteur enfant s'il est modifié avec une PATCH méthode. À ce stade, les informations d'aperçu ne sont pas utiles car vous pouvez utiliser le lecteur enfant publié immédiatement après sa création.

    Vous pouvez maintenant utiliser la url propriété du joueur enfant pour voir les résultats. Dans l'exemple ci-dessous, le joueur enfant a été ajouté au joueur parent créé dans l'étape par étape : Gestion des joueurs. Vous voyez la nouvelle affiche et la vidéo, mais le plugin de superposition du lecteur parent est toujours présent.

    Joueur enfant avec superposition des parents
    Joueur enfant avec superposition des parents

    Mettre à jour le joueur enfant

    Pour mettre à jour le lecteur enfant, vous utilisez une PATCH méthode HTTP. L'instruction curl suivante met à jour la poster propriété. Il est supposé que vous avez défini la variable d' $EMBED_ID environnement de manière appropriée :

        curl
        --header "Content-Type: application/json"
        --user $EMAIL
        --request PATCH
        --data '{
        "media": {
        "poster": {
          "highres":"http://solutions.brightcove.com/bcls/assets/images/Water-Splashing.jpg"
        }
        }
          }'
        https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/embeds/$EMBED_ID/configuration
        

    La réponse fournit des informations d'aperçu pour un preview_url et preview_embed_code code:

        {
            "preview_url": "http://preview-players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c/be864624-8d85-4dfc-8fe6-4e9dd4c70417/index.html",
            "preview_embed_code": "<iframe src='//preview-players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c/be864624-8d85-4dfc-8fe6-4e9dd4c70417/index.html' allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>"
        }

    Publier un joueur enfant

    Une fois que le joueur enfant est modifié, vous devrez le publier. Assurez-vous que la variable d' $EMBED_ID environnement est définie et que vous pouvez ensuite publier le lecteur enfant nouvellement modifié :

        curl
        --header "Content-Type: application/json"
        --user $EMAIL
        --request POST
        https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/embeds/$EMBED_ID/publish

    La réponse fournit les informations essentielles nécessaires pour utiliser le joueur enfant, tout comme la publication d'un joueur fait :

        {
            "id": "be864624-8d85-4dfc-8fe6-4e9dd4c70417",
            "url": "http://players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c_be864624-8d85-4dfc-8fe6-4e9dd4c70417/index.html",
            "embed_code": "<iframe src='//players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c_be864624-8d85-4dfc-8fe6-4e9dd4c70417/index.html' allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>",
            "embed_in_page": "http://players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c_be864624-8d85-4dfc-8fe6-4e9dd4c70417/in_page.embed"
        }

    Afficher les informations enfant

    Vous pouvez utiliser la GET méthode HTTP pour récupérer les informations sur un lecteur enfant. Un exemple d'instruction curl est :

        curl
          --header "Content-Type: application/json"
          --user $EMAIL
          --request GET
          https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/embeds

    Une assez grande quantité de données JSON est renvoyée.

    Supprimer les joueurs enfants

    Vous pouvez également supprimer un joueur enfant à l'aide de la DELETE méthode. Voici un exemple d'instruction curl pour supprimer un joueur enfant :

        curl
        --header "Content-Type: application/json"
        --user $EMAIL
        --request DELETE
        https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/embeds/$EMBED_ID

    Bien sûr, cela n'affectera que le joueur enfant et non le joueur parent.