Utiliser Postman pour les demandes d'API

Installer Postman

Obtenir Postman de postman.com. Il existe une version en ligne que vous pouvez utiliser, mais nous vous recommandons d'installer l'application de bureau.

Obtenir les informations d'identification du client

Pour travailler avec les API Brightcove, vous aurez besoin des informations d'identification client pour le compte et les API que vous souhaitez utiliser. Obtenez vos informations d'identification client dans Studio en suivant les instructions dans Gestion des informations d'authentification API. Dans les étapes ci-dessous, nous effectuerons des demandes d'API CMS en utilisant Postman , vos informations d'identification doivent donc avoir au moins les autorisations suivantes:

• Video: Read/Write

Vous pouvez ajouter autant d'autorisations supplémentaires que vous le souhaitez pour obtenir des informations d'identification qui seront utilisables pour un plus large éventail de demandes d'API. Notez également que vous obtenez des informations d'identification qui fonctionneront pour plusieurs comptes si vous le souhaitez.

Vous pouvez utiliser cette application en ligne si tu préfères. Si vous le faites, vous devez spécifier au moins video-cloud/video/all autorisations.

Obtenez la spécification OpenAPI

Bien que cela ne soit pas obligatoire, vous pouvez grandement simplifier la configuration de Postman consiste à importer la spécification OpenAPI de l'API que vous souhaitez utiliser. Vous pouvez le faire pour n'importe quelle API de la plate-forme Brightcove, mais pour ce didacticiel, nous utiliserons l'API CMS.

Pour obtenir la spécification OpenAPI, accédez simplement à la Référence de l'API CMS et cliquez sur le Télécharger bouton:

Le fichier téléchargé sera appelé openapi.yaml

Importer la spécification OpenAPI

L'étape suivante consiste à lancer l'application Postman, puis à importer la spécification OpenAPI que vous avez téléchargée :

Ouvrir la collection

Lorsque l'API est importée, Postman génère une série de demandes.

1. Cliquez sur Collections.
2. Sélectionnez la nouvelle collection CMS API :
3. Développez la collection et cliquez sur le vidéos dossier et sélectionnez le Obtenir des vidéos demander.

   

   

Notez que Postman a configuré pour vous la plupart des détails à partir de la référence de l'API, y compris la demande elle-même et les paramètres qui peuvent y être ajoutés. Il fournit également la documentation relative aux paramètres, vous permet de modifier les valeurs et de décocher celles que vous ne souhaitez pas envoyer avec la demande.

Cependant, vous devrez toujours fournir certaines informations personnelles, notamment l'identifiant du compte et les informations d'authentification. Vous pouvez le faire demande par demande, mais le meilleur moyen est de créer un environnement pour la demande, où vous pouvez stocker les informations couramment utilisées sous forme de variables. Nous le ferons dans la section suivante.

Créer un environnement

Les étapes ci-dessous vous guideront dans la configuration d'un environnement pour les demandes d'API CMS

1. Cliquez sur l'icône Aperçu rapide de l'environnement , puis sur Ajouter:

   

2. Modifiez le nom de l'environnement en le remplaçant par " Brightcove APIs " (vous pourrez utiliser cet environnement pour d'autres API de Brightcove, en y ajoutant de nouvelles variables si nécessaire).

   

3. Cliquez sur le texte "Ajouter une nouvelle variable", saisissez account_id , puis cliquez dans le VALEUR INITIALE et entrez votre identifiant de compte Video Cloud (puis faites de même pour CURRENT VALUE) :

   

4. Répétez l'étape précédente pour ajouter des variables supplémentaires :

   Variables d'environnement

   Variable	Valeur initiale
   client_id	(votre identifiant client - voir Obtenir les informations d'identification du client dessus)
   client_secret	(votre secret client - voir Obtenir les informations d'identification du client dessus)
   access_token_url	https://oauth.brightcove.com/v4/access_token

5. Cliquez sur sauvegarder pour sauver l'environnement :

   

6. Revenez à votre collection d'API Brightcove CMS et sélectionnez l'environnement que vous avez créé à partir du sélecteur d'environnement :

   

Les variables d'environnement peuvent être référencées en les entourant de doubles accolades - exemple: {{client_id}}. Postman vous aide avec la saisie semi-automatique lorsque vous tapez "{{...". Vous pouvez essayer ceci en retournant à la Obtenir des vidéos demande et commencez à taper "{{a" dans le Valeur champ pour la variable de chemin account_id:

Activer les demandes

Maintenant que vous avez configuré l'environnement, vous pouvez utiliser les variables pour tester les requêtes. Nous examinerons d'abord la demande d'obtention de vidéos.

1. Si vous ne l'avez pas déjà fait, saisissez {{account_id}} comme valeur de account_id Variable de chemin.
2. Clique le Autorisation onglet pour la demande :

   

3. Sous Options de configuration , changer la Type de subvention à Client-Identifiants:

   

4. Saisissez les variables suivantes de votre environnement dans les champs appropriés :
   • URL du jeton d'accès : {{access_token_url}}
   • Identité du client: {{client_id}}
   • Secret client : {{client_secret}}
5. Cliquez sur Obtenir un nouveau jeton d'accès:

   

6. Une fois l'autorisation terminée, vous pouvez cliquer sur Procéder ou attendez que le jeton apparaisse. Puis clique Utiliser le jeton:

   

Notez que les jetons d'accès Brightcove expirent au bout de cinq minutes. Selon ce que vous faites et à quelle vitesse, vous pourrez peut-être utiliser le même jeton d'accès plusieurs fois. À son expiration, l'API CMS renvoie une erreur non autorisée :

[
	{
			"error_code": "UNAUTHORIZED",
			"message": "Permission denied."
	}
]

(La forme exacte du message peut varier pour d'autres API, mais elle sera similaire.)

Lorsque cela se produit, retournez simplement au Autorisation onglet et demander un nouveau jeton. Vous devez également supprimer tous les jetons expirés pour éviter toute confusion, car ils n'ont plus aucune valeur.

Faire des demandes

Vous êtes maintenant prêt à faire une demande d'obtention de vidéos.

1. Retournez au Paramètres tab et décochez tous les Query Params (vous pouvez les utiliser, bien sûr, et changer les valeurs, mais nous n'utiliserons que les valeurs par défaut pour ce premier test).
2. Cliquez sur Envoyer.
3. Vous devriez voir le code JSON apparaître dans la zone de réponse ci-dessous (un tableau d'objets de métadonnées vidéo) :

   

4. Nous allons maintenant essayer une demande d'écriture (Créer une vidéo). Sélectionnez cette demande dans la collection :

   

5. Vous devrez à nouveau entrer pour le Variable de chemin d'identification de compte. Vous serez NE PAS devez répéter les étapes de la section précédente pour configurer l'autorisation, car Postman transfère ces paramètres à d'autres demandes de la collection. Cependant, vous aurez toujours besoin de générer un nouveau jeton d'accès.
6. Ensuite, allez au Corps onglet, où vous verrez un exemple de corps de requête de la référence API :

   

7. Ce JSON est modifiable. Le seul champ obligatoire pour une demande de création de vidéo est le name , changez donc cette valeur en "Test Video" et supprimez le reste du JSON afin que le corps de votre requête soit:

   {
   	"name": "Test video"
   }

8. Cliquez maintenant sur envoyer (pour obtenir un nouveau jeton d'accès si vous en avez besoin), et vous devriez voir l'objet de métadonnées de la nouvelle vidéo apparaître dans la zone de réponse.

Rubriques connexes

• Outils de test pour les API Brightcove
• Authentification pour les demandes d'API
• Testeur d'API en ligne
• Utiliser Insomnia pour les requêtes API