Position Green API: Datapunkter

Ändrad den Mån, 9 juni vid 3:56 E.M.

INNEHÅLLSFÖRTECKNING

Specifikationer
Egenskaper för ett datapunktsobjekt
- Egenskaper för metadata
Hämta data för datapunkter
Fråga efter datapunkter i API

En datapunkt avser de uppgifter som lämnats av en rapportör och som presenteras i en platt struktur.

Specifikationer

För att hantera de unika egenskaperna hos datapunktens slutpunkt, som skiljer sig från andra slutpunkter som innehåller mer data, och för att undvika uppenbara problem med dataredundans i en platt struktur (där metadata upprepas för en eller flera datapunkter), implementeras en streaminglösning.

Den returnerade strömmen kommer uteslutande att inkludera datapunkter med värden, medan de utan något värde kommer att filtreras bort.

Egenskaper för ett datapunktsobjekt

Egenskaper för metadata

Egendom	Typ av data	Beskrivning
OrgUnitPrettyId	sträng	PrettyID för organisationsenheten
OrgUnitEtikett	sträng	Den organisationsenhet som uppgifterna tillhör
OrgUnitTags	Array av strängar	Taggar som är specificerade på en organisationsenhet
RapporteringsårEtikett	sträng	Rapportering år en registrering hör till
RapporteringsårId	Vägledning	Rapportering år ID som en registrering tillhör
PeriodNamn	sträng	Namnet på den period registreringen tillhör
PeriodMoniker	sträng	Monikern antyder den tidsperiod som en registrering tillhör

PeriodStartDatum	sträng	Startdatum för den period som en registrering tillhör
AspectNamn	sträng	Aspekten som den tillhör
AspectId	Vägledning	ID för aspekten som den tillhör
MätningNamn	sträng	Namnet på mätningen
MätId	Vägledning	Mätningens id
MätningGlobalId	Guid?	Mätningens globalId
MätPrettyId	sträng	PrettyID för mätningen

MätTaggar	Array av strängar	En lista över taggar som hör till mätningen
MeasurePointId	Guid?	ID för mätpunkt
RegistreringAnsvarigE-post	sträng	En e-postadress till en Rapportör som är ansvarig för datarapporteringen
Namn på registreringsansvarig	sträng	Fullständigt namn på Rapportör som är ansvarig för datarapportering
RegistreringSenaste uppdateringUtc	lång?	En unixtimestamp som anger när datapunkten senast uppdaterades
RegistreringBekräftad	bool	Status för bekräftelse av registreringen

Egenskaper för datapunktvärden

Egendom	Typ av data	Beskrivning
MeasurePointTags	Array av strängar	En lista med taggar. De kan ställas in i mätbyggaren och är ett rekommenderat sätt att identifiera en kontroll
KontrollTyp	sträng	Typ av kontroll hör till datapunkten
DataPointControlNamn	sträng	Namnet på datapunkten. Kan vara komplex med separatorer !!! om datapunkterna tillhör den iterativa kontrollen.
DataDisplayVärde	sträng	Displaynamn som visas för Rapportören
Dataenhet	sträng	Värdenas enhet hör till datapunkten
DataVärdeTyp	sträng	Typ av värde. Används som diskriminator
DataVärde	sträng	De faktiska uppgifterna för datapunkten
RowId	Vägledning	Den id som anger vilka datapunkter som tillhör varandra. Även känd som korrelerande Id

Hämta data för datapunkter

/datapoints

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

Används vid hämtning av data för en datasjö eller ett BI-system med valfri indata för att få delta-records.

Utdata är ett plant och konsekvent dataset med data som registrerats och beräknats i Position Green.

Parametrar för förfrågan

Namn	Ämne	Beskrivning
årId*	sträng	Id (GUID) för året - som anges från /years e.g. 0f80635f-1215-400b-924a-e365cc601d31
måttIds	sträng[]	Lista över mätning Ids för att begränsa resultatet till
mätaGlobalaIds	sträng[]	Lista över id:n för globala mätningar som resultatet ska begränsas till
orgUnitIds	sträng[]	Lista över id:n för organisationsenheter (GUID:er) för att filtrera resultaten.
orgUnitGlobalIds	sträng[]	Lista över id:n för globala organisationsenheter (GUID:er) för att filtrera resultaten.
includeChildren	bool	Anger om barn till de inkluderade organisationsenheterna ska ingå i svaret. (Förvalt = false)
startDatum	sträng	Tidsstämpel (ISO 8601) t.ex. 2023-06-01T00:00:00+02:00
slutDatum	sträng	Tidsstämpel (ISO 8601) t.ex. 2023-08-31T23:59:59+02:0
senastModifieradStart	[empty string]	Unix-tidsstämpel
bekräftelseStatus	sträng	Se bekräftelseStatus
sortDirection	sträng	Se sortering nedan
efter	sträng	Användning av markören för att hämta nästa sida
första	[empty string]	Antal registreringar för att begränsa sidan till
lastModifiedEnd	[empty string]	Unix tidsstämpel

200: OK Framgång

Se exempel på svar nedan

Exempel på en curl-förfrågan

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

Genom att köra en cURL-förfrågan i en konsol är det möjligt att observera att data strömmas ut från slutpunkten.

Exempel på ett svar från

Nedan visas ett exempel på en registrering med två olika datapunkter. Det är viktigt att notera att även om metadata för registreringen är desamma, skiljer sig uppgifterna för varje datapunkt åt.

{
    "objekt": [
        {
            "cursor": "cGFnZTs5",
            "node": {
                "OrgUnitPrettyId": "SOME_PRETTY_ID",
                "OrgUnitLabel": "Organisatorisk enhet 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": "Aspekt name 1",
                "AspektId": "e0265592-dsd7-44hf-b433-fd9a5ty3bdc7",
                "MeasureName": "Mätning namn 1",
                "MeasureId": "ed454f906-9999-48fc-9c44-420we65654f8",
                "MeasureGlobalId": "1hfghdeac5-c297-7gfd-95ad-4b43543534552",
                "MeasurePrettyId": "Mätning vackert namn 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": "Sammanfattning av första mätningen",
                "DataUnit": "ton",
                "DataValueType": "Numeric",
                "DataValue": "0",
                "RowId": null
            }
        }
        {
            "cursor": "cGFnZTs5",
             "node": {
                "OrgUnitPrettyId": "SOME_PRETTY_ID",
                "OrgUnitLabel": "Organisatorisk enhet 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": "Aspekt name 1",
                "AspektId": "e0265592-dsd7-44hf-b433-fd9a5ty3bdc7",
                "MeasureName": "Mätning namn 1",
                "MeasureId": "ed454f906-9999-48fc-9c44-420we65654f8",
                "MeasureGlobalId": "1hfghdeac5-c297-7gfd-95ad-4b43543534552",
                "MeasurePrettyId": "Mätning vackert namn 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": "Sammanfattning av första mätningen",
                "DataUnit": "m3",
                "DataValueType": "Numeric",
                "DataValue": "10",
                "RowId": "201b9192-e565-4680-ad64-30fd78dc4b6d"
            }
        }
    ],
    "totalCount": 1,
    "pageInfo": {
        "startCursor": "cGFnZTs5",
        "endCursor": "cGFnZTs5",
        "hasNextPage": true
    }
}

Fråga efter datapunkter i API

Vid användning av parametrarna"startDate" och"endDate" kommer registreringar att returneras där"periodEndDate" faller inom det angivna intervallet. Om du till exempel filtrerar på"startDate" som "2019-12-01" kommer du att få alla registreringar där"periodEndDate" är senare än den 1 december 2019. Detta gäller när mätningen är konfigurerad för att rapporteras årligen och registreringens startdatum är den 1 januari 2019 och slutdatum är den 31 december 2019, efter ett kalenderår.

Vid användning av parametrarna"lastModifiedStart" och"lastModifiedEnd" kommer registreringar att returneras där"RegistrationLastUpdateUtc" ligger inom det angivna intervallet. Denna parameter fungerar oberoende av tidszoner och ger hög precision, vilket gör det möjligt att ställa frågor även på millisekundnivå.

En förfrågan med användning av parametern"confirmationState" hämtar registreringar med en viss status. Parametern "confirmationState" är en Enum och förvalt är att endast bekräftade registreringar kommer att returneras.

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

Du kan utföra sökningar med användning av antingen "measureIds" eller "measureGlobalIds". Det är möjligt att ställa en fråga med användning av ett enda "measureId" eller en matris med flera "measureIds". Detsamma gäller för "measureGlobalIds".

Sortering

Sortering efter period kan ske i stigande eller fallande ordning. Förvalt beteende är stigande.

  public enum SortDirection
    {
        Ascending,
        Descending
    }

För att stödja paginering finns det två specifika parametrar: "först" och "efter". På grund av uppgifternas platta struktur och osäkerheten i antalet datapunkter i varje registrering kan dessa parametrar dock endast användas på registreringsnivå. Parametern "first" anger det antal registreringar som ska returneras av slutpunkten. Förvalt värde är "int.MaxValue" (2,147,483,647), vilket hämtar alla registreringar. Du kan också ange ett visst antal registreringar.

Obs: Varje begäran har följande slutavsnitt:

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

På grund av begränsningar är det viktigt att notera att egenskapen"totalCount" representerar antalet registreringar snarare än antalet datapunkter.

Det totala antalet registreringar beror på tillståndet"RegistrationConfirmed". Den returnerar alltid det totala antalet registreringar, oavsett parametern "first" som anger antalet registreringar som ska hämtas.

Hur paginering fungerar beskrivs här.

Dessutom kan olika parametrar kombineras med parametrarna"först" och "efter" för att förfina frågan ytterligare.

Tomt svar

Om inga objekt hittades efter tillämpning av filter ser svaret ut så här:

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