Comment utiliser la fonction OpenAPI de la caméra VIGI

Contenu

Introduction

Prérequis

Configuration

Configuration de l’accès OpenAPI

Authentification de l’interface Control et requêtes API

Authentification de l’interface Stream et requêtes Stream

Vérification

Conclusion

Questions/Réponses

Introduction

VIGI Camera OpenAPI permet aux applications tierces de communiquer avec les caméras VIGI via le réseau afin d’effectuer la configuration des appareils, la souscription aux événements et les opérations liées aux flux vidéo. Grâce à l’interface Control, un client OpenAPI peut interroger ou configurer les paramètres de la caméra et s’abonner aux messages d’événements. Grâce à l’interface Stream, il peut effectuer des opérations liées aux flux, telles que l’aperçu en direct, la lecture, le téléchargement des enregistrements et la communication audio.

Cet article présente la procédure permettant d’activer OpenAPI sur une caméra VIGI, d’effectuer l’authentification, d’appeler les API de l’interface Control et de comprendre le processus général des requêtes de l’interface Stream.

Prérequis

• Une caméra VIGI IPC compatible avec OpenAPI. (Pour vérifier les modèles compatibles, consultez Appareils compatibles avec VIGI Open API)
• Le document OpenAPI VIGI IPC
• Un client OpenAPI capable d’accéder à la caméra via le réseau

Configuration

Configuration de l’accès OpenAPI

Avant d’appeler les interfaces OpenAPI de la caméra VIGI, activez OpenAPI sur la caméra. Les étapes suivantes utilisent la page Web de gestion de la caméra comme exemple.

Étape 1. Connectez-vous à l’interface Web de la caméra à l’aide de son adresse IP. Saisissez le nom d’utilisateur et le mot de passe, puis cliquez sur Se connecter.

Étape 2. Accédez à Settings > Network Settings > OpenAPI, activez le commutateur OpenAPI, puis cliquez sur Apply pour enregistrer la configuration.

Authentification de l’interface Control et requêtes API

L’interface Control OpenAPI de la caméra VIGI utilise le protocole HTTPS. Avant d’appeler une interface Control, le client OpenAPI doit effectuer l’authentification Do Auth et obtenir le stok. Le port Control OpenAPI par défaut est 20443.

Étape 1. Envoyez la première requête doAuth afin d’obtenir les paramètres d’authentification.

Envoyez une requête POST vers https://<Camera_IP>:20443. Dans le corps de la requête, définissez method sur doAuth et params sur null. La caméra renvoie les paramètres d’authentification utilisés pour calculer la réponse, notamment realm, nonce, algorithm, uri et method.
Un exemple de commande curl sous Windows est présenté ci-dessous :
Requête :
curl.exe --% -k -X POST https://192.168.0.100:20443 -H "Content-Type: application/json" -d "{\"method\":\"doAuth\",\"params\":null}"
Réponse :
{"method":"doAuth","authenticate":{"realm":"TP-LINK IP-Camera","nonce":"c51594999c7dcfd020e97a2688d431d0","algorithm":"SHA-256","uri":"doAuth","method":"POST"},"errCode":-10020}

Étape 2. Envoyez la deuxième requête doAuth afin d’obtenir le stok.
Calculez la réponse à partir des paramètres d’authentification renvoyés à l’étape 1 et du mot de passe de connexion de la caméra. Si l’algorithme renvoyé est SHA-256, calculez la réponse comme suit :

A1 = SHA256(admin:<realm>:<password>)

A2 = SHA256(<method>:<uri>)

response = SHA256(A1:<nonce>:A2)
Envoyez ensuite une requête POST vers https://<Camera_IP>:20443. Dans le corps de la requête, définissez method sur doAuth et incluez le nonce renvoyé ainsi que la response calculée dans params.

Un exemple de commande curl sous Windows est présenté ci-dessous :

Requête :
curl.exe --% -k -X POST https://192.168.0.100:20443 -H "Content-Type: application/json" -d "{\"method\":\"doAuth\",\"params\":{\"nonce\":\"c51594999c7dcfd020e97a2688d431d0\",\"response\":\"ae990e323d2370c9a6cbcf638b5808f006f2c32343034787205f00d81c1fe16a\"}}"
Réponse :
{"method":"doAuth","stok":"jqNXOtUS7*Qu0XSvOqO0uOXst1ZlOOcD","errCode":0}

Étape 3. Appeler les API de l’interface Control

Après avoir obtenu le stok, ajoutez-le à l’URL de la requête et envoyez la requête de l’interface Control cible au format JSON. La méthode de requête est POST et le format de l’URL est le suivant : https://<Camera_IP>:20443/stok=<stok>.

Cette section présente deux exemples : une requête Control courante permettant de définir le fuseau horaire de la caméra et une requête d’abonnement aux événements permettant de recevoir les messages d’événements.

Exemple 1 : Définir le fuseau horaire de la caméra
L’interface setTimeZone permet de définir le fuseau horaire de la caméra. Dans le corps de la requête, définissez method sur setTimeZone et configurez timezone et area dans params. L’exemple suivant définit le fuseau horaire de la caméra sur America/Los_Angeles.

Requête :
curl.exe --% -k -X POST https://192.168.0.100:20443/stok=jqNXOtUS7*Qu0XSvOqO0uOXst1ZlOOcD -H "Content-Type: application/json" -d "{\"method\":\"setTimeZone\",\"params\":{\"timezone\":\"UTC-08:00",\"area\":\"America/Los_Angeles\"}}"
Réponse :
{"method":"setTimeZone","errCode":0}

Exemple 2 : S’abonner aux messages d’événements

L’interface subscribeMsg permet de s’abonner aux messages liés aux événements de détection. Dans le corps de la requête, définissez method sur subscribeMsg et configurez event_type et heartbeat dans params. Après l’envoi de la requête, maintenez la connexion ouverte. La caméra envoie périodiquement des paquets heartbeat et transmet les messages d’événements via cette même connexion lorsqu’un événement est déclenché.

Requête :

curl.exe --% -k -N -X POST https://192.168.0.100:20443/stok=jqNXOtUS7*Qu0XSvOqO0uOXst1ZlOOcD -H "Content-Type: application/json" -d "{\"method\":\"subscribeMsg\",\"params\":{\"event_type\":[\"all\"],\"heartbeat\":10}}"

Réponse :

{"method":"subscribeMsg","errCode":0}

Authentification de l’interface Stream et requêtes Stream

L’interface Stream OpenAPI de la caméra VIGI est établie via RTSP. Le client OpenAPI doit effectuer une authentification Digest avant d’envoyer des requêtes liées aux flux. Cette section utilise le scénario de téléchargement d’un enregistrement comme exemple afin de décrire le processus général de l’interface Stream.

Étape 1. Obtenir les paramètres de requête du flux si nécessaire.

Pour certaines opérations liées aux flux, telles que la requête de téléchargement de l’interface Stream, le client doit d’abord obtenir les paramètres nécessaires via l’interface Control. Par exemple, avant d’envoyer une requête de téléchargement, appelez getMediaList dans la section 4.11.1 du document OpenAPI VIGI IPC afin d’obtenir l’heure de début d’enregistrement, l’heure de fin, le FileID, event_type et d’autres informations associées. Utilisez ensuite les paramètres requis dans la requête de téléchargement de l’interface Stream.

Étape 2. Vérifier le port RTSP.

Vérifiez le port RTSP de la caméra dans la page Web de gestion de la caméra en accédant à Settings > Network Settings > Network Service > RTSP. Dans cet exemple, le port RTSP est 554. Si la caméra est accessible via une redirection de port, utilisez le port RTSP externe configuré sur le routeur au lieu du port RTSP interne de la caméra.

Étape 3. Établir la connexion RTSP et effectuer l’authentification Digest.

Le client établit une connexion TCP avec le port RTSP de la caméra et envoie une première requête MULTITRANS. La caméra renvoie une réponse 401 Unauthorized contenant les paramètres d’authentification Digest. Le client calcule la réponse d’authentification à partir du nom d’utilisateur, du mot de passe, de la méthode de requête, de l’URI de requête et des paramètres d’authentification retournés, puis envoie à nouveau la requête MULTITRANS avec l’en-tête d’authentification. Pour plus de détails concernant le calcul de l’authentification Digest, consultez la Section 2.2.2 Digest Authentication du document OpenAPI VIGI IPC.

Étape 4. Envoyer la requête de l’interface Stream.

Une fois l’authentification Digest réussie, le client envoie la requête Stream nécessaire, telle que l’aperçu en direct, la lecture, le téléchargement d’enregistrement, l’arrêt, la lecture, la demande forcée d’une image I ou la communication audio. Pour le téléchargement d’un enregistrement, la caméra renvoie 200 OK avec les informations du codec et commence à envoyer les données RTP via la connexion TCP. Pour plus de détails sur les méthodes et paramètres de l’interface Stream, consultez la Section 5 OpenAPI Stream Interface du document OpenAPI VIGI IPC.

Étape 5. Recevoir et analyser les données RTP.

Les données du flux sont transmises sous forme de RTP via TCP. Le client doit identifier les paquets RTP grâce à l’octet initial $, lire le Channel ID et la Payload Length, puis analyser l’en-tête RTP et la charge utile. Le client doit également identifier le type de média en fonction du type de charge utile RTP. Pour plus de détails concernant la structure des paquets RTP sur TCP, consultez la Section 2.3 Data Transmission. Pour les définitions des types de charge utile, consultez l’Appendix 2 Payload Type du document OpenAPI VIGI IPC.

Étape 6. Vérifier et traiter le codec audio si des données audio sont impliquées.

Si l’opération de flux implique des données audio, comme le téléchargement d’un enregistrement avec audio ou la communication audio, appelez l’interface getAudioEncode dans la Section 4.4.6 du document OpenAPI VIGI IPC afin de vérifier d’abord le codec audio de la caméra. Le client doit traiter la charge utile RTP audio en fonction de la valeur encode_type retournée.

Vérification

Après avoir appelé les API de l’interface Control présentées dans les exemples précédents, vérifiez les résultats comme suit.
Vérification de l’exemple 1 : Définir le fuseau horaire de la caméra
Après que la requête setTimeZone a retourné "errCode": 0, connectez-vous à la page Web de gestion de la caméra et accédez à Settings > System Settings > Basic Settings > Date. Vérifiez que la valeur du Time Zone a été modifiée selon le fuseau horaire configuré. Dans cet exemple, le fuseau horaire doit être défini sur (UTC-08:00) Pacific Time.

Vérification de l’exemple 2 : S’abonner aux messages d’événements

Après que la requête subscribeMsg a retourné "result": "success" et "errCode": 0, maintenez l’exécution de la commande. La caméra envoie des paquets heartbeat selon l’intervalle configuré et transmet les messages d’événements via la même connexion lorsqu’un événement est déclenché.

Dans cet exemple, event_type est défini sur all et heartbeat est défini sur 10. Le terminal doit donc afficher des paquets heartbeat toutes les 10 secondes et afficher les messages d’événements lorsqu’un événement souscrit est déclenché.

Conclusion

Après avoir suivi les étapes décrites dans cet article, vous pouvez activer OpenAPI sur la caméra VIGI, effectuer l’authentification et appeler l’interface Control ou l’interface Stream selon vos besoins. Les exemples montrent également comment vérifier les appels courants de l’interface Control et comprendre le processus général des requêtes de l’interface Stream.

Questions/Réponses

Q1 : Comment le client doit-il gérer les connexions lors de l’appel de l’interface Control ?
R1 : Pour les appels de l’interface Control, créez une nouvelle connexion pour chaque requête API.

Après avoir obtenu le stok via doAuth, utilisez ce stok pour appeler l’API Control requise, telle que getDeviceInfo ou setTimeZone. Chaque requête API doit être envoyée via une connexion distincte afin que la requête puisse être envoyée et traitée indépendamment.

Pour subscribeMsg, maintenez la connexion ouverte après la réussite de la souscription. La caméra utilise cette connexion pour envoyer les paquets heartbeat et les messages d’événements.

Q2 : Où puis-je trouver le document OpenAPI VIGI IPC ?
R2 : Accédez au Centre de téléchargement, recherchez le modèle de caméra et ouvrez la page de téléchargement du produit. Dans la section Manual, téléchargez le document correspondant VIGI IPC OpenAPI Document.

Pour obtenir davantage de détails sur chaque fonction et chaque configuration, veuillez consulter le Centre de téléchargement afin de télécharger le manuel correspondant à votre produit.