Visualisations¶

Tableaux de bord¶

Le tableau de bord est conçu pour vous donner un aperçu de plusieurs éléments analytiques tels que des cartes, des graphiques, des tableaux croisés dynamiques et des rapports qui, ensemble, peuvent fournir un aperçu complet de vos données. Les tableaux de bord sont disponibles dans l'API Web via la ressource tableaux de bord. Un tableau de bord contient une liste d'éléments de tableau de bord. Un élément peut représenter une ressource unique, comme un graphique, une carte ou un tableau de rapport, ou représenter une liste de liens vers des ressources analytiques, comme des rapports, des ressources, des rapports tabulaires et des utilisateurs. Un élément de tableau de bord peut contenir jusqu'à huit liens. En règle générale, un client de tableau de bord peut choisir de visualiser les éléments à objet unique directement dans une interface utilisateur, tout en rendant les éléments à objets multiples sous forme de liens cliquables.

/api/tableau de bord

Parcourir les tableaux de bord¶

Pour obtenir une liste de vos tableaux de bord avec des informations de base telles que l'identifiant, le nom et le lien au format JSON, vous pouvez envoyer une requête GET à l'URL suivante :

/api/dashboards.json

La ressource Tableaux de bord fournit une liste de tableaux de bord. N'oubliez pas que l'objet tableau de bord est partagé et que la liste sera donc affectée par l'utilisateur actuellement authentifié. Vous pouvez obtenir plus d'informations sur un tableau de bord spécifique en suivant son lien, comme suit :

/api/dashboards/vQFhmLJU5sK.json

Un tableau de bord contient des informations telles que le nom et la date de création, ainsi qu'un tableau d'éléments du tableau de bord. La réponse au format JSON ressemblera à cette réponse (certaines informations ont été supprimées par souci de concision).

{
  "lastUpdated" : "2013-10-15T18:17:34.084+0000",
  "id": "vQFhmLJU5sK",
  "created": "2013-09-08T20:55:58.060+0000",
  "name": "Mother and Child Health",
  "href": "https://play.dhis2.org/demo/api/dashboards/vQFhmLJU5sK",
  "publicAccess": "--------",
  "restrictFilters": false,
  "externalAccess": false,
  "itemCount": 17,
  "displayName": "Mother and Child Health",
  "access": {
    "update": true,
    "externalize": true,
    "delete": true,
    "write": true,
    "read": true,
    "manage": true
  },
  "user": {
    "id": "xE7jOejl9FI",
    "name": "John Traore",
    "created": "2013-04-18T15:15:08.407+0000",
    "lastUpdated": "2014-12-05T03:50:04.148+0000",
    "href": "https://play.dhis2.org/demo/api/users/xE7jOejl9FI"
  },
  "dashboardItems": [{
    "id": "bu1IAnPFa9H",
    "created": "2013-09-09T12:12:58.095+0000",
    "lastUpdated": "2013-09-09T12:12:58.095+0000"
    }, {
    "id": "ppFEJmWWDa1",
    "created": "2013-09-10T13:57:02.480+0000",
    "lastUpdated": "2013-09-10T13:57:02.480+0000"
  }],
  "layout": {
    "spacing": {
      "column": 5,
      "row": 5
    },
    "columns": [{
      "index": 0,
      "span": 2
    }, {
      "index": 1,
      "span": 1
    }]
  },
  "userGroupAccesses": []
}

Il est possible d'obtenir une réponse plus personnalisée en spécifiant des champs particuliers dans la demande. Un exemple est fourni ci-dessous, qui renverrait des informations plus détaillées sur chaque objet du tableau de bord d'un utilisateur.

/api/dashboards/vQFhmLJU5sK/?fields=:all,dashboardItems[:all]

Rechercher des tableaux de bord¶

Lorsqu'un utilisateur crée un tableau de bord, il est pratique de pouvoir rechercher diverses ressources analytiques à l'aide des ressources /dashboards/q ou /dashboards/search. Ces ressources vous permettent de rechercher des correspondances sur la propriété de nom des objets suivants : visualisations, cartes de visualisations d'événements, utilisateurs, rapports et ressources. Vous pouvez effectuer une recherche en effectuant une requête GET sur le modèle d'URL de ressource suivant, où « my-query » doit être remplacé par la requête de recherche préférée :

/api/dashboards/q/my-query.json
/api/dashboards/search?q=my-query

Par exemple, cette requête :

/api/dashboards/q/ma?count=6&maxCount=20&max=REPORT&max=MAP
/api/dashboards/search?q=ma?count=6&maxCount=20&max=REPORT&max=MAP

La recherche portera sur les éléments suivants :

• Le nom de l'objet analytique contient la chaîne « ma »
• Renvoi jusqu'à 6 exemplaires de chaque type
• Pour les types RAPPORT et CARTE, il est possible de renvoyer jusqu'à 20 éléments.

Tableau : tableaux de bord/q et tableaux de bord/paramètres de requête de recherche

Les formats de réponse JSON et XML sont pris en charge. La réponse au format JSON contiendra les références aux ressources correspondantes et le nombre de correspondances trouvées au total et pour chaque type de ressource. Elle ressemblera à ceci :

{
  "visualizations": [{
    "name": "ANC: ANC 3 Visits Cumulative Numbers",
    "id": "arf9OiyV7df",
    "type": "LINE"
  }, {
    "name": "ANC: 1st and 2rd trends Monthly",
    "id": "jkf6OiyV7el",
    "type": "PIVOT_TABLE"
  }],
  "eventVisualizations": [{
    "name": "Inpatient: Cases 5 to 15 years this year (case)",
    "id": "TIuOzZ0ID0V",
    "type": "LINE_LIST"
  }, {
    "name": "Inpatient: Cases last quarter (case)",
    "id": "R4wAb2yMLik",
    "type": "LINE_LIST"
  }],
  "maps": [{
    "name": "ANC: 1st visit at facility (fixed) 2013",
    "id": "YOEGBvxjAY0"
  }, {
    "name": "ANC: 3rd visit coverage 2014 by district",
    "id": "ytkZY3ChM6J"
  }],
  "reports": [{
    "name": "ANC: 1st Visit Cumulative Chart",
    "id": "Kvg1AhYHM8Q"
  }, {
    "name": "ANC: Coverages This Year",
    "id": "qYVNH1wkZR0"
  }],
  "searchCount": 8,
  "visualizationCount": 2,
  "eventVisualizationCount": 2,
  "mapCount": 2,
  "reportCount": 2,
  "userCount": 0,
  "eventReports": 0,
  "eventCharts" :0,
  "resourceCount": 0
}

Créer, mettre à jour et supprimer des tableaux de bords{ #webapi_creating_updating_removing_dashboards }¶

La création, la mise à jour et la suppression des tableaux de bord suivent la sémantique REST standard. Pour créer un nouveau tableau de bord, vous pouvez faire une requête POST à la ressource /api/dashboards. Du point de vue du consommateur, il peut être pratique de créer d'abord un tableau de bord et d'y ajouter ensuite des éléments. Les formats JSON et XML sont supportés pour la charge de la requête. Pour créer un tableau de bord avec le nom « Mon tableau de bord », vous pouvez utiliser une charge JSON comme celle-ci :

{
  "nom": "Mon tableau de bord"
}

Pour mettre à jour, par exemple renommer, un tableau de bord, vous pouvez faire une demande PUT avec une charge similaire à la même ressource api/dashboards.

To remove a dashboard, you can make a DELETE (supprimer) request to the specific dashboard resource similar to this:

/api/dashboards/vQFhmLJU5sK

Ajouter, déplacer et supprimer des éléments et du contenu du tableau de bord¶

Pour ajouter des éléments au tableau de bord, un utilisateur peut utiliser la ressource /api/dashboards/<dashboard-id>/items/content, où <dashboard-id> doit être remplacé par l'identifiant du tableau de bord concerné.La demande doit utiliser la méthode POST. La syntaxe de l'URL et les paramètres sont décrits en détail dans le tableau suivant.

Tableau : Paramètres du contenu des éléments

L'URL d'une requête POST pour ajouter une visualisation à un tableau de bord spécifique pourrait ressembler à ceci, où la dernière valeur du paramètre de l'identifiant de la requête est l'identifiant de la ressource du graphique :

/api/dashboards/vQFhmLJU5sK/items/content?type=visualization&id=LW0O27b7TdD

Lors de l'ajout d'une ressource de type carte, visualisation et application, l'API crée et ajoute un nouvel élément au tableau de bord. Lors de l'ajout d'une ressource de type utilisateurs, rapports et ressources, l'API tente d'ajouter la ressource à un élément de tableau de bord existant du même type. S'il n'existe aucun élément du même type ou aucun élément du même type auquel moins de huit ressources sont associées, l'API crée un nouvel élément de tableau de bord et y ajoute la ressource.

Pour déplacer un élément du tableau de bord vers une nouvelle position dans la liste des éléments du tableau de bord, un utilisateur peut envoyer une requête POST à l'URL suivante, où <dashboard-id> doit être remplacé par l'identifiant du tableau de bord, <item-id> doit être remplacé par l'identifiant de l'élément du tableau de bord et <index> doit être remplacé par la nouvelle position de l'élément dans le tableau de bord, où l'index est égal à zéro :

/api/dashboards/<dashboard-id>/items/<item-id>/position/<index>

Pour supprimer complètement un élément d'un tableau de bord spécifique, un utilisateur peut envoyer une requête DELETE à l'URL de la ressource ci-dessous, où <dashboard-id> doit être remplacé par l'identifiant du tableau de bord et <item-id> par l'identifiant de l'élément du tableau de bord. Les identifiants des éléments du tableau de bord peuvent être récupérés par le biais d'une requête GET à l'URL de la ressource tableau de bord.

/api/dashboards/<dashboard-id>/items/<item-id>

Pour supprimer une ressource de contenu spécifique dans un élément de tableau de bord, un utilisateur peut envoyer une requête DELETE à l'URL de ressource ci-dessous, où <content-resource-id> doit être remplacé par l'identifiant d'une ressource associée à l'élément de tableau de bord, par exemple l'identifiant d'un rapport ou d'un utilisateur. Par exemple, cela peut être utilisé pour supprimer un seul rapport d'un élément de tableau de bord de type rapports, plutôt que de supprimer complètement l'élément du tableau de bord :

/api/dashboards/<dashboard-id>/items/<item-id>/content/<content-resource-id>

Définir la présentation d'un tableau de bord¶

Vous pouvez définir et enregistrer une présentation pour chaque tableau de bord. L'objet suivant est chargé de gérer ce paramètre.

{
  "layout": {
    "spacing": {
      "column": 5,
      "row": 5
    },
    "columns": [{
      "index": 0,
      "span": 2
    }, {
      "index": 1,
      "span": 1
    }]
  }
}

La définition de la présentation sera appliquée à tous les éléments du tableau de bord liés au tableau de bord donné, en respectant les attributs de présentation tels que l'espacement, les colonnes, la portée, etc. Vous trouverez ci-dessous une brève description de chaque attribut.

Tableau : Attributs de la présentation

Visualisation¶

L'API de visualisation est conçue pour aider les clients à interagir avec les graphiques et les tableaux croisés dynamiques/rapports. Les endpoints de cette API sont utilisés par l'application de visualisation des données qui permet la création, la configuration et la gestion des graphiques et des tableaux croisés dynamiques sur la base des définitions du client. L'idée principale est de permettre aux clients et aux utilisateurs de disposer d'une API unique et centralisée fournissant tous les types de graphiques et de tableaux croisés dynamiques ainsi que des paramètres et une configuration spécifiques pour chaque type de visualisation.

Cette API a été introduite pour unifier les API charts (graphiques) et reportTables (tableaux de rapports) et les remplacer entièrement par l'API visualizations (visualisations).

Un objet de visualisation est composé de nombreux attributs (certains sont liés aux graphiques et d'autres aux tableaux croisés dynamiques), mais les plus importants d'entre eux, qui reflètent les informations essentielles de l'objet, sont les suivants :* "id" (identifiant) , "name" (nom) , "type" (type) , "dataDimensionItems" (éléments de données de dimensions) , "columns" (colonnes) , "rows" (lignes) et "filters" (filtres) .*

Le endpoint racine de l'API est /api/visualizations, et la liste des attributs et éléments actuels est décrite dans le tableau ci-dessous.

Tableau : Attributs de visualisation

Récupération des visualisations¶

Pour récupérer une liste de toutes les visualisations existantes, au format JSON, avec quelques informations de base (y compris l'identifiant, le nom et la pagination), vous pouvez faire une requête GET à l'URL ci-dessous. Vous devriez voir une liste de toutes les visualisations publiques/partagées ainsi que vos visualisations privées.

GET /api/visualizations.json

Si vous souhaitez extraire la définition JSON d'une visualisation spécifique, vous pouvez ajouter son identifiant respectif à l'URL :

GET /api/visualizations/hQxZGXqnLS9.json

La représentation suivante est un exemple de réponse au format JSON (par souci de concision, certaines informations ont été supprimées). Pour obtenir le schéma complet, veuillez utiliser GET /api/schemas/visualization.

{
  "lastUpdated": "2020-02-06T11:57:09.678",
  "href": "http://my-domain/dhis/api/visualizations/hQxZGXqnLS9",
  "id": "hQxZGXqnLS9",
  "created": "2017-05-19T17:22:00.785",
  "name": "ANC: ANC 1st visits last 12 months cumulative values",
  "publicAccess": "rw------",
  "userOrganisationUnitChildren": false,
  "type": "LINE",
  "access": {},
  "reportingParams": {
    "parentOrganisationUnit": false,
    "reportingPeriod": false,
    "organisationUnit": false,
    "grandParentOrganisationUnit": false
  },
  "dataElementGroupSetDimensions": [],
  "attributeDimensions": [],
  "yearlySeries": [],
  "axes": [
    {
      "index": 0,
      "type": "RANGE",
      "title": {
        "textMode": "CUSTOM",
        "text": "Any Title"
      }
    }
  ],
  "filterDimensions": [
    "dx"
  ],
  "columns": [
    {
      "id": "ou"
    }
  ],
  "dataElementDimensions": [],
  "categoryDimensions": [],
  "rowDimensions": [
    "pe"
  ],
  "columnDimensions": [
    "ou"
  ],
  "dataDimensionItems": [
    {
      "dataDimensionItemType": "DATA_ELEMENT",
      "dataElement": {
        "id": "fbfJHSPpUQD"
      }
    }
  ],
  "filters": [
    {
      "id": "dx"
    }
  ],
  "rows": [
    {
      "id": "pe"
    }
  ]
}

GET /api/visualizations/hQxZGXqnLS9.json?fields=interpretations

renvoie

{
  "interpretations": [
    {
      "id": "Lfr8I2RPU0C"
    },
    {
      "id": "JuwgdJlJPGb"
    },
    {
      "id": "WAoU2rSpyZp"
    }
  ]
}

Comme on peut le voir, le GET ci-dessus ne renverra que les interprétations liées à l'identifiant donné (dans ce cas hQxZGXqnLS9).

Créer, mettre à jour et supprimer des visualisations¶

Ces opérations suivent la sémantique standard REST. Une nouvelle visualisation peut être créée par une requête POST à la ressource /api/visualisations avec une charge JSON valide. Un exemple de charge pourrait être :

{
  "columns": [
    {
      "dimension": "J5jldMd8OHv",
      "items": [
        {
          "name": "CHP",
          "id": "uYxK4wmcPqA",
          "displayName": "CHP",
          "displayShortName": "CHP",
          "dimensionItemType": "ORGANISATION_UNIT_GROUP"
        },
        {
          "name": "Hospital",
          "id": "tDZVQ1WtwpA",
          "displayName": "Hospital",
          "displayShortName": "Hospital",
          "dimensionItemType": "ORGANISATION_UNIT_GROUP"
        }
      ]
    }
  ],
  "rows": [
    {
      "dimension": "SooXFOUnciJ",
      "items": [
        {
          "name": "DOD",
          "id": "B0bjKC0szQX",
          "displayName": "DOD",
          "displayShortName": "DOD",
          "dimensionItemType": "CATEGORY_OPTION_GROUP"
        },
        {
          "name": "CDC",
          "id": "OK2Nr4wdfrZ",
          "displayName": "CDC",
          "displayShortName": "CDC",
          "dimensionItemType": "CATEGORY_OPTION_GROUP"
        }
      ]
    }
  ],
  "filters": [
    {
      "dimension": "ou",
      "items": [
        {
          "name": "Sierra Leone",
          "id": "ImspTQPwCqd",
          "displayName": "Sierra Leone",
          "displayShortName": "Sierra Leone",
          "dimensionItemType": "ORGANISATION_UNIT"
        },
        {
          "name": "LEVEL-1",
          "id": "LEVEL-H1KlN4QIauv",
          "displayName": "LEVEL-1"
        }
      ]
    }
  ],
  "name": "HIV Cases Monthly",
  "description": "Cases of HIV across the months",
  "category": "XY1vwCQskjX",
  "showDimensionLabels": true,
  "hideEmptyRows": true,
  "hideEmptyColumns": true,
  "skipRounding": true,
  "aggregationType": "SUM",
  "regressionType": "LINEAR",
  "type": "PIVOT_TABLE",
  "numberType": "VALUE",
  "measureCriteria": "Some criteria",
  "showHierarchy": true,
  "completedOnly": true,
  "displayDensity": "NORMAL",
  "fontSize": "NORMAL",
  "digitGroupSeparator": "SPACE",
  "legendDisplayStyle": "FILL",
  "legendDisplayStrategy": "FIXED",
  "hideEmptyRowItems": "BEFORE_FIRST_AFTER_LAST",
  "fixColumnHeaders": true,
  "fixRowHeaders": false,
  "regression": false,
  "cumulative": true,
  "sortOrder": 1,
  "topLimit": 2,
  "rowTotals": true,
  "colTotals": true,
  "hideTitle": true,
  "hideSubtitle": true,
  "hideLegend": true,
  "showData": true,
  "percentStackedValues": true,
  "noSpaceBetweenColumns": true,
  "rowSubTotals": true,
  "colSubTotals": true,
  "userOrgUnitType": "TEI_SEARCH",
  "externalAccess": false,
  "publicAccess": "--------",
  "reportingParams": {
    "reportingPeriod": true,
    "organisationUnit": true,
    "parentOrganisationUnit": true,
    "grandParentOrganisationUnit": true
  },
  "parentGraphMap": {
    "ImspTQPwCqd": ""
  },
  "access": {
    "read": true,
    "update": true,
    "externalize": true,
    "delete": false,
    "write": true,
    "manage": false
  },
  "optionalAxes": [
    {
      "dimensionalItem": "fbfJHSPpUQD",
      "axis": 1
    },
    {
      "dimensionalItem": "cYeuwXTCPkU",
      "axis": 2
    }
  ],
  "relativePeriods": {
    "thisYear": false,
    "quartersLastYear": true,
    "last52Weeks": false,
    "thisWeek": false,
    "lastMonth": false,
    "last14Days": false,
    "biMonthsThisYear": false,
    "monthsThisYear": false,
    "last2SixMonths": false,
    "yesterday": false,
    "thisQuarter": false,
    "last12Months": false,
    "last5FinancialYears": false,
    "thisSixMonth": false,
    "lastQuarter": false,
    "thisFinancialYear": false,
    "last4Weeks": false,
    "last3Months": false,
    "thisDay": false,
    "thisMonth": false,
    "last5Years": false,
    "last6BiMonths": false,
    "last4BiWeeks": false,
    "lastFinancialYear": false,
    "lastBiWeek": false,
    "weeksThisYear": false,
    "last6Months": false,
    "last3Days": false,
    "quartersThisYear": false,
    "monthsLastYear": false,
    "lastWeek": false,
    "last7Days": false,
    "thisBimonth": false,
    "lastBimonth": false,
    "lastSixMonth": false,
    "thisBiWeek": false,
    "lastYear": false,
    "last12Weeks": false,
    "last4Quarters": false
  },
  "user": {},
  "yearlySeries": [
    "THIS_YEAR"
  ],
  "userGroupAccesses": [
    {
      "access": "rwx-----",
      "userGroupUid": "ZoHNWQajIoe",
      "displayName": "Bo District M&E officers",
      "id": "ZoHNWQajIoe"
    }
  ],
  "userAccesses": [
    {
      "access": "--------",
      "displayName": "John Barnes",
      "id": "DXyJmlo9rge",
      "userUid": "DXyJmlo9rge"
    }
  ],
  "legendSet": {
    "name": "Death rate up",
    "id": "ham2eIDJ9k6",
    "legends": [
      {
        "startValue": 1,
        "endValue": 2,
        "color": "red",
        "image": "some-image"
      },
      {
        "startValue": 2,
        "endValue": 3,
        "color": "blue",
        "image": "other-image"
      }
    ]
  },
  "outlierAnalysis": {
    "enabled": true,
    "outlierMethod": "IQR",
    "thresholdFactor": 1.5,
    "normalizationMethod": "Y_RESIDUALS_LINEAR",
    "extremeLines": {
      "enabled": true,
      "value": 3.5
    }
  },
  "legend": {
    "strategy": "FIXED",
    "style": "FILL",
    "set": {
      "id": "fqs276KXCXi",
      "displayName": "ANC Coverage"
    },
    "showKey": false
  },
  "seriesKey": {
    "hidden": true,
    "label": {
      "fontStyle": {
        "textColor": "#cccddd"
      }
    }
  },
  "axes": [
    {
      "index": 0,
      "type": "RANGE",
      "label": {
        "fontStyle": {
          "textColor": "#cccddd"
        }
      },
      "title": {
        "text": "Range axis title",
        "textMode": "CUSTOM",
        "fontStyle": {
          "textColor": "#000000"
        }
      },
      "decimals": 1,
      "maxValue": 100,
      "minValue": 20,
      "steps": 5,
      "baseLine": {
        "value": 50,
        "title": {
          "text": "My baseline",
          "fontStyle": {
            "textColor": "#000000"
          }
        }
      },
      "targetLine": {
        "value": 80,
        "title": {
          "text": "My targetline",
          "fontStyle": {
            "textColor": "#cccddd"
          }
        }
      }
    },
    {
      "index": 1,
      "type": "DOMAIN",
      "label": {
        "fontStyle": {
          "textColor": "#000000"
        }
      },
      "title": {
        "text": "Domain axis title",
        "textMode": "CUSTOM",
        "fontStyle": {
          "textColor": "#cccddd"
        }
      }
    }
  ],
  "axes": [
    {
      "index": 0,
      "type": "RANGE",
      "label": {
        "fontStyle": {
          "textColor": "#cccddd"
        }
      },
      "title": {
        "text": "Range axis title",
        "fontStyle": {
          "textColor": "#000000"
        }
      },
      "decimals": 1,
      "maxValue": 100,
      "minValue": 20,
      "steps": 5,
      "baseLine": {
        "value": 50,
        "title": {
          "text": "My baseline",
          "fontStyle": {
            "textColor": "#000000"
          }
        }
      },
      "targetLine": {
        "value": 80,
        "title": {
          "text": "My targetline",
          "fontStyle": {
            "textColor": "#cccddd"
          }
        }
      }
    },
    {
      "index": 1,
      "type": "DOMAIN",
      "label": {
        "fontStyle": {
          "textColor": "#000000"
        }
      },
      "title": {
        "text": "Domain axis title",
        "fontStyle": {
          "textColor": "#cccddd"
        }
      }
    }
  ]
}

Pour mettre à jour une visualisation spécifique, vous pouvez envoyer une requête PUT à la même ressource /api/visualisations avec une charge similaire PLUS l'identifiant de la visualisation respective, par exemple :

PUT /api/visualizations/hQxZGXqnLS9

Enfin, pour supprimer une visualisation existante, vous pouvez faire une requête DELETE en spécifiant l'identifiant de la visualisation à supprimer, comme indiqué :

DELETE /api/visualizations/hQxZGXqnLS9

Visualisation des événements¶

L'API EventVisualization (visualisation d'événements) est conçue pour aider les clients à interagir avec les graphiques et les rapports d'événements. Les endpoints de cette API sont utilisés par l'application Event Visualization qui permet la création, la configuration et la gestion de graphiques et de rapports basés sur les paramètres définis par le client. L'idée principale est de permettre aux clients et aux utilisateurs de disposer d'une API unique et centralisée fournissant tous les types de graphiques et de rapports d'événements ainsi que des paramètres et une configuration spécifiques pour chaque type de visualisation d'événement. Cette API a été introduite dans le but d'unifier les API eventCharts (graphiques d'événements) et eventReports (rapports d'événements) et de les remplacer entièrement en faveur de l'API eventVisualizations (ce qui signifie que l'utilisation des API eventCharts (graphiques d'événements) et eventReports (rapports d'événements) devrait être évitée). En résumé, les ressources/API suivantes : /api/eventCharts, /api/eventReports sont remplacées par /api/eventVisualizations

Remarque

Les nouvelles applications et les nouveaux clients doivent éviter d'utiliser les API eventCharts (graphiques d'événements) et eventReports (rapports d'événements) car elles sont obsolètes. Utilisez plutôt l'API eventVisualizations (visualisations d'événements).

Un objet EventVisualization (visualisation d'événements) est composé de nombreux attributs (certains liés à la création de graphiques et d'autres à la création de rapports), mais les plus importants, qui reflètent les informations essentielles de l'objet, sont les suivants : * "identifiant", "nom", "type", "éléments de données de dimension ", " colonnes ", " lignes " et " filtres ".* Le endpoint racine de l'API est /api/eventVisualizations, et la liste des attributs et éléments actuels est décrite dans le tableau ci-dessous.

Tableau : Attributs de la visualisation d'événements

Récupération de visualisations d'événements¶

Pour récupérer une liste de toutes les visualisations d'événements existantes, au format JSON, avec quelques informations de base (y compris l'identifiant, le nom et la pagination), vous pouvez faire une requête GET à l'URL ci-dessous. Vous devriez voir une liste de toutes les visualisations d'événements publiques/partagées ainsi que vos visualisations privées. GET /api/eventVisualizations.json Si vous souhaitez extraire la définition JSON d'une visualisation d'événement spécifique, vous pouvez ajouter son identifiant respectif à l'URL : GET /api/eventVisualizations/hQxZGXqnLS9.json La représentation suivante est un exemple de réponse au format JSON (par souci de concision, certaines informations ont été supprimées). Pour obtenir le schéma complet, veuillez utiliser GET /api/schemas/eventVisualization.

{
    "lastUpdated": "2021-11-25T17:18:03.834",
    "href": "http://localhost:8080/dhis/api/eventVisualizations/EZ5jbRTxRGh",
    "id": "EZ5jbRTxRGh",
    "created": "2021-11-25T17:18:03.834",
    "name": "Inpatient: Mode of discharge by facility type this year",
    "publicAccess": "rw------",
    "userOrganisationUnitChildren": false,
    "type": "STACKED_COLUMN",
    "subscribed": false,
    "userOrganisationUnit": false,
    "rowSubTotals": false,
    "cumulativeValues": false,
    "showDimensionLabels": false,
    "sortOrder": 0,
    "favorite": false,
    "topLimit": 0,
    "collapseDataDimensions": false,
    "userOrganisationUnitGrandChildren": false,
    "displayName": "Inpatient: Mode of discharge by facility type this year",
    "percentStackedValues": false,
    "noSpaceBetweenColumns": false,
    "showHierarchy": false,
    "hideTitle": false,
    "showData": true,
    "hideEmptyRows": false,
    "hideNaData": false,
    "regressionType": "NONE",
    "completedOnly": false,
    "colTotals": false,
    "sharing": {
      "owner": "GOLswS44mh8",
      "external": false,
      "users": {},
      "userGroups": {},
      "public": "rw------"
    },
    "programStatus": "CANCELLED",
    "hideEmptyRowItems": "NONE",
    "hideSubtitle": false,
    "outputType": "EVENT",
    "hideLegend": false,
    "externalAccess": false,
    "colSubTotals": false,
    "rowTotals": false,
    "digitGroupSeparator": "SPACE",
    "program": {
      "id": "IpHINAT79UW"
    },
    "access": {
      "read": true,
      "update": true,
      "externalize": true,
      "delete": true,
      "write": true,
      "manage": true
    },
    "lastUpdatedBy": {
      "displayName": "John Traore",
      "name": "John Traore",
      "id": "xE7jOejl9FI",
      "username": "admin"
    },
    "relativePeriods": {
      "thisYear": false,
      ...
    },
    "programStage": {
      "id": "A03MvHHogjR"
    },
    "createdBy": {
      "displayName": "Tom Wakiki",
      "name": "Tom Wakiki",
      "id": "GOLswS44mh8",
      "username": "system"
    },
    "user": {
      "displayName": "Tom Wakiki",
      "name": "Tom Wakiki",
      "id": "GOLswS44mh8",
      "username": "system"
    },
    "attributeDimensions": [],
    "translations": [],
    "legend": {
      "set": {
        "id": "gFJUXah1uRH"
      },
      "showKey": false,
      "style": "FILL",
      "strategy": "FIXED"
    },
    "filterDimensions": [
      "ou",
      "H6uSAMO5WLD"
    ],
    "interpretations": [],
    "userGroupAccesses": [],
    "subscribers": [],
    "columns": [
      {
        "id": "X8zyunlgUfM"
      }
    ]
    "periods": [],
    "categoryDimensions": [],
    "rowDimensions": [
      "pe"
    ],
    "itemOrganisationUnitGroups": [],
    "programIndicatorDimensions": [],
    "attributeValues": [],
    "columnDimensions": [
      "X8zyunlgUfM"
    ],
    "userAccesses": [],
    "favorites": [],
    "dataDimensionItems": [],
    "categoryOptionGroupSetDimensions": [],
    "organisationUnitGroupSetDimensions": [],
    "organisationUnitLevels": [],
    "organisationUnits": [
      {
        "id": "ImspTQPwCqd"
      }
    ],
    "filters": [
      {
        "id": "ou"
      },
      {
        "id": "H6uSAMO5WLD"
      }
    ],
    "rows": [
      {
        "id": "pe"
      }
    ]
}

Une réponse plus personnalisée peut être obtenue en spécifiant, dans l'URL, les champs que vous souhaitez extraire. Par exemple: GET /api/eventVisualizations/hQxZGXqnLS9.json?fields=interpretations renverra

{
  "interpretations": [
    {
      "id": "Lfr8I2RPU0C"
    },
    {
      "id": "JuwgdJlJPGb"
    },
    {
      "id": "WAoU2rSpyZp"
    }
  ]
}

Comme on peut le voir, le GET ci-dessus ne renverra que les interprétations liées à l'identifiant donné (dans ce cas hQxZGXqnLS9).

Créer, mettre à jour et supprimer des visualisations d'événements¶

Ces opérations suivent la sémantique REST standard. Une nouvelle visualisation d'événement peut être créée par une requête POST à la ressource /api/eventVisualizations avec une charge JSON valide. Un exemple de charge pourrait être :

{
    "name": "Inpatient: Cases under 10 years last 4 quarters",
    "publicAccess": "rw------",
    "userOrganisationUnitChildren": false,
    "type": "STACKED_COLUMN",
    "subscribed": false,
    "userOrganisationUnit": false,
    "rowSubTotals": false,
    "cumulativeValues": false,
    "showDimensionLabels": false,
    "sortOrder": 0,
    "favorite": false,
    "topLimit": 0,
    "collapseDataDimensions": false,
    "userOrganisationUnitGrandChildren": false,
    "displayName": "Inpatient: Cases under 10 years last 4 quarters",
    "percentStackedValues": false,
    "noSpaceBetweenColumns": false,
    "showHierarchy": false,
    "hideTitle": false,
    "showData": true,
    "hideEmptyRows": false,
    "userAccesses": [],
    "userGroupAccesses": [],
    "hideNaData": false,
    "regressionType": "NONE",
    "completedOnly": false,
    "colTotals": false,
    "programStatus": "CANCELLED",
    "sharing": {
      "owner": "GOLswS44mh8",
      "external": false,
      "users": {},
      "userGroups": {},
      "public": "rw------"
    },
    "displayFormName": "Inpatient: Cases under 10 years last 4 quarters",
    "hideEmptyRowItems": "NONE",
    "hideSubtitle": false,
    "outputType": "EVENT",
    "hideLegend": false,
    "externalAccess": false,
    "colSubTotals": false,
    "rowTotals": false,
    "digitGroupSeparator": "SPACE",
    "access": {
      "read": true,
      "update": true,
      "externalize": false,
      "delete": true,
      "write": true,
      "manage": true
    },
    "lastUpdatedBy": {
      "displayName": "Tom Wakiki",
      "name": "Tom Wakiki",
      "id": "GOLswS44mh8",
      "username": "system"
    },
    "legend": {
      "set": {
        "id": "gFJUXah1uRH"
      },
      "showKey": false,
      "style": "FILL",
      "strategy": "FIXED"
    },
    "relativePeriods": {
      "thisYear": false,
    ...
    },
    "program": {
      "id": "IpHINAT79UW",
      "enrollmentDateLabel": "Date of enrollment",
      "incidentDateLabel": "Date of birth",
      "name": "Child Programme"
    },
    "programStage": {
      "id": "A03MvHHogjR",
      "executionDateLabel": "Report date",
      "name": "Birth"
    },
    "createdBy": {
      "displayName": "Tom Wakiki",
      "name": "Tom Wakiki",
      "id": "GOLswS44mh8",
      "username": "system"
    },
    "user": {
      "displayName": "Tom Wakiki",
      "name": "Tom Wakiki",
      "id": "GOLswS44mh8",
      "username": "system"
    },
    "translations": [],
    "filterDimensions": [
      "ou"
    ],
    "interpretations": [],
    "dataElementDimensions": [
      {
        "filter": "LE:10",
        "dataElement": {
          "id": "qrur9Dvnyt5"
        }
      }
    ],
    "periods": [],
    "categoryDimensions": [],
    "rowDimensions": [
      "pe"
    ],
    "columnDimensions": [
      "qrur9Dvnyt5"
    ],
    "organisationUnits": [
      {
        "id": "ImspTQPwCqd"
      }
    ],
    "filters": [
      {
        "dimension": "ou",
        "items": [
          {
            "id": "ImspTQPwCqd"
          }
        ]
      },
      {
        "dimension": "H6uSAMO5WLD",
        "items": []
      }
    ],
    "columns": [
      {
        "dimension": "X8zyunlgUfM",
        "items": [],
        "repetition": {
          "indexes": [1, 2, 3, -2, -1, 0]
        }
      },
      {
        "dimension": "eventDate",
        "items": [
          {
            "id": "2021-07-21_2021-08-01"
          },
          {
            "id": "2021-01-21_2021-02-01"
          }
        ]
      },
      {
        "dimension": "incidentDate",
        "items": [
          {
            "id": "2021-10-01_2021-10-30"
          }
        ]
      },
      {
        "dimension": "eventStatus",
        "items": [
          {
            "id": "ACTIVE"
          },
          {
            "id": "COMPLETED"
          }
        ]
      },
      {
        "dimension": "createdBy",
        "items": [
          {
            "id": "userA"
          }
        ]
      },
      {
        "dimension": "lastUpdatedBy",
        "items": [
          {
            "id": "userB"
          }
        ]
      }
    ],
    "rows": [
      {
        "dimension": "pe",
        "items": [
          {
            "id": "LAST_12_MONTHS"
          }
        ]
      }
    ]
}

Pour le maintien du multi-programme, la racine programme ne doit pas être spécifiée. Cela transformera la visualisation d'événement en un multi-programme. Par conséquent, nous devons spécifier le programme et l' étape du programme (le cas échéant) pour chaque dimension dans les lignes, les colonnes et les filtres.

Exemple:

"program": null,
"columns": [
  {
    "dimension": "ou",
    "items": [
        {
            "id": "O6uvpzGd5pu"
        }
    ],
    "program": {
        "id": "IpHINAT79UW"
    }
  },
  {
    "dimensionType": "CATEGORY_OPTION_GROUP_SET",
    "items": [
      {
          "id": "JLGV7lRQRAg"
      },
      {
          "id": "p916ZCVGNyq"
      }
    ],
    "dimension": "C31vHZqu0qU",
    "program": {
        "id": "kla3mAPgvCH"
    },
    "programStage": {
        "id": "aNLq9ZYoy9W"
    }
  }
]

Remarque

L'attribut répétition (dans lignes, colonnes ou filtres) indique les index d'événements à récupérer. En reprenant l'exemple ci-dessus (dans la charge json précédente), on peut le lire comme suit:

1 = Premier événement
2 = Deuxième événement
3 = Troisième événement
...
-2 = Troisième événement le plus récent
-1 = Deuxième événement le plus récent
0 = Dernier événement (par défaut)

Pour mettre à jour une visualisation d'événement spécifique, vous pouvez envoyer une requête PUT à la même ressource /api/eventVisualizations avec une charge similaire PLUS l'identifiant de la visualisation d'événement respective, par exemple : PUT /api/eventVisualizations/hQxZGXqnLS9 Enfin, pour supprimer une visualisation d'événement existante, vous pouvez effectuer une requête DELETE en spécifiant l'identifiant de la visualisation d'événement à supprimer, comme indiqué ci-dessous : DELETE /api/eventVisualizations/hQxZGXqnLS9

Interprétations¶

Pour les ressources liées à l'analyse des données dans DHIS2, telles que les visualisations, les cartes, les rapports d'événements, les graphiques d'événements et même les visualisations, vous pouvez écrire et partager des interprétations de données. Une interprétation peut être un commentaire, une question, une observation ou une interprétation concernant un rapport de données ou une visualisation.

/api/interpretations

Lire les interprétations¶

Pour lire les interprétations, nous allons interagir avec la ressource /api/interpretations. Une requête GET typique utilisant le filtrage des champs peut ressembler à ceci :

GET /api/interpretations?fields=*,comments[id,text,user,mentions]

La réponse au format JSON pourrait ressembler à ce qui suit (les champs supplémentaires ont été omis par souci de concision) :

{
  "interpretations": [
    {
      "id": "XSHiFlHAhhh",
      "created": "2013-05-30T10:24:06.181+0000",
      "text": "Data looks suspicious, could be a data entry mistake.",
      "type": "MAP",
      "likes": 2,
      "user": {
        "id": "uk7diLujYif"
      },
      "reportTable": {
        "id": "LcSxnfeBxyi"
      },
      "visualization": {
        "id": "LcSxnfeBxyi"
      }
    }, {
      "id": "kr4AnZmYL43",
      "created": "2013-05-29T14:47:13.081+0000",
      "text": "Delivery rates in Bo looks high.",
      "type": "VISUALIZATION",
      "likes": 3,
      "user": {
        "id": "uk7diLujYif"
      },
      "visualization": {
        "id": "HDEDqV3yv3H"
      },
      "mentions": [
        {
          "created": "2018-06-25T10:25:54.498",
          "username": "boateng"
        }
      ],
      "comments": [
        {
          "id": "iB4Etq8yTE6",
          "text": "This report indicates a surge.",
          "user": {
            "id": "B4XIfwOcGyI"
          }
        },
        {
          "id": "iB4Etq8yTE6",
          "text": "Likely caused by heavy rainfall.",
          "user": {
            "id": "B4XIfwOcGyI"
          }
        },
        {
          "id": "SIjkdENan8p",
          "text": "Have a look at this @boateng.",
          "user": {
            "id": "xE7jOejl9FI"
          },
          "mentions": [
            {
              "created": "2018-06-25T10:03:52.316",
              "username": "boateng"
            }
          ]
        }
      ]
    }
  ]
}

Tableau : Champs d'interprétation

Pour tous les objets analytiques, vous pouvez ajouter / données à l'URL pour récupérer les données associées à la ressource (par opposition aux métadonnées). Par exemple, en suivant le lien de la carte et en ajoutant / données, on peut récupérer une représentation PNG (image) de la carte thématique par l'intermédiaire de l'URL suivante :

https://play.dhis2.org/demo/api/maps/bhmHJ4ZCdCd/data

Pour tous les objets analytiques, vous pouvez filtrer par mentions. Pour récupérer toutes les interprétations/commentaires où un utilisateur a été mentionné, vous avez trois options. Vous pouvez filtrer par les mentions d'interprétation (mentions dans la description de l'interprétation) :

GET /api/interpretations?fields=*,comments[*]&filter=mentions.username:in:[boateng]

Vous pouvez filtrer les commentaires d'interprétation en fonction des mentions (mentions dans n'importe quel commentaire) :

GET /api/interpretations?fields=*,comments[*]
  &filter=comments.mentions.username:in:[boateng]

Vous pouvez filtrer les interprétations qui contiennent les mentions soit dans l'interprétation ou dans un commentaire ( OU jonction) :

GET /api/interpretations?fields=*,comments[*]&filter=mentions:in:[boateng]

Écrire les interprétations¶

Lorsque vous écrivez des interprétations, vous fournissez le texte de l'interprétation dans le corps de la requête en utilisant une requête POST avec un contenu de type « text/plain ». Le modèle d'URL ressemble à ce qui suit, où {object-type} fait référence au type de l'objet interprété et {object-id} fait référence à l'identifiant de l'objet interprété.

/api/interpretations/{object-type}/{object-id}

Les options valides pour le type d'objet sont visualisation, carte, rapport d'événement, graphique d'événement, visualisation d'événement et rapport d'ensemble de données.

Quelques exemples pertinents d'interprétations sont énumérés ci-dessous.

Remarque

Les API eventCharts (graphiques d'événements) et eventReports (rapports d'événements) sont obsolètes. Nous recommandons d'utiliser l'API eventVisualizations (visualisations d'événements) à la place.

/api/interpretations/visualization/hQxZGXqnLS9
/api/interpretations/map/FwLHSMCejFu
/api/interpretations/eventReport/xJmPLGP3Cde
/api/interpretations/eventChart/nEzXB2M9YBz
/api/interpretations/eventVisualization/nEzXB2M9YBz
/api/interpretations/dataSetReport/tL7eCjmDIgM

A titre d'exemple, nous commencerons par écrire une interprétation pour la visualisation avec l'identifiant EbRN2VIbPdV. Pour écrire des interprétations de visualisation, nous allons interagir avec la ressource /api/interpretations/visualization/{visualizationId}. L'interprétation sera le corps de la requête. Sur cette base, nous pouvons formuler la requête suivante en utilisant cURL :

curl -d "Cette visualisation montre un abandon important de la CPN 1-3" -X POST
  "https://play.dhis2.org/demo/api/interpretations/visualization/EbRN2VIbPdV" -H "Content-Type:text/plain" -u admin:district

Notez que la réponse fournit un en-tête de Localisation avec une valeur indiquant l'emplacement de l'interprétation créée. Ceci est utile du point de vue du client lorsque vous souhaitez ajouter un commentaire à interprétation.

Mise à jour et suppression d'interprétations¶

Pour mettre à jour une interprétation existante, vous pouvez utiliser une requête PUT dont le texte de l'interprétation est le corps de la requête, qui utilise le modèle d'URL suivant, dans lequel {id} fait référence à l'identifiant de l'interprétation :

/api/interpretations/{id}

Sur cette base, nous pouvons utiliser curl pour mettre à jour l'interprétation :

curl -d "Cette visualisation montre un taux d'abandon élevé" -X PUT
  "https://play.dhis2.org/demo/api/interpretations/visualization/EV08iI1cJRA" -H "Content-Type:text/plain" -u admin:district

Vous pouvez utiliser le même modèle d'URL que ci-dessus en utilisant une requête DELETE pour supprimer l'interprétation.

Création des commentaires d'interprétation¶

Lorsque vous écrivez des commentaires sur les interprétations, vous fournissez le texte du commentaire dans le corps de la requête en utilisant une requête POST avec le type de contenu « text/plain ». Le modèle d'URL ressemble à ce qui suit, où {interpretation-id} fait référence à l'identifiant de l'interprétation.

/api/interpretations/{interpretation-id}/comments

Deuxièmement, nous allons rédiger un commentaire à l'interprétation que nous avons écrite dans l'exemple ci-dessus. En regardant la réponse de l'interprétation, vous verrez qu'un en-tête Localisation est renvoyé. Cet en-tête nous indique l'URL de l'interprétation nouvellement créée et, à partir de là, nous pouvons lire son identifiant. Cet identifiant est généré de manière aléatoire, vous devrez donc remplacer celui de la commande ci-dessous par le vôtre. Pour écrire un commentaire, nous pouvons interagir avec la ressource /api/interpretations/{id}/comments comme ceci :

curl -d "Une intervention est nécessaire" -X POST
  "https://play.dhis2.org/demo/api/interpretations/j8sjHLkK8uY/comments"
  -H "Content-Type:text/plain" -u admin:district

Mise à jour et suppression des commentaires d'interprétation¶

Pour mettre à jour un commentaire d'interprétation, vous pouvez utiliser une requête PUT où le texte du commentaire est le corps de la requête en utilisant le modèle d'URL suivant :

/api/interpretations/{interpretation-id}/comments/{comment-id}

Sur cette base, nous pouvons utiliser curl pour mettre à jour le commentaire :

curl "https://play.dhis2.org/demo/api/interpretations/j8sjHLkK8uY/comments/idAzzhVWvh2"
  -d "Je suis d'accord." -X PUT -H "Content-Type:text/plain" -u admin:district

Vous pouvez utiliser le même modèle d'URL que ci-dessus en utilisant une requête DELETE pour supprimer le commentaire d'interprétation.

Comment aimer les interprétations¶

Pour aimer une interprétation, vous pouvez utiliser une requête POST vide vers la ressource like :

POST /api/interpretations/{id}/like

Un like sera ajouté pour l'utilisateur actuellement authentifié. Un utilisateur ne peut aimer une interprétation qu'une seule fois.

Pour supprimer un « like » pour une interprétation, vous pouvez utiliser une requête DELETE à la même ressource que pour l'opération « like ».

Le statut d'une interprétation peut être visualisé en regardant la représentation ordinaire de l'API Web :

GET /api/interpretations/{id}

Les informations relatives aux appréciations se trouvent dans le champ likes (aimé), qui représente le nombre d'appréciations, et dans le tableau likedBy (aimé par), qui énumère les utilisateurs qui ont aimé l'interprétation.

{
  "id": "XSHiFlHAhhh",
  "text": "Data looks suspicious, could be a data entry mistake.",
  "type": "VISUALIZATION",
  "likes": 2,
  "likedBy": [
    {
      "id": "k7Hg12fJ2f1"
    },
    {
      "id": "gYhf26fFkjFS"
    }
  ]
}

Les vues SQL¶

La ressource des vues SQL vous permet de créer et d'extraire l'ensemble des résultats de vues SQL. Les vues SQL peuvent être exécutées directement dans la base de données et restituer l'ensemble des résultats par l'intermédiaire de la ressource Web API.

/api/sqlViews

Les vues SQL sont utiles dans la création de vues de données qui peuvent être plus facilement construites avec SQL qu'en combinant les multiples objets de l'API Web. Par exemple, supposons qu'il nous a été demandé de fournir une vue de toutes les unités d'organisation avec leur noms, les noms des parents, le niveau et le nom de l'unité d'organisation, ainsi que les coordonnées répertoriées dans la base de données. La vue pourrait ressembler à ceci :

select ou.name as orgunit, par.name as parent, ou.coordinates, ous.level, oul.name 
from organisationunit ou
inner join _orgunitstructure ous on ou.organisationunitid = ous.organisationunitid
inner join organisationunit par on ou.parentid = par.organisationunitid
inner join orgunitlevel oul on ous.level = oul.level
where ou.coordinates is not null
order by oul.level, par.name, ou.name;

Nous allons utiliser curl pour exécuter d'abord la vue sur le serveur de DHIS2. Il s'agit essentiellement d'un processus de matérialisation, qui garantit que les données les plus récentes sont disponibles dans la vue SQL lorsqu'elles sont récupérées sur le serveur. Vous pouvez d'abord rechercher la vue SQL dans la ressource api/sqlViews, puis faire un POST à l'aide de la commande suivante :

curl "https://play.dhis2.org/demo/api/sqlViews/dI68mLkP1wN/execute" -X POST -u admin:district

L'étape suivante du processus est la récupération des données. Le endpoint est disponible à l'adresse suivante:

/api/sqlViews/{id}/data(.csv)

Le chemin id représente l'identifiant de la vue SQL. L'extension du chemin fait référence au format de téléchargement des données. Ajoutez soit data pour les données JSON, soit data.csv pour les valeurs séparées par des virgules. Les formats de réponse supportés sont json, xml, csv, xls, html et html+css.

Par exemple, la commande suivante permet de récupérer des données CSV pour la vue SQL définie ci-dessus.

curl "https://play.dhis2.org/demo/api/sqlViews/dI68mLkP1wN/data.csv" -u admin:district

Il existe trois types de vues SQL :

• Vues SQL: Vues SQL standard.

• Vue SQL matérialisée: Les vues SQL matérialisées, c'est-à-dire écrites sur le disque, doivent être mises à jour pour refléter les modifications apportées aux tables sous-jacentes. Elles prennent en charge les critères permettant de filtrer l'ensemble des résultats.

• Requêtes SQL: Les requêtes SQL simples. Elles prennent en charge les variables en ligne pour les requêtes personnalisées.

Critère¶

Vous pouvez effectuer un filtrage simple sur les colonnes de l'ensemble de résultats en ajoutant des paramètres de requête critère à l'URL, en utilisant les noms de colonnes et les valeurs de filtrage séparées par les colonnes en tant que valeurs de paramètre, au format suivant :

/api/sqlViews/{id}/data?criteria=col1:value1&criteria=col2:value2

Par exemple, pour filtrer les résultats de la vue SQL ci-dessus afin de ne renvoyer que les unités d'organisation de niveau 4, vous pouvez utiliser l'URL suivante :

https://play.dhis2.org/demo/api/sqlViews/dI68mLkP1wN/data.csv?criteria=level:4

Les variables¶

Les vues SQL supportent la substitution de variables. La substitution de variables n'est disponible que pour les vues SQL de type requête, c'est-à-dire les vues SQL qui ne sont pas créées dans la base de données mais simplement exécutées comme des requêtes SQL normales. Les variables peuvent être insérées directement dans la requête SQL et doivent être dans ce format :

${variable-key}

Par exemple, une requête SQL qui récupère tous les éléments de données d'un type de valeur donné, où le type de valeur est défini par une variable, peut ressembler à ceci :

select * from dataelement where valuetype = '${valueType}';

Ces variables peuvent ensuite être fournies dans le cadre de l'URL lorsqu'elles sont demandées par l'intermédiaire de la ressource API Web sqlViews. Les variables peuvent être fournies dans le format suivant :

/api/sqlViews/{id}/data?var=key1:value1&var=key2:value2

Un exemple de requête correspondant à l'exemple ci-dessus peut se présenter comme suit :

/api/sqlViews/dI68mLkP1wN/data.json?var=valueType:int

La variable valueType sera remplacée par la valeur int et la requête renverra des éléments de données de type int.

Le paramètre variable ne doit contenir que des caractères alphanumériques. Les variables doivent contenir uniquement des caractères alphanumériques, des tirets, des traits de soulignement et des espaces.

Les vues SQL de type query prennent également en charge deux variables définies par le système qui permettent à la requête d'accéder à des informations sur l'utilisateur qui exécute la vue :

Les valeurs de ces variables ne peuvent pas être fournies dans le cadre de l'URL. Elles sont toujours remplies d'informations sur l'utilisateur.

Par exemple, la vue SQL suivante de type requête affiche toutes les unités d'organisation affectées à l'utilisateur :

select ou.path, ou.name
from organisationunit ou_user
join organisationunit ou on ou.path like ou_user.path || '%'
join usermembership um on um.organisationunitid = ou_user.organisationunitid
where um.userinfoid = ${_current_user_id}
order by ou.path;

Filtrage¶

L'API de vue SQL prend en charge le filtrage des données, au même titre que filtre_d'objet de métadonnées. Pour une liste complète des opérateurs de filtrage, vous pouvez consulter la documentation de filtre_d'objet de métadonnées.

Pour utiliser les filtres, il suffit de les ajouter en tant que paramètres à la fin de l'URL de demande de votre vue SQL, comme ceci. Cette requête renverra un résultat comprenant les unités d'organisation dont le nom contient « bo » au niveau 2 de la hiérarchie des unités d'organisation :

/api/sqlViews/w3UxFykyHFy/data.json?filter=orgunit_level:eq:2&filter=orgunit_name:ilike:bo

L'exemple suivant renverra toutes les unités d'org avec niveau_de l'unité d'organisation 2 ou 4 :

/api/sqlViews/w3UxFykyHFy/data.json?filter=orgunit_level:in:[2,4]

Et enfin, un exemple pour retourner toutes les unités d'organisation qui ne commencent pas par "Bo" :

/api/sqlViews/w3UxFykyHFy/data.json?filter=orgunit_name:!like:Bo

Éléments de données¶

Ce endpoint permet à l'utilisateur d'interroger les données relatives à quelques éléments dimensionnels différents. Ces éléments sont les suivants : INDICATEUR, ÉLÉMENT DE_DONNÉES, ENSEMBLE DE_DONNÉES, INDICATEUR DE_PROGRAMME, ÉLÉMENT DE_DONNÉES_DE PROGRAMME, ATTRIBUT DE_PROGRAMME. Le endpoint ne supporte que les requêtes GET et, comme les autres endpoints, peut renvoyer des réponses au format JSON ou XML.

L'URL est /api/dataItems et comme vous pouvez l'imaginer, il est possible de récupérer différents objets à travers le même endpoint dans la même requête GET. Pour cette raison, certains attributs disponibles pour les requêtes seront différents en fonction de l'élément dimensionnel interrogé.

Pour comprendre la déclaration ci-dessus, examinons les exemples de requête suivants :

1) GET /api/dataItems?filter=dimensionItemType:eq:DATA_ELEMENT&filter=valueType:eq:TEXT Dans cet exemple, le type d'élément ELEMENT_DE DONNÉES possède un attribut Type de valeur qui peut être utilisé dans la requête.

2) GET /api/dataItems?pageSize=50&order=displayName:asc&filter=dimensionItemType:eq:PROGRAM_INDICATOR&filter=displayName:ilike:someName&filter=programId:eq:WSGAb5XwJ3Y

Ici, le L'INDICATEUR DE_PROGRAMME permet de filtrer par identifiant de programme.

Ainsi, en se basant sur les exemples 1) et 2), si vous essayez de filtrer un ELEMENT DE_DONNEES par identifiant de programme ou de filtrer un INDICATEUR_DE PROGRAMME par type de valeur, vous n'obtiendrez aucun résultat. En d'autres termes, le filtre ne sera appliqué que si l'attribut existe réellement pour l'élément de données concerné.

Un autre aspect important à souligner est que ce endpoint ne suit PAS les mêmes normes de requête que d'autres endpoints existants, comme Filtre d'objet de métadonnées par exemple. En conséquence, il supporte un ensemble plus restreint de fonctionnalités et de requêtes. La raison principale en est la nécessité d'interroger plusieurs éléments différents ayant des relations différentes, ce qui n'est pas possible en utilisant les composants de filtrage existants (utilisés par les autres endpoints).

Réponses des endpoints¶

En fonction de la requête GET, les codes d'état et les réponses suivants peuvent être renvoyés.

Results found (status code 200)¶

{
  "pager": {
    "page": 1,
    "pageCount": 27,
    "total": 1339,
    "pageSize": 50
  },
  "dataItems": [
    {
      "simplifiedValueType": "TEXT",
      "displayName": "TB program Gender",
      "displayShortName": "TB prog. Gen.",
      "valueType": "TEXT",
      "name": "TB program Gender",
      "shortName": "TB prog Gen",
      "id": "ur1Edk5Oe2n.cejWyOfXge6",
      "programId": "ur1Edk5Oe2n",
      "dimensionItemType": "PROGRAM_ATTRIBUTE"
    }
  ]
}

Résultats non trouvés (code de statut 200)¶

{
  "pager": {
    "page": 1,
    "pageCount": 1,
    "total": 0,
    "pageSize": 50
  },
  "dataItems": [
  ]
}

Requête non valide (code de statut 409)¶

{
  "httpStatus": "Conflict",
  "httpStatusCode": 409,
  "status": "ERROR",
  "message": "Unable to parse element `INVALID_TYPE` on filter dimensionItemType`. The values available are: [INDICATOR, DATA_ELEMENT, DATA_ELEMENT_OPERAND, DATA_SET, PROGRAM_INDICATOR, PROGRAM_DATA_ELEMENT, PROGRAM_ATTRIBUTE]",
  "errorCode": "E2016"
}

Pagination¶

Ce endpoint supporte également la pagination en tant qu'option par défaut. Si nécessaire, vous pouvez désactiver la pagination en ajoutant paging=false à la requête GET, c'est-à-dire : /api/dataItems?filter=dimensionItemType:in :[INDICATOR]&paging=false.

Voici un exemple de charge lorsque la pagination est activée. N'oubliez pas que la pagination est l'option par défaut et qu'il n'est pas nécessaire de la définir explicitement.

{
  "pager": {
    "page": 1,
    "pageCount": 20,
    "total": 969,
    "pageSize": 50
  },
  "dataItems": [...]
}

Remarque

Pour les éléments auxquels un programme est associé, le nom du programme doit également être renvoyé en tant que partie du nom de l'élément (en tant que préfixe). La seule exception concerne les Indicateurs de programme. Nous ne préfixerons pas le nom de l'élément dans ce cas, afin de conserver le même comportement que les endpoints existants.

Le endpoint /dataItems n'apportera que des éléments de données qui sont définis comme étant de type agrégable. La liste actuelle des types agrégeables valides est la suivante : TEXTE, TEXTE_LONG, LETTRE, BOLÉEN, VRAI_UNIQUEMENT, NOMBRE, INTERVALLE_UNITAIRE, POURCENTAGE, ENTIER, ENTIER_POSITIF, ENTIER_NÉGATIF, ENTIER_ZÉRO_OU_POSITIF, COORDONNÉE.

Même si la réponse renvoie plusieurs attributs différents, le filtrage ne peut être appliqué qu'à certains d'entre eux : afficher le nom, le nom, le type de valeur, l'id, le type d'élément de dimension, l'id de programme.

L' ordre sera considéré comme invalide s'il est placé au-dessus de nom (ie. : ordre=nom:asc) et qu'un filtre est placé sur afficher le nom (ie. : filter=afficher le nom:ilike:aNom), et vice-versa.

Attributs de la réponse¶

Maintenant que nous avons une bonne idée des principales caractéristiques et de l'utilisation de ce endpoint , examinons la liste des attributs renvoyés dans la réponse.

Tableau : Attributs des éléments de données

Visualisation des représentations des ressources analytiques¶

DHIS2 dispose de plusieurs ressources pour l'analyse des données. Ces ressources comprennent les cartes, les visualisations, les visualisations d'événements, les rapports et les documents. En visitant ces ressources, vous obtiendrez des informations à leur sujet. Par exemple, en naviguant vers /api/visualisations/R0DVGvXDUNP, la réponse contiendra le nom, la dernière date de modification et ainsi de suite pour le graphique. Pour récupérer la représentation analytique, par exemple une représentation PNG de la visualisation, vous pouvez ajouter / données à toutes ces ressources. Par exemple, en visitant /api/visualisations/R0DVGvXDUNP/data, le système renverra une image PNG de la visualisation.

Tableau : Ressources analytiques

Le contenu des données des représentations analytiques peut être modifié en fournissant un paramètre de requête date. Pour cela, il faut que la ressource analytique soit configurée en périodes relatives pour la dimension période.

Tableau : Paramètres de requête de données

Tableau : Paramètres de requête pour les pngs / types d'images (visualisations, cartes)

Quelques exemples d'URL valides pour la récupération de diverses représentations analytiques sont énumérés ci-dessous.

/api/visualizations/R0DVGvXDUNP/data
/api/visualizations/R0DVGvXDUNP/data?date=2013-06-01

/api/visualizations/jIISuEWxmoI/data.html
/api/visualizations/jIISuEWxmoI/data.html?date=2013-01-01
/api/visualizations/FPmvWs7bn2P/data.xls
/api/visualizations/FPmvWs7bn2P/data.pdf

/api/eventVisualizations/x5FVFVt5CDI/data
/api/eventVisualizations/x5FVFVt5CDI/data.png

/api/maps/DHE98Gsynpr/data
/api/maps/DHE98Gsynpr/data?date=2013-07-01

/api/reports/OeJsA6K1Otx/data.pdf
/api/reports/OeJsA6K1Otx/data.pdf?date=2014-01-01