Question :
Comment éviter les erreurs 401 liées à l'absence de licences libres lors de l'utilisation de l'API DocuWare ?
Réponse :
En général, il existe deux options. Soit l'utilisation de cookies pour maintenir la session en vie, soit l'utilisation de jetons pour réutiliser l'ancienne session. La procédure à suivre est décrite ci-dessous.
En général, il existe deux options. Soit l'utilisation de cookies pour maintenir la session en vie, soit l'utilisation de jetons pour réutiliser l'ancienne session. La procédure à suivre est décrite ci-dessous.
Authentification :
Avant que le cookie/jeton puisse être utilisé, une session initiale est nécessaire. L'application doit donc se connecter à DocuWare. Pour ce faire, elle doit envoyer une requête post contenant les données d'authentification au point de terminaison /Account/Logon. La réponse contiendra au moins les deux cookies suivants : .DWPLATFORMAUTH et DWPLATFORMBROWSERID.
Déconnexion :
Lorsqu'une déconnexion est effectuée via le point de terminaison /Account/LogOff, l'utilisateur est déconnecté de DocuWare. Le cookie de session actuel devient invalide et ne peut plus être utilisé par la suite. Cela signifie qu'une nouvelle session doit être créée. Si une nouvelle tentative de connexion a lieu dans les deux minutes qui suivent et qu'aucune licence gratuite n'est disponible, le code d'état HTTP 401 avec le message "Aucune des licences enregistrées n'est disponible pour le client [nom d'utilisateur]" sera renvoyé.
Éviter la réponse 401 :
L'une des deux options suivantes peut être utilisée pour éviter le code d'état 401 décrit ci-dessus.
Maintenir la session vivante à l'aide de cookies:
Après la connexion, stockez le cookie .DWPLATFORMAUTH dans un conteneur de cookies. Le cookie du conteneur de cookies peut désormais être utilisé dans toutes les demandes suivantes adressées à l'API DocuWare. Tant que la déconnexion est effectuée, l'application peut utiliser l'ancienne session sans avoir à se réauthentifier et n'utilisera qu'une seule licence client. Utilisez cette méthode si l'application envoie des requêtes à l'API DocuWare dans un laps de temps irrégulier. La durée de vie du cookie est fixée à 20 ans et devrait fonctionner tant qu'aucune déconnexion n'est effectuée.
Reconnexion dans les deux minutes à l'aide d'un jeton:
Il est parfois nécessaire de se reconnecter à l'API DocuWare dans les deux minutes qui suivent l'appel au point de terminaison /Account/LogOff. Pour éviter l'erreur 401, il est possible d'utiliser un jeton au lieu de maintenir la session en vie à l'aide d'un cookie. Le jeton peut être créé avant la déconnexion en appelant le point de terminaison /Organisations/LoginToken via la méthode post. Cet appel nécessite un corps, dans lequel le produit cible, l'utilisation (Multi, Single) et la durée de vie sont spécifiés. Veuillez consulter l'exemple suivant de corps JSON pour créer un jeton :
{
"TargetProducts" :["PlatformService"],
"Usage" : "Multi" ,
"Lifetime":"1.00:00:00"
}
La réponse contiendra le jeton fourni par la plateforme. Ensuite, l'authentification peut être effectuée en envoyant le jeton par courrier à /Account/TokenLogOn. Cette méthode d'authentification permet de réutiliser la licence utilisateur qui était utilisée avant l'opération de déconnexion. Le jeton a une durée de vie qui peut être définie lors de la demande du jeton (paramètre Lifetime). La plupart des applications DocuWare (par exemple, les applications bureautiques) utilisent un jeton d'une durée de vie de 365 jours. Pour répéter ce processus, il est important de créer un nouveau jeton avant la déconnexion et de toujours utiliser le dernier jeton pour effectuer l'opération de connexion.
Déconnexion :
Lorsqu'une déconnexion est effectuée via le point de terminaison /Account/LogOff, l'utilisateur est déconnecté de DocuWare. Le cookie de session actuel devient invalide et ne peut plus être utilisé par la suite. Cela signifie qu'une nouvelle session doit être créée. Si une nouvelle tentative de connexion a lieu dans les deux minutes qui suivent et qu'aucune licence gratuite n'est disponible, le code d'état HTTP 401 avec le message "Aucune des licences enregistrées n'est disponible pour le client [nom d'utilisateur]" sera renvoyé.
Éviter la réponse 401 :
L'une des deux options suivantes peut être utilisée pour éviter le code d'état 401 décrit ci-dessus.
Maintenir la session vivante à l'aide de cookies:
Après la connexion, stockez le cookie .DWPLATFORMAUTH dans un conteneur de cookies. Le cookie du conteneur de cookies peut désormais être utilisé dans toutes les demandes suivantes adressées à l'API DocuWare. Tant que la déconnexion est effectuée, l'application peut utiliser l'ancienne session sans avoir à se réauthentifier et n'utilisera qu'une seule licence client. Utilisez cette méthode si l'application envoie des requêtes à l'API DocuWare dans un laps de temps irrégulier. La durée de vie du cookie est fixée à 20 ans et devrait fonctionner tant qu'aucune déconnexion n'est effectuée.
Reconnexion dans les deux minutes à l'aide d'un jeton:
Il est parfois nécessaire de se reconnecter à l'API DocuWare dans les deux minutes qui suivent l'appel au point de terminaison /Account/LogOff. Pour éviter l'erreur 401, il est possible d'utiliser un jeton au lieu de maintenir la session en vie à l'aide d'un cookie. Le jeton peut être créé avant la déconnexion en appelant le point de terminaison /Organisations/LoginToken via la méthode post. Cet appel nécessite un corps, dans lequel le produit cible, l'utilisation (Multi, Single) et la durée de vie sont spécifiés. Veuillez consulter l'exemple suivant de corps JSON pour créer un jeton :
{
"TargetProducts" :["PlatformService"],
"Usage" : "Multi" ,
"Lifetime":"1.00:00:00"
}
La réponse contiendra le jeton fourni par la plateforme. Ensuite, l'authentification peut être effectuée en envoyant le jeton par courrier à /Account/TokenLogOn. Cette méthode d'authentification permet de réutiliser la licence utilisateur qui était utilisée avant l'opération de déconnexion. Le jeton a une durée de vie qui peut être définie lors de la demande du jeton (paramètre Lifetime). La plupart des applications DocuWare (par exemple, les applications bureautiques) utilisent un jeton d'une durée de vie de 365 jours. Pour répéter ce processus, il est important de créer un nouveau jeton avant la déconnexion et de toujours utiliser le dernier jeton pour effectuer l'opération de connexion.
Le KBA s'applique aussi bien aux organisations en nuage qu'aux organisations sur site.
Veuillez noter : Cet article est une traduction de l'anglais. Les informations contenues dans cet article sont basées sur la ou les versions originales des produits en langue anglaise. Il peut y avoir des erreurs mineures, notamment dans la grammaire utilisée dans la version traduite de nos articles. Bien que nous ne puissions pas garantir l'exactitude complète de la traduction, dans la plupart des cas, vous la trouverez suffisamment informative. En cas de doute, veuillez revenir à la version anglaise de cet article.