Cet article a pour but d’expliquer l’implémentation et l’utilisation de web services dans Microsoft Access.
Le contexte est le suivant :
D’un côté nous avons une application métier développée via Microsoft Access : mAppliAccess qui permet de gérer les équipements qui composent une résidence (exemple d’équipements : ascenseur, porte automatique de garage, chaudière individuelle, etc.)
De l’autre côté, on a un portail internet géré par un prestataire externe : ePortailWeb qui regroupe toutes les pannes et maintenances réalisées sur ces équipements.
Dans un premier temps, on va voir comment nous pouvons nous connecter à l'ePortailWeb sur l’équipement sélectionné via mAppliAccess à l’aide d’un web service.
Ensuite, dans un second temps, nous allons voir comment on interroge ePortailWeb pour avoir l’état d’un équipement en temps réel toujours en utilisant un web service via mAppliAccess.
Le prestataire externe d’ePortailWeb gère les web services au travers d’une API (Application Programming Interface) de type REST (Representational State Transfer).
Notre point d’entrée est : https://www.eportailweb.fr/api
Il nous fournit également un compte utilisateur et un mot de passe générique pour pouvoir se connecter au ePortailWeb : user:password
L’authentification se fait par jeton API. La sécurité est assurée par l’utilisation du protocole TSL/SSL (Transport Layer Security/Secure Sockets Layer).
Le résultat des requêtes https (HyperText Transfer Protocol Secure) pour obtenir l’état d’un équipement est sous la forme d’un fichier au format JSON (JavaScript Object Notation).
Dans notre application métier mAppliAccess, on ajoute la référence Microsoft WinHTTP Services via le menu Outils/Références accessible dans la fenêtre de code Microsoft Access (chemin d’accès : C:\windows\system32\winhttp.dll).
Cette référence permet d’accéder à la bibliothèque WinHttp et surtout à la classe qui nous intéresse : WinHttpRequest
Se connecter au portail internet et accéder aux informations concernant l’équipement sélectionné :
Dans notre application mAppliAccess, on crée un module ModWebService.
A l’intérieur de ce module on crée la fonction GIVEME_EPORTAILWEB_URL.
On passe le code de l’équipement que l’on souhaite visualiser en entrée.
En sortie, la fonction nous retourne l’url de connexion avec le jeton pour visualiser l’équipement souhaité sur ePortailWeb.
On utilise la fonction Shell avec l’url retournée pour ouvrir le portail internet avec le navigateur souhaité (ici on utilise C:\Program Files\Internet Explorer\iexplore.exe).
Public Function GIVEME_EPORTAILWEB_URL(ByVal mCodEqu As String) As String
Dim mRequest As New WinHttp.WinHttpRequest
Dim mUrlApi As String
Dim mlogBase64 As String
Dim mResponse As String
Dim mMsgError As String
'fonction qui retourne l'url avec le token pour visualiser un équipement dans ePortailWeb
On Error GoTo ErrorHandler
'ici on utilise l'API qui nous retourne l'url de visualisation de l'équipement avec le jeton d'authentification
mUrlApi = "https://www.eportailweb.fr/api/user/generate_authenticated_url?equipment_name=" & mCodEqu
'ici on encode le login et le password en base64
mlogBase64 = Base64EncodeString("user:password")
'web service
'on ouvre la connexion
mRequest.Open "GET", mUrlApi, False
'on initialise le header en lui affectant le login:password
mRequest.SetRequestHeader "Authorization", "Basic " & mlogBase64
'on envoie la requête
mRequest.Send
mRequest.WaitForResponse
'on récupère la réponse en chaîne de caractères
mResponse = mRequest.ResponseText
'exemple de réponse valide : {"url": "//www.eportailweb.fr/?equipment=1402&authkey=8506b688-01a5-4e7e-94f4-b32d9409d36b"}
'exemples de réponse non valide : {"detail": "Invalid username/password"} ou {"detail": "Not found"}
If InStr(1, mResponse, "eportailweb") > 0 Then
'ici on retravaille la réponse pour retourner l'url avec le token
mResponse = chaineADroite(mResponse, Chr(63))
mResponse = chaineAGauche(mResponse, Chr(34))
'exemple d'url valide : https://www.eportailweb.fr/?equipment=1402&authkey=8506b688-01a5-4e7e-94f4-b32d9409d36b
GIVEME_EPORTAILWEB_URL = "https://www.eportailweb.fr/" & Chr(63) & mResponse
Else
'erreur de login ou pas d'équipement
If InStr(1, mResponse, "Invalid") > 0 Then
mMsgError = "Login et mot de passe incorrect"
Else
mMsgError = "Cet équipement : " & mCodEqu & " n'existe pas dans ePortailWeb"
End If
GIVEME_EPORTAILWEB_URL = mMsgError
End If
Set mRequest = Nothing
Exit Function
ErrorHandler:
GIVEME_EPORTAILWEB_URL = Err.Description
Set mRequest = Nothing
Err.Clear
End Function
ModWebService - GIVEME_EPORTAILWEB_URL()
Requêter en temps réel le portail internet pour obtenir le statut d’un équipement :
A l’intérieur du module ModWebService, on crée la fonction GIVEME_EQU_STATUT.
On passe le code de l’équipement en entrée.
En sortie, la fonction nous retourne le statut de l’équipement :
OK = l’équipement est en état de marche.
Si l’équipement est KO, la fonction nous retourne la cause du dysfonctionnement de l’équipement.
Public Function GIVEME_EQU_STATUT(ByVal mCodEqu As String) As String
Dim mRequest As New WinHttp.WinHttpRequest
Dim mUrlApi As String
Dim mlogBase64 As String
Dim mResponse As String
Dim mRetour As String
Dim mTabResp() As String
Dim mTabData() As String
Dim i As Integer
'fonction qui retourne le statut d'un équipement dans ePortailWeb
On Error GoTo ErrorHandler
'ici on utilise l'API qui nous retourne les données concernant un équipement au format JSON
mUrlApi = "https://www.eportailweb.fr/api/equipments?name=" & mCodEqu & "&format=json"
'ici on encode le login et le password en base64
mlogBase64 = Base64EncodeString("user:password")
'web service
'on ouvre la connexion
mRequest.Open "GET", mUrlApi, False
'on initialise le header en lui affectant le login:password
mRequest.SetRequestHeader "Authorization", "Basic " & mlogBase64
'on envoie la requête
mRequest.Send
mRequest.WaitForResponse
'on récupère la réponse en chaîne de caractères
mResponse = mRequest.ResponseText
'exemple de réponse au format JSON :
'[{"url": "https://www.eportailweb.fr/api/equipment/1234", "name": "EQU-1234-AB", "provider_name": "123-AB/1", "status": false, "status_label": "Panne", "type": "Ascenseur", "location": "DROIT", "logs": "https://www.eportailweb.fr/api/equipment/1234/logs"}]
If Nz(mResponse, "") <> "" Then
'ici on retravaille la réponse pour retrouver facilement le statut
mResponse = Replace(mResponse, "[{", "")
mResponse = Replace(mResponse, "}]", "")
mResponse = Replace(mResponse, """", "")
mRetour = ""
'ici on sépare sur ", " on obtient un tableau 1 dimension contenant le libellé et la valeur
mTabResp = Split(mResponse, ", ")
ReDim mTabData(UBound(mTabResp), 1)
'ici on sépare sur ": " pour avoir le libellé en colonne 0 et la valeur en colonne 1
For i = 0 To UBound(mTabResp)
mTabData(i, 0) = chaineAGauche(mTabResp(i), ": ")
mTabData(i, 1) = chaineADroite(mTabResp(i), ": ")
Next
For i = 0 To UBound(mTabData)
'ici on récupère le statut
If UCase(mTabData(i, 0)) = "STATUT" Then
If UCase(mTabData(i, 1)) = "TRUE" Then
mRetour = "OK"
ElseIf UCase(mTabData(i, 1)) = "FALSE" Then
mRetour = "KO"
End If
End If
If mRetour = "KO" Then
'ici, si statut = KO, on récupère le status_label qui précise le dysfonctionnement de l'équipement
If UCase(mTabData(i, 0)) = "STATUS_LABEL" Then
mRetour = mTabData(i, 1)
End If
End If
Next
Erase mTabResp
Erase mTabData
GIVEME_EQU_STATUT = mRetour
End If
Set mRequest = Nothing
Exit Function
ErrorHandler:
GIVEME_EQU_STATUT = Err.Description
Set mRequest = Nothing
Err.Clear
End Function
ModWebService - GIVEME_EQU_STATUT()
