Web service dans Microsoft Access

Logo_Microsoft_Access_2013

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
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()

 

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Captcha *

Ce site utilise Akismet pour réduire les indésirables. En savoir plus sur comment les données de vos commentaires sont utilisées.