Position Green API: Datenpunkte

Geändert am Di, 8 Jul um 5:11 NACHMITTAGS

INHALTSVERZEICHNIS

Besonderheiten
Eigenschaften eines Datenpunktobjekts
- Eigenschaften der Metadaten
Daten für Datenpunkte abrufen
Datenpunkte in der API abfragen

Ein Datenpunkt bezieht sich auf die von einem Berichterstatter übermittelten Daten, dargestellt in einer flachen Struktur.

Besonderheiten

Um den einzigartigen Merkmalen des Datenpunkt-Endpunkts gerecht zu werden, der sich von anderen Endpunkten mit mehr Daten unterscheidet, und um offensichtliche Probleme der Datenredundanz in einer flachen Struktur (in der Metadaten für einen oder mehrere Datenpunkte wiederholt werden) zu vermeiden, wird eine Streaming-Lösung implementiert.

Der ausgegebene Datenstrom enthält ausschließlich Datenpunkte mit Werten, während solche ohne Wert herausgefiltert werden.

Eigenschaften eines Datenpunktobjekts

Eigenschaften der Metadaten

Eigenschaft	Datenart	Beschreibung
OrgUnitPrettyId	String	PrettyID der Organisationseinheit
OrgUnitLabel	String	Die Organisationseinheit, zu der die Daten gehören
OrgUnitTags	mehrere Strings	Tags, die einer Organisationseinheit zugeordnet sind
ReportingYearLabel	String	Berichtsjahr, zu dem eine Registrierung gehört
ReportingYearId	Guid	ID des Berichtsjahres, zu dem die Registrierung gehört
PeriodName	String	Bezeichnung des Zeitraums, zu dem die Registrierung gehört
PeriodMoniker	String	Abkürzung des Zeitraums, zu dem eine Registrierung gehört

PeriodStartDate	String	Anfangsdatum des Zeitraums, zu dem eine Registrierung gehört
AspectName	String	Der Aspekt, zu dem sie gehört
AspectId	Guid	ID des Aspekts, zu dem sie gehört
MeasureName	String	Bezeichnung der Metrik
MeasureId	Guid	ID der Metrik
MeasureGlobalId	Guid?	GlobalID der Metrik
MeasurePrettyId	String	PrettyID der Metrik

MeasureTags	mehrere Strings	Eine Liste von Tags, die zu der Metrik gehören
MeasurePointId	Guid?	ID des Datenpunktes
RegistrationResponsibleEmail	String	E-Mail-Adresse eines Berichterstatters, der für die Datenerfassung zuständig ist
RegistrationResponsibleName	String	Vollständiger Name des Berichterstatters, der für die Datenerfassung zuständig ist
RegistrationLastUpdateUtc	lang?	Ein Unix-Zeitstempel, der angibt, wann der Datenpunkt zuletzt aktualisiert wurde
RegistrationConfirmed	bool	Bestätigungsstatus der Registrierung

Eigenschaften der Datenpunktwerte

Eigenschaft	Datenart	Beschreibung
MeasurePointTags	mehrere Strings	Eine Liste von Tags. Sie können im Metrikengenerator festgelegt werden und werden als Möglichkeit zur Identifizierung eines Steuerelements empfohlen
ControlType	String	Art des Steuerelements, das zum Datenpunkt gehört
DataPointControlName	String	Bezeichnung des Datenpunktes. Kann komplex sein und Trennzeichen !! enthalten, wenn Datenpunkte zu iterativen Steuerelementen gehören
DataDisplayValue	String	Anzeigename, den der Berichterstatter sieht
DataUnit	String	Einheit der Werte, die zum Datenpunkt gehört
DataValueType	String	Art des Wertes. Wird als Unterscheidungsmerkmal verwendet
DataValue	String	Die tatsächlichen Daten des Datenpunktes
RowId	Guid	ID, die angibt, welche Datenpunkte zueinander gehören. Wird auch als korrelierende ID bezeichnet

Daten für Datenpunkte abrufen

/datapoints

GET https://api.positiongreen.com/v1/datapoints

Nützlich beim Abrufen von Daten für ein Data-Lake- oder BI-System mit optionaler Eingabe, um Delta-Datensätze zu erhalten.

Ausgegeben wird ein flacher, konsistenter Datensatz mit Daten, die in Position Green erfasst und berechnet wurden.

Abfrageparameter

Bezeichnung	Art	Beschreibung
yearId*	String	ID (GUID) des Jahres - wie unter /years angegeben z. B.: 0f80635f-1215-400b-924a-e365cc601d31
measureIds	string[]	Liste der Metrik-IDs, auf die das Ergebnis beschränkt werden soll
measureGlobalIds	string[]	Liste der globalen Metrik-IDs, auf die das Ergebnis beschränkt werden soll
orgUnitIds	string[]	Liste der IDs der Organisationseinheit (GUIDs) zum Filtern der Ergebnisse
orgUnitGlobalIds	string[]	Liste der globalen IDs der Organisationseinheit (GUIDs) zum Filtern der Ergebnisse
includeChildren	bool	Gibt an, ob untergeordnete Einheiten der angegebenen Organisationseinheiten in die Antwort einbezogen werden sollen. (Standardeinstellung = falsch)
startDate	String	Zeitstempel (ISO 8601) z. B. 2023-06-01T00:00:00+02:00
endDate	String	Zeitstempel (ISO 8601) z. B. 2023-08-31T23:59:59+02:0
lastModifiedStart	Zahl	Unix-Zeitstempel
confirmationState	String	Siehe confirmationState
sortDirection	String	Siehe nachfolgenden Abschnitt Sortierung
after	String	Verwendeter Cursors zum Abrufen der nächsten Seite
first	Zahl	Anzahl der Registrierungen, auf die die Seite beschränkt werden soll
lastModifiedEnd	Zahl	Unix-Zeitstempel

200: OK Erfolg

Siehe nachstehendes Antwortbeispiel

Beispiel für eine Curl-Anfrage

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

Durch Ausführen einer cURL-Anfrage in einer Konsole lässt sich beobachtet, dass die Daten vom Endpunkt aus gestreamt werden.

Beispiel für eine Antwort

Das nachstehende Beispiel zeigt eine Registrierung mit zwei unterschiedlichen Datenpunkten. Beachten Sie, dass die Metadaten für die Registrierung zwar gleich bleiben, die Daten für jeden Datenpunkt jedoch unterschiedlich sind.

{
    "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": "Aspect name 1",
                "AspectId": "e0265592-dsd7-44hf-b433-fd9a5ty3bdc7",
                "MeasureName": "Measure name 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": "Summary of first measure",
                "DataUnit": "ton",
                "DataValueType": "Numeric",
                "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": "January",
                "PeriodMoniker": "M1",
                "PeriodStartDate": "2023-01-31T00:00:00.0000000+01:00",
                "AspectName": "Aspect name 1",
                "AspectId": "e0265592-dsd7-44hf-b433-fd9a5ty3bdc7",
                "MeasureName": "Measure name 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": "Summary of first measure",
                "DataUnit": "m3",
                "DataValueType": "Numeric",
                "DataValue": "10",
                "RowId": "201b9192-e565-4680-ad64-30fd78dc4b6d"
            }
        }
    ],
    "totalCount": 1,
    "pageInfo": {
        "startCursor": "cGFnZTs5",
        "endCursor": "cGFnZTs5",
        "hasNextPage": true
    }
}

Datenpunkte in der API abfragen

Bei Verwendung der Parameter"startDate" und"endDate" werden Registrierungen ausgegeben, deren "periodEndDate" innerhalb des angegebenen Bereichs liegt. Wenn Sie beispielsweise bei "startDate" nach "2019-12-01" filtern, erhalten Sie alle Registrierungen, bei denen das "periodEndDate" nach dem 1. Dezember 2019 liegt. Dies gilt, wenn für die Metrik eine jährliche Datenerfassung eingestellt ist und das Startdatum der Registrierung der 1. Januar 2019 und das Enddatum der 31. Dezember 2019 ist, was einem Kalenderjahr entspricht.

Bei Verwendung der Parameter"lastModifiedStart" und"lastModifiedEnd" werden Registrierungen ausgegeben, deren"RegistrationLastUpdateUtc" innerhalb des angegebenen Bereichs liegt. Dieser Parameter funktioniert zeitzonenunabhängig und ist sehr genau, sodass sorgar Abfragen auf Millisekundenebene möglich sind.

Bei Verwendung des Parameters "confirmationState" werden Registrierungen mit einem bestimmten Status ausgegeben. Der Parameter "confirmationState" ist ein ENUM und als Standardwert ist eingestellt, dass nur bestätigte Registrierungen ausgegeben werden.

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

Sie können für Abfragen entweder "measureIds" oder "measureGlobalIds" verwenden. Dabei können Sie eine Abfrage mittels einer einzelnen "measureId" oder mehrerer "measureIds" durchführen. Dasselbe gilt für "measureGlobalIds".

Sortierung

Sie können in aufsteigender oder absteigender Reihenfolge nach dem Zeitraum sortieren. Voreingestellt ist die aufsteigende Reihenfolge.

  public enum SortDirection
    {
        Ascending,
        Descending
    }

Zur Erleichterung der Paginierung gibt es zwei spezielle Parameter: "first" und "after". Aufgrund der flachen Datenstruktur und der unbekannten Anzahl der Datenpunkte in jeder Registrierung können diese Parameter jedoch nur auf Registrierungsebene verwendet werden. Der Parameter "first" gibt die Anzahl der Registrierungen an, die der Endpunkt ausgeben soll. Die Standardeinstellung ist "int.MaxValue" (2.147.483.647), woraufhin alle Registrierungen abgerufen werden. Sie können auch eine bestimmte Anzahl an Registrierungen angeben.

Hinweis: Jede Anfrage endet mit folgendem Abschnitt:

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

Aufgrund von Einschränkungen ist es wichtig zu beachten, dass die Eigenschaft "totalCount" die Anzahl der Registrierungen und nicht die Anzahl der Datenpunkte darstellt.

Die Gesamtzahl der Registrierungen hängt vom Status "RegistrationConfirmed" ab. Sie gibt immer die Gesamtzahl der Registrierungen aus – unabhängig vom Parameter "first", der die Anzahl der abzurufenden Registrierungen angibt.

Der Paginierungsvorgang wird hier beschrieben.

Zusätzlich können verschiedene Parameter mit den Parametern "first" und "after" kombiniert werden, um die Abfrage weiter einzugrenzen.

Leere Antwort

Wenn nach Anwendung der Filter keine Einträge gefunden wurden, sieht die Antwort wie folgt aus:

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