Position API verte : points de données

Modifié le Lun, 24 Nov. à 12:44 H

TABLE DES MATIÈRES

Détails
Propriétés d'un objet point de données
- Propriétés des métadonnées
Obtenir les données pour les points de données
Interroger les points de données dans l'API

Un point de données désigne les données soumises par un journaliste, présentées dans une structure plate.

Détails

Pour tenir compte des caractéristiques uniques du point de terminaison des données, qui diffère des autres points de terminaison contenant davantage de données, et pour éviter les problèmes évidents de redondance des données dans une structure plate (où les métadonnées sont répétées pour un ou plusieurs points de données), une solution de streaming est mise en œuvre.

Le flux renvoyé comprendra exclusivement les points de données comportant des valeurs, tandis que ceux sans valeur seront filtrés.

Propriétés d'un objet point de données

Propriétés des métadonnées

Propriété	Type de données	Description
OrgUnitPrettyId	chaîne	PrettyId de l'unité organisationnelle
Étiquette d'unité organisationnelle	chaîne	L'unité organisationnelle à laquelle appartiennent les données
Balises d'unité organisationnelle	Tableau de chaînes	Balises spécifiées sur une unité organisationnelle
Étiquette de l'année de référence	chaîne	Année de référence à laquelle appartient une immatriculation
Identifiant de l'année de référence	Guide	Année de déclaration à laquelle appartient une immatriculation
Nom de la période	chaîne	Le nom de l'enregistrement de période appartient à
PeriodMoniker	chaîne	Le nom suggère la période à laquelle appartient l'enregistrement.

Date de début de période	chaîne	Date de début de la période à laquelle appartient une inscription
Nom de l'aspect	chaîne	L'aspect auquel il appartient
Identifiant d'aspect	Guide	L'ID de l'aspect auquel il appartient
Nom de la mesure	chaîne	Le nom de la mesure
Identifiant de mesure	Guide	L'identifiant de la mesure
MesurerGlobalId	Guide ?	L'identifiant global de la mesure
MesurePrettyId	chaîne	PrettyId de la mesure

MesureTags	Tableau de chaînes	Une liste des balises appartenant à la mesure
Identifiant du point de mesure	Guide ?	L'identifiant du point de mesure
InscriptionResponsableEmail	chaîne	Adresse électronique du journaliste chargé de communiquer les données
Nom du responsable de l'enregistrement	chaîne	Nom complet du journaliste chargé de rapporter les données
InscriptionDernièreMiseÀJourUtc	long ?	Un horodatage Unix qui indique la date de la dernière mise à jour du point de données.
Inscription confirmée	bool	Le statut de confirmation de l'inscription

Propriétés des valeurs des points de données

Propriété	Type de données	Description
Balises de mesure	Tableau de chaînes	Une liste de balises. Ils peuvent être définis dans Measure Builder et constituent la méthode recommandée pour identifier un contrôle.
Type de contrôle	chaîne	Le type d'un contrôle appartient au point de données
Nom du contrôle de point de données	chaîne	Le nom du point de données. Peut être complexe avec des séparateurs !! si les points de données appartiennent au contrôle itératif.
Valeur d'affichage des données	chaîne	Nom affiché au journaliste
Unité de données	chaîne	L'unité des valeurs appartient au point de données.
Type de valeur de données	chaîne	Le type de la valeur. Utilisé comme discriminateur
Valeur des données	chaîne	Les données réelles du point de données
RowId	Guide	L'identifiant indiquant quels points de données appartiennent les uns aux autres. Également appelé « corrélation d'identifiant ».

Obtenir les données pour les points de données

/points de données

OBTENEZ L'https://api.positiongreen.com/v1/datapoints

Utile lors de la récupération de données pour un lac de données ou un système BI avec entrée facultative pour obtenir des enregistrements delta.

Le résultat est un ensemble de données plat et cohérent, enregistré et calculé dans Position Green.

Paramètres de requête

Nom	Type	Description
annéeId*	chaîne	Identifiant (GUID) de l'année - tel qu'indiqué dans /years Par exemple : 0f80635f-1215-400b-924a-e365cc601d31
mesureIds	chaîne[]	Liste des identifiants de mesures pour limiter le résultat à
mesurer les identifiants globaux	chaîne[]	Liste des identifiants de mesure globaux pour limiter le résultat à
orgUnitIds	chaîne[]	Liste des identifiants d'unité organisationnelle (GUID) permettant de filtrer les résultats.
orgUnitGlobalIds	chaîne[]	Liste des identifiants d'unité organisationnelle globale (GUID) permettant de filtrer les résultats.
inclure les enfants	bool	Indique s'il faut inclure les enfants des unités organisationnelles fournies dans la réponse. (Valeur par défaut = faux)
date de début	chaîne	Horodatage (ISO 8601) par exemple 2023-06-01T00:00:00+02:00
date de fin	chaîne	Horodatage (ISO 8601) par exemple 2023-08-31T23:59:59+02:0
dernière modification	numéro	Horodatage Unix
état de confirmation	chaîne	Voir confirmationState
sortDirection	chaîne	Voir tri, ci-dessous.
après	chaîne	Curseur utilisé pour aller à la page suivante
premier	numéro	Nombre d'inscriptions pour limiter la page à
dernière modification	numéro	horodatage Unix

200 : OK Réussi

Voir l'exemple de réponse ci-dessous

Exemple d'une requête curl

curl --location "<api url>/datapoints?yearId=<year_id>" --header "client_id: <client_id>" --header "client_secret: <clientsecret>" --no-buffer

En exécutant une requête cURL dans une console, il est possible d'observer que les données sont transmises depuis le point de terminaison.

Exemple de réponse « » (Réponse de la police)

Vous trouverez ci-dessous un exemple d'enregistrement comportant deux points de données distincts. Il est important de noter que si les métadonnées pour l'enregistrement restent les mêmes, les données pour chaque point de données diffèrent.

{
    "items": [
        {
            "cursor": "cGFnZTs5",
            "node": {
                "OrgUnitPrettyId": "SOME_PRETTY_ID",
                "OrgUnitLabel": « Organisation unit 1 »,
                « OrgUnitTags » : [« tag1 », « tag2 », « tag3 »],
                « ReportingYearLabel » : « 2023 »,
                « ReportingYearId » : « 9cagdfg31a-efg6-4747-9bjrt-49dc4e34563448 »,
                « PeriodName » : « January »,
                « PeriodMoniker » : « M1 »,
                « PeriodStartDate » : « 2023-01-31T00:00:00.0000000+01:00 »,
                « AspectName » : « Nom de l'aspect 1 »,
                « AspectId » : « e0265592-dsd7-44hf-b433-fd9a5ty3bdc7 »,
                « MeasureName » : « Nom de la mesure 1 »,
                « MeasureId » : « ed454f906-9999-48fc-9c44-420we65654f8 »,
                « MeasureGlobalId » : « 1hfghdeac5-c297-7gfd-95ad-4b43543534552 »,
                « MeasurePrettyId » : « Measure pretty name 1 »,
                « MeasureTags » : [« tag1 », « tag2 », « tag3 »],
                « MeasurePointId » : « 8basd90-d884-4asd8-8fads1-1a6da0e0df »,
                « MeasurePointTags » : [« tag1 », « tag2 », « tag3 »],
                « RegistrationResponsibleEmail » : « test+John.Doe+D310D6@testmail.com »,
                « RegistrationResponsibleName » : « John Doe »,
                « RegistrationLastUpdateUtc » : 1677680020228,
                « RegistrationConfirmed » : true,
                « ControlType » : « Number »,
                « DataPointControlName » : « measure_dfd »
                « DataDisplayValue » : « Résumé de la première mesure »,
                « DataUnit » : « ton »,
                « DataValueType » : « Numérique »,
                « DataValue » : « 0 »,
                « RowId » : null
            }
        }
        {
            "cursor": "cGFnZTs5",
             "node": {
                "OrgUnitPrettyId": "SOME_PRETTY_ID",
                "OrgUnitLabel": "Organisation unit 1",
                "OrgUnitTags": ["tag1", "tag2", "tag3"],
                « ReportingYearLabel » : « 2023 »,
                « ReportingYearId » : « 9cagdfg31a-efg6-4747-9bjrt-49dc4e34563448 »,
                « PeriodName » : « Janvier »,
                « PeriodMoniker » : « M1 »,
                « PeriodStartDate » : « 2023-01-31T00:00:00.0000000+01:00 »,
                « AspectName » : « Nom de l'aspect 1 »,
                « AspectId » : « e0265592-dsd7-44hf-b433-fd9a5ty3bdc7 »,
                « MeasureName » : « Nom de la mesure 1 »,
                « MeasureId » : « ed454f906-9999-48fc-9c44-420we65654f8 »,
                « MeasureGlobalId » : « 1hfghdeac5-c297-7gfd-95ad-4b43543534552 »,
                « MeasurePrettyId » : « Measure pretty name 1 »,
                « MeasureTags » : [« tag1 », « tag2 », « tag3 »],
                « MeasurePointId » : « 8basd90-d884-4asd8-8fads1-1a6da0e0df »,
                « MeasurePointTags » : [« tag1 », « tag2 », « tag3 »],
                « RegistrationResponsibleEmail » : « test+John.Doe+D310D6@testmail.com »,
                « RegistrationResponsibleName » : « John Doe »,
                « RegistrationLastUpdateUtc » : 1677680020228,
                « RegistrationConfirmed » : true,
                « ControlType » : « Number »,
                « DataPointControlName » : « measure_xyz »
                « DataDisplayValue » : « Résumé de la première mesure »,
                « DataUnit » : « m3 »,
                « DataValueType » : « Numérique »,
                « DataValue » : « 10 »,
                « RowId » : « 201b9192-e565-4680-ad64-30fd78dc4b6d »
            }
        }
    ],
    "totalCount": 1,
    "pageInfo": {
        "startCursor": "cGFnZTs5",
        "endCursor": "cGFnZTs5",
        "hasNextPage": true
    }
}

Interroger les points de données dans l'API

Lorsque vous effectuez une requête à l'aide des paramètres «startDate » et «endDate », les inscriptions pour lesquelles «periodEndDate » se situe dans la plage spécifiée seront renvoyées. Par exemple, si vous filtrez sur «startDate » comme « 2019-12-01 », vous recevrez toutes les inscriptions dont la «periodEndDate » est postérieure au 1er décembre 2019. Cela s'applique lorsque la mesure est configurée pour être déclarée chaque année, que la date de début de l'enregistrement est le 1er janvier 2019 et que la date de fin est le 31 décembre 2019, suivant une année civile.

Lors d'une requête utilisant les paramètres «lastModifiedStart » et «lastModifiedEnd », les inscriptions pour lesquelles «RegistrationLastUpdateUtc » se situe dans la plage spécifiée seront renvoyées. Ce paramètre fonctionne indépendamment des fuseaux horaires et offre une grande précision, permettant d'effectuer des requêtes même à l'échelle de la milliseconde.

Une requête utilisant le paramètre «confirmationState » permet de récupérer les inscriptions ayant un statut spécifique. Le paramètre « confirmationState » est un énuméré et la valeur par défaut est que seules les inscriptions confirmées seront renvoyées.

 public enum ConfirmationState
    {
        [EnumMember(Value = "All")]
        All,
        [EnumMember(Value = "Confirmed")]
        Confirmed,
        [EnumMember(Value = "NotConfirmed")]
        NotConfirmed
    }

Vous pouvez effectuer des requêtes à l'aide de « measureIds » ou « measureGlobalIds ». Il est possible d'effectuer une requête à l'aide d'un seul « measureId » ou d'un tableau contenant plusieurs « measureIds ». Il en va de même pour « measureGlobalIds ».

Tri

Le tri par période peut être effectué dans l'ordre croissant ou décroissant. Le comportement par défaut est ascendant.

  énumération publique SortDirection
    {
        Ascending,
        Descending
    }

Pour prendre en charge la pagination, il existe deux paramètres spécifiques : « first » et « after ». Cependant, en raison de la structure plate des données et de l'incertitude quant au nombre de points de données dans chaque enregistrement, ces paramètres ne peuvent être utilisés qu'au niveau de l'enregistrement. Le paramètre « first » indique le nombre d'enregistrements à renvoyer par le point de terminaison. La valeur par défaut est « int.MaxValue » (2 147 483 647), qui récupère toutes les inscriptions. Vous pouvez également spécifier un nombre précis d'inscriptions.

Remarque : chaque requête comporte la section finale suivante :

« totalCount » : {total_number_of_registrations},
    « pageInfo » : {
        « startCursor » : « cGFnXXsw »,
        « endCursor » : « cGRnXXsw »,
        « hasNextPage » : true
    }

En raison de certaines limitations, il est important de noter que la propriété «totalCount » représente le nombre d'enregistrements plutôt que le nombre de points de données.

Le nombre total d'inscriptions dépend de l'état «RegistrationConfirmed ». Il renvoie toujours le nombre total d'inscriptions, quel que soit le paramètre « first » qui spécifie le nombre d'inscriptions à récupérer.

Le comportement de la pagination est décrit ici.

De plus, différents paramètres peuvent être combinés avec les paramètres «first » et «after » afin d'affiner davantage la requête.

Réponse vide

Si aucun élément n'a été trouvé après l'application des filtres, la réponse se présente comme suit :

{
    "items": [],
    "totalCount": 0,
    "pageInfo": {
        "startCursor": "",
        "endCursor": "",
        "hasNextPage": false
    }
}