For the complete DHIS2 documentation index, see llms.txt.

Utilisateurs¶

Cette section couvre les méthodes de ressources de l'utilisateur.

/api/users

Requête de l'utilisateur¶

La ressource utilisateurs offre des paramètres de requête supplémentaires en plus des paramètres standard (par exemple, la pagination). Pour rechercher des utilisateurs dans la ressource vous pouvez utiliser les paramètres suivants.

Tableau : Paramètres de requête de l'utilisateur

Paramètre	Type	Description
requête	Texte	Valeur de la requête pour le prénom, le nom de famille, le nom d'utilisateur et l'adresse électronique, sensible à la casse.
Numéro de Téléphone	Texte	Requête pour un numéro de téléphone.
peutGérer	faux \| vrai	Filtre permettant de déterminer si l'utilisateur actuel peut gérer les utilisateurs renvoyés à travers les relations de groupe d'utilisateurs gérés.
autorisation de sous-ensemble	faux \| vrai	Filtre permettant de déterminer si les utilisateurs renvoyés ont un sous-ensemble des autorisations de l'utilisateur actuel.
dernière connexion	Date	Filtre les utilisateurs qui se sont connectés après la date indiquée.
mois inactifs	Nombre	Filtre les utilisateurs qui ne se sont pas connectés pendant le nombre de mois indiqué.
inactif Depuis	Date	Filtre les utilisateurs qui ne se sont pas connectés après la date indiquée.
auto-inscrit	faux \| vrai	Filtre les utilisateurs qui se sont auto-inscrits sur leur compte d'utilisateur.
statut de l'invitation	aucun \| all \| expiré	Filtre les invitations des utilisateurs, notamment toutes les invitations ou les invitations expirées.
ou	Identificateur	Filtre les utilisateurs associés à l'unité d'organisation dont l'identifiant est indiqué.
unités d'organisation des utilisateurs	faux \| vrai	Filtre les utilisateurs qui sont associés aux unités d'organisation liées à l'utilisateur actuellement connecté.
Inclut les subordonnées	faux \| vrai	Inclut les utilisateurs de toutes les unités d'organisation subordonnées du paramètre de l'uo.
page	Nombre	Le nombre de la page.
taille de la page	Nombre	La taille de la page
limite de l'unité d'organisation	saisie de_données \| ; sortie de_données \| ; recherche_d'ies	Restreint la recherche aux utilisateurs ayant une unité d'organisation commune avec l'utilisateur actuel pour la limite indiquée

Une requête pour un maximum de 10 utilisateurs avec "konan" comme prénom ou nom de famille (sensible à la casse) qui ont un sous-ensemble d'autorisations par rapport à l'utilisateur actuel :

/api/users?query=konan&authSubset=true&pageSize=10

Récupérer tous les comptes d'utilisateurs qui ont été initialement auto-inscrits :

/api/users?selfRegistered=true

Requête de l'utilisateur par identifiant¶

La syntaxe suivante permet d'obtenir des informations complètes sur un utilisateur ayant un identifiant particulier.

/api/users/{id}

Voici un exemple d'identifiant particulier :

/api/users/OYLGMiazHtW

Recherche d'utilisateurs¶

L'API de recherche d'utilisateurs propose un système de récupération des utilisateurs lorsque la réponse comporte un minimum d'informations. Aucune autorité spécifique n'est requise et elle permet aux clients de rechercher des informations telles que le prénom et le nom de famille de l'utilisateur, sans pour autant révéler des informations potentiellement sensibles.

/api/userLookup

Le système de recherche de l'utilisateur comporte deux méthodes.

Recherche des utilisateurs par identifiant¶

Vous pouvez effectuer une recherche d'utilisateur par identifiant en utilisant la requête API suivante :

GET /api/userLookup/{id}

L'ID de l'utilisateur sera recherché par rapport aux propriétés d'utilisateur suivantes dans l'ordre indiqué :

UID
UUID
Nom d'utilisateur

Voici donc un exemple de requête :

/api/userLookup/QqvaU7JjkUV

La réponse comportera un minimum d'informations relatives à l'utilisateur.

{
  "id": "QqvaU7JjkUV",
  "nom d'utilisateur": "nkono",
  "prénom": "Thomas",
  "nom de famille": "Nkono",
  "nom affiché": "Thomas Nkono"
}

Requête de recherche d'utilisateurs¶

Vous pouvez réaliser une requête des utilisateurs à partir de la requête API suivante :

GET /api/userLookup?query={string}

Le paramètre de requête query est obligatoire. La chaîne de requête query sera comparée aux propriétés utilisateur suivantes :

Prénom
Nom
Adresses électronique
Nom d'utilisateur

En plus du paramètre query, la recherche peut être restreinte par le paramètre orgUnitBoundary comme décrit dans le tableau des paramètres pour les utilisateurs ci-dessus.

Voici donc un exemple de requête :

/api/userLookup?query=John

La réponse comportera des informations relatives aux utilisateurs et correspondants à la requête.

{
  "utilisateurs": [
    {
      "id": "DXyJmlo9rge",
      "nom d'utilisateur": "jbarnes",
      "prénom": "John",
      "nom de famille": "Barnes",
      "nom affiché": "John Barnes"
    },
    {
      "id": "N3PZBUlN8vq",
      "nom d'utilisateur": "jkamara",
      "prénom": "John",
      "nom de famille": "Kamara",
      "nom affiché": "John Kamara"
    }
  ]
}

Créer et mettre à jour un compte utilisateur¶

La création et la mise à jour des utilisateurs sont prises en charge par l'API. Une charge utile de base pour créer un utilisateur ressemble à l'exemple ci-dessous. Notez que le mot de passe sera envoyé en texte clair, n'oubliez donc pas d'activer SSL/HTTPS pour le transport réseau.

{
  "identifiant": "Mj8balLULKp",
  "Prénom": "John",
  "nom ": "Doe",
  "email": "johndoe@mail.com",
  "informations d'identification de l'utilisateur": {
    "identifiant": "lWCkJ4etppc",
    "infoUtilisateur": {
    "identifiant": "Mj8balLULKp"
  },
  "nom d'utilisateur": "johndoe123",
  "mot de passe": "Your-password-123",
  "skype": "john.doe",
  "telegram": "joh.doe",
  "whatsApp": "+1-541-754-3010",
  "facebookMessenger": "john.doe",
  "avatar": {
    "identifiant": "<fileResource id>"
  },
  "rôles d'utilisateur": [
    {
      "identifiant": "Ufph3mGRmMo"
    }
  ]
  },
  "unités d'organisation": [
    {
      "identifiant": "Rp268JB6Ne4"
    }
  ],
  "groupes d'utilisateurs": [
    {
      "identifiant": "wl5cDMuUhmF"
    }
  ]
}

curl -X POST -d @u.json "http://server/api/33/users" -u user:pass
  -H "Content-Type: application/json"

Dans la charge utile de création d'utilisateurs, les groupes d'utilisateurs ne sont pris en charge que lors de l'importation ou du POSTing d'un seul utilisateur à la fois. Si vous tentez de créer plus d'un utilisateur tout en spécifiant des groupes d'utilisateurs, vous ne recevrez pas d'erreur et les utilisateurs seront créés, mais aucun groupe d'utilisateurs ne sera affecté. Ceci est prévu et limité en raison de la relation de plusieurs à plusieurs entre les utilisateurs et les groupes d'utilisateurs, les groupes d'utilisateurs étant propriétaires de la relation. Pour mettre à jour ou créer plusieurs utilisateurs et leurs groupes d'utilisateurs, envisagez un programme pour POSTER un à la fois, ou POSTER tous les utilisateurs suivi d'une autre action pour mettre à jour leurs groupes d'utilisateurs tout en spécifiant les identifiants du nouvel utilisateur.

Lors de la création d'un utilisateur, la charge utile peut également contenir les paramètres de l'utilisateur. Ceux-ci sont ajoutés en tant qu'objet settings à l'objet racine. Chaque paire clé-valeur devient un membre de l'objet settings, par exemple :

{
    "id": "Mj8balLULKp",
    "Prénom": "John",
    "Nom": "Doe",
    "paramètres": {
        "keyUiLocale": "de"
    },
    //...
}

Après la création de l'utilisateur, une entête Location est renvoyée avec l'identifiant nouvellement généré (vous pouvez également fournir le vôtre en utilisant le point d'extrémité /api/system/id). La même charge utile peut alors être utilisée pour faire des mises à jour, mais n'oubliez pas d'utiliser PUT au lieu de POST et le point d'extrémité est désormais /api/users/ID.

curl -X PUT -d @u.json "http://server/api/33/users/ID" -u user:pass
  -H "Content-Type: application/json"

Pour plus d'informations sur l'ensemble des données disponibles, voir /api/schemas/user.

Pour plus d'informations sur le téléchargement et la récupération des avatars des utilisateurs, veuillez consulter le point d'extrémité /fileResources.

Invitations pour les comptes d'utilisateurs¶

L'API Web permet d'inviter des personnes à créer des comptes d'utilisateur par le biais de la ressource invite. Pour créer une invitation, vous devez POSTER un utilisateur au format XML ou JSON à la ressource "invite". Un nom d'utilisateur spécifique peut être imposé en définissant le nom d'utilisateur dans l'entité postée. En omettant le nom d'utilisateur, la personne pourra le spécifier elle-même. Le système enverra une invitation par courrier électronique. Il faut pour cela que les paramètres de messagerie soient correctement configurés.

La ressource "invite" est utile pour permettre en toute sécurité à des personnes de créer des comptes sans que personne d'autre ne connaisse le mot de passe ou en transférant le mot de passe en texte clair. La charge utile à utiliser pour l'invitation est la même que pour la création d'utilisateurs. Un exemple de charge utile en JSON ressemble à ceci :

{
  "prénom": "John",
  "nom": "Doe",
  "email": "johndoe@mail.com",
  "informations d'identification de l'utilisateur": {
    "nom d'utilisateur": "johndoe",
    "roles d'utilisateur": [{
      "id": "Euq3XfEIEbx"
    }]
  },
  "unités d'organisation": [ {
    "id": "ImspTQPwCqd"
  } ],
  "groupes d'utilisateurs": [ {
    "id": "vAvEltyXGbD"
  }]
}

L'entité d'invitation de l'utilisateur peut être affichée comme suit :

curl -d @invite.json "localhost/api/33/users/invite" -u admin:district
  -H "Content-Type:application/json"

Pour envoyer des invitations à plusieurs utilisateurs en même temps, vous devez utiliser un format légèrement différent. Pour JSON :

{
  "utilisateurs": [ {
    "prénom": "John",
    "nom": "Doe",
    "email": "johndoe@mail.com",
    "informations d'identification de l'utilisateur": {
      "nom d'utilisateur": "johndoe",
      "rôles d'utilisateur": [ {
        "id": "Euq3XfEIEbx"
      } ]
    },
    "unités d'organisation": [ {
      "id": "ImspTQPwCqd"
      } ]
    }, {
    "prénom": "Tom",
    "nom": "Johnson",
    "email": "tomj@mail.com",
    "informations d'identification de l'utilisateur": {
      "rôles d'utilisateur": [ {
        "id": "Euq3XfEIEbx"
      } ]
    },
    "unités d'organisation": [ {
      "id": "ImspTQPwCqd"
      } ]
    }
  ]
}

Pour créer plusieurs invitations, vous pouvez envoyer la charge utile à la ressource api/users/invites comme ceci :

curl -d @invites.json "localhost/api/33/users/invites" -u admin:district
  -H "Content-Type:application/json"

Certaines conditions doivent être remplies pour que les invitations à ouvrir un compte d'utilisateur soient envoyées :

Le serveur SMTP doit être configuré correctement sur le serveur.
L'utilisateur à inviter doit avoir indiqué un e-mail valide.
Si le nom d'utilisateur est spécifié, il ne doit pas être déjà pris par un autre utilisateur existant.

Si l'une de ces conditions n'est pas remplie, la ressource invitée renvoie un code d'état 409 Conflict accompagné d'un message descriptif.

Réplication de l'utilisateur¶

Pour reproduire un utilisateur, vous pouvez utiliser la ressource replica. Reproduire un utilisateur peut être utile pour déboguer ou reproduire des problèmes signalés par un particulier. Vous devez fournir un nouveau nom d'utilisateur et un nouveau mot de passe à l'utilisateur reproduit, que vous allez utiliser pour vous authentifier ultérieurement. Notez que vous avez besoin de l'autorisation ALL pour effectuer cette action. Pour reproduire un utilisateur, vous vous pouvez envoyer une charge utile JSON comme ci-dessous :

{
  "nom d'utilisateur" : " utilisateur_replica",
  "mot de passe" : " Motdepassesecret "
}

Cette charge utile peut être envoyée à la ressource réplica, où vous fournissez l'identifiant de l'utilisateur à répliquer dans l'URL :

/api/33/users/<uid>/replica

Voici un exemple de reproduction d'un utilisateur à l'aide de curl :

curl -d @replica.json "localhost/api/33/users/N3PZBUlN8vq/replica"
  -H "Content-Type:application/json" -u admin:district

Réinitialiser le mot de passe de l'utilisateur¶

Les administrateurs utilisateurs (disposant des droits appropriés) peuvent réinitialiser le compte d'un autre utilisateur en déclenchant la récupération du mot de passe. Une fois l'opération déclenchée, un e-mail contenant un lien de récupération est envoyé à l'utilisateur. Les utilisateurs qui suivent le lien accèdent à un formulaire qui leur permet de définir un nouveau mot de passe.

Pour déclencher ce flux de travail pour l'utilisateur tH7WIiIJ0O3, utilisez :

POST /api/37/users/tH7WIiIJ0O3/reset

Désactiver et activer des comptes d'utilisateurs¶

Les comptes d'utilisateurs peuvent être marqués comme désactivés. Un utilisateur désactivé ne peut plus se connecter.

Pour marquer un utilisateur avec l'UID tH7WIiIJ0O3 comme désactivé (nécessite un utilisateur avec les droits appropriés) :

POST /api/36/users/tH7WIiIJ0O3/disabled

Pour permettre à un utilisateur désactivé d'utiliser à nouveau l'outil en question (l'utilisateur doit disposer des droits appropriés) :

POST /api/36/users/tH7WIiIJ0O3/enabled

Expiration de l'utilisateur¶

Une date d'expiration peut être définie pour un compte d'utilisateur. Elle marque le moment à partir duquel le compte d'utilisateur a expiré et ne peut plus être utilisé. L'utilisateur dont le compte a expiré ne peut plus se connecter.

Pour mettre à jour la date d'expiration de l'utilisateur avec l'UID tH7WIiIJ0O3 et la mettre à la date 2021-01-01 (nécessite un utilisateur avec les droits appropriés) :

POST /api/36/users/tH7WIiIJ0O3/expired?date=2021-01-01

Pour désactiver la date d'expiration afin que le compte n'expire jamais utiliser en conséquence (nécessite un utilisateur disposant des droits appropriés) :

POST /api/36/users/tH7WIiIJ0O3/unexpired

Flux de travail pour l'approbation des données des utilisateurs¶

Pour connaître les flux de travail et les niveaux d'approbation des données auxquels un utilisateur peut accéder, vous pouvez utiliser la ressource dataApprovalWorkflows comme suit :

GET /api/users/{id}/dataApprovalWorkflows

Informations sur l'utilisateur actuel¶

Pour obtenir des informations sur l'utilisateur actuellement authentifié et ses associations avec d'autres ressources, vous pouvez utiliser la ressource me (vous pouvez également l'appeler par son ancien nom currentUser). Les ressources liées à l'utilisateur actuel fournissent des informations utiles lors de la création de clients, par exemple pour la saisie de données et la gestion des utilisateurs. Les paragraphes suivants décrivent ces ressources et leur objectif.

Fournit des informations de base sur l'utilisateur sous lequel vous êtes actuellement connecté. en tant qu'utilisateur, y compris le nom d'utilisateur, les informations d'identification de l'utilisateur, les unités d'organisation affectées:

/api/me

Donne des informations sur les messages non lus et les interprétations :

/api/me/tableau de bord

Pour modifier le mot de passe, ce point d'extrémité peut être utilisé pour valider le mot de passe nouvellement saisi. le nouveau mot de passe. La validation du mot de passe sera effectuée sur la base des PasswordValidationRules configurées dans le système. Ce point d'extrémité prend en charge POST et la chaîne du mot de passe doit être envoyée dans le corps de POST.

/api/me/valider le mot de passe

Lors d'un changement de mot de passe, ce point final (support POST) peut être utilisé pour vérifier l'ancien mot de passe. La chaîne du mot de passe doit être envoyée dans le corps du POST.

/api/me/verifier le mot de passe

Renvoie l'ensemble des autorisations accordées à l'utilisateur actuel :

/api/me/authorisation

Renvoie vrai ou faux, indiquant si l'utilisateur actuel a reçu l'autorisation <auth> donnée:

/api/me/authorisation/<auth>

Indique les niveaux d'approbation des données correspondant à l'utilisateur actuel :

/api/me/Niveaux d'approbation des données

Indique les flux de travail d'approbation des données accessibles à l'utilisateur actuel. Pour chaque flux de travail, indique les niveaux d'approbation des données que l'utilisateur peut voir, et les autorisations dont il dispose à chaque niveau :

/api/me/dataApprovalWorkflows