Position Green API: Registrierungen

Geändert am Mi, 9 Jul um 5:06 NACHMITTAGS

INHALTSVERZEICHNIS


Bei einer Registrierung handelt es sich um die Daten, die ein Berichterstatter aufgrund der Struktur einer Metrik übermittelt hat. Angesichts der individuell anpassbaren Eigenschaften einer Metrik enthält die Registrierung ein Diagramm der Antworten für die Werte, die den Fragen in einer Metrik entsprechen.


Swagger UI

Nachfolgend finden Sie die Dokumentation zu den Registrierungen. Um den Endpunkt zu testen, besuchen Sie bitte unsere Swagger-UI-Seite.


Eigenschaften eines Registrierungsobjekts


EigenschaftDatenartBeschreibung
id

Guid

ID der Registrierung

organizationUnit

String

Organisationseinheit, zu der die Daten gehören

measureName

String

Bezeichnung der Metrik

responsibleUser

StringFür die Datenerfassung zuständiger Berichterstatter

confirmedAt

DateTime?Wenn die Registrierung bestätigt wurde, hat sie einen Zeitstempel
period

String

Art des Zeitraums
periodStart

String

Startdatum des Zeitraums
periodEndStringEnddatum des Zeitraums
dataObjektDie Darstellung der Daten. Datenstruktur



Die Eigenschaft "Zeitraum" enthält einen Code und eine Zahl, zum Beispiel "M4": M für Monat und 4 für April. Auf diese Weise lässt sich bei Bedarf das Intervall ermitteln. Wenn für die Metrik "Seit Jahresbeginn" eingestellt ist, dann ist das Startdatum immer das Datum des Jahresbeginns.


Die Registrierungsdaten sind ein Diagrammobjekt, das die Werte enthält. Die Diagrammstruktur richtet sich nach dem Setup der Metrik. Der Controller konfiguriert die Metrik, in der der Berichterstatter die Daten erfasst.


Das Stammobjekt in der Dateneigenschaft ist immer ein ListValue, eine Sammlung von Werten.


Wert

Die Grundlage aller Wertarten; enthält allgemeine Informationen, die in allen Wertarten verfügbar sind.


EigenschaftBeschreibung
idID der Daten. Diese ist bei jeder Registrierung anders.
name

Systemname; er kann im Metrikengenerator festgelegt werden, um das Steuerelement näher zu bestimmen.

labelAnzeigename, den der Berichterstatter sieht

typ

Art des Wertes. Wird als Unterscheidungsmerkmal verwendet

tags

Eine Liste von Tags. Sie können im Metrikengenerator festgelegt werden und werden als Möglichkeit zur Identifizierung eines Steuerelements empfohlen.


Zur Ermittlung einer Unterart eines Wertes wird die Eigenschaftsart verwendet. In den nachfolgenden Beschreibungen der einzelnen Werte wurden alle gemeinsamen Eigenschaften weggelassen.


Liste


Eine Sammlung von Werten. Das Stammobjekt bei "data" ist immer eine Liste. Sie kann andere Listen enthalten. ID und Bezeichnung einer Liste sind immer Null.


EigenschaftBeschreibung
ValueAuflistung von Werten


Beispiel


Beispiel für eine Liste mit zwei Werten.


{
    "Wert": [
        {
            "Typ": "numeric",
            "value": 4,
            "unit": "Trips",
            "id": "measure_1",
            "name": "measure_1",
            "label": "Anzahl der Flüge",
            "tags": []
        },
        {
            "type": "numeric",
            "value": 2000,
            "unit": "km",
            "id": "measure_2",
            "name": "measure_2",
            "label": "Entfernung mit dem Flugzeug 2",
            "tags": []
        }
    ],
    "type": "list"
}


Wiederholungsmodul


Mit einem wiederholbaren Steuerelement kann ein Berichterstatter bei der Datenerfassung in Position Green in einer Metrik Zeilen hinzufügen und entfernen. Jede Zeile des Wiederholungsmoduls wird in der Datenstruktur als Liste dargestellt.


Eigenschaft

Beschreibung

ValueAuflistung von Zeilen


Beispiel

Das nachfolgende Beispiel zeigt eine Registrierung in einer Metrik, die ein Wiederholungsmodul enthält, bei dem der Berichterstatter eine oder mehrere Zeilen hinzufügen und jeweils eine Energiequelle sowie den Energieverbrauch angeben kann.


Jeder Zeile im Wiederholungsmodul wird eine eindeutige ID zugewiesen, die Bezeichnung bleibt jedoch für jedes Steuerelement gleich.


Die Antwort sieht folgendermaßen aus:


{
    "value": [
        {
            "type": "repeatable",
            "value": [
                {
                    "value": [
                        {
                            "type": "dropdown",
                            "value": [
                                {
                                    "name": "Wind"
                                }
                            ],
                            "id": "measure_fc2t!!repeatable_q3gn!!15862358690400",
                            "name": "measure_fc2t",
                            "label": "Source",
                            "tags": []
                        },
                        {
                            "type": "numeric",
                            "value": 65000,
                            "unit": "kWh",
                            "id": "measure_dnkl!!repeatable_q3gn!!15862358690400",
                            "name": "measure_dnkl",
                            "label": "Energy used",
                            "tags": []
                        }
                    ],
                    "type": "list"
                },
                {
                    "value": [
                        {
                            "type": "dropdown",
                            "value": [
                                {
                                    "name": "Solar"
                                }
                            ],
                            "id": "measure_fc2t!!repeatable_q3gn!!15862359182380",
                            "name": "measure_fc2t",
                            "label": "Source",
                            "tags": []
                        },
                        {
                            "type": "numeric",
                            "value": 250000,
                            "unit": "kWh",
                            "id": "measure_dnkl!!repeatable_q3gn!!15862359182380",
                            "name": "measure_dnkl",
                            "label": "Energy used",
                            "tags": []
                        }
                    ],
                    "type": "list"
                },
                {
                    "value": [
                        {
                            "type": "dropdown",
                            "value": [
                                {
                                    "name": "Nuclear"
                                }
                            ],
                            "id": "measure_fc2t!!repeatable_q3gn!!15862359243871",
                            "name": "measure_fc2t",
                            "label": "Source",
                            "tags": []
                        },
                        {
                            "type": "numeric",
                            "value": 3000000,
                            "unit": "kWh",
                            "id": "measure_dnkl!!repeatable_q3gn!!15862359243871",
                            "name": "measure_dnkl",
                            "label": "Energy used",
                            "tags": []
                        }
                    ],
                    "type": "list"
                }
            ],
            "id": "repeatable_q3gn",
            "name": "repeatable_q3gn"
        }
    ],
    "type": "list"
}


Zahl


Enthält einen numerischen Wert und eine Einheit.


Eigenschaft

Beschreibung

value

Dezimalwert

unit

Einheit des Wertes


Beispiel


Der Wert ist 9000 und die Einheit ist Kilometer.


{
    "type": "numeric",
    "value": 9000,
    "unit": "km",
    "id": "measure_2_copy1",
    "name": "measure_2_copy1",
    "label": "Distance by train",
    "tags": []
}


Text

Textwert, bei dem der Berichterstatter eine qualitative Antwort einträgt.


EigenschaftBeschreibung
valueTextwert


{
    "type": "text",
    "id": "info",
    "name": "info",
    "label": "Additional info",
    "tags": [],
    "value": "Qualitative text response"
}

Bool

Ein boolescher Wert, bei dem der Berichterstatter bei der Beantwortung zwischen Ja und Nein gewählt hat.


EigenschaftBeschreibung
valueBoolescher Wert


Beispiel

{
    "type": "bool",
    "id": "renewable",
    "name": "renewable",
    "label": "Is the source renewable?",
    "tags": [],
    "value": true
}



Datum

Ein Wert, der ein Datum im Format ISO 8601, yyyy-mm-dd enthält.


ObjektBeschreibung
WertDatum im Format ISO 8601 jjjj-mm-tt


Beispiel

{
    "Typ": "date",
    "value": "2020-01-24",
    "id": "registration_date",
    "name": "registration_date",
    "label": "Datum",
    "tags": []
}


Dropdown-Listen

Ein Dropdown-Wert, der eine oder mehrere von einem/einer Reporter*in ausgewählte Optionen enthält.


ObjektBeschreibung
ValueEin Array von SelectedOption


Die Dropdown-Liste hat eine Konfigurationseinstellung, die angibt, ob die Reporter*in viele Werte auswählen darf. Der Dropdown-Wert ist immer ein Array in der Datenstruktur.


Die SelectedOption enthält einen Namen und einen optionalen Wert.


Beispiel

Hier ist ein Beispiel für drei verschiedene Werte aus Dropdowns.


  1. Der Wert enthält eine JSON-kodierte Zeichenfolge
  2. Der Wert enthält einen einfachen Wert
  3. Es gibt keinen Wert für die ausgewählte Option
{
    "type": "Wiederholungsmodul",
    "Wert": [
        {
            "Wert": [
                {
                    "Typ": "dropdown",
                    "value": [
                        {
                            "name": "Wind",
                            "value": "{\"renewable\":true}"
                        }
                    ],
                    "id": "measure_fc2t!!repeatable_q3gn!!15862358690400",
                    "name": "measure_fc2t",
                    "label": "Quelle",
                    "tags": []
                },
                {
                    "type": "numeric",
                    "value": 65000,
                    "unit": "kWh",
                    "id": "measure_dnkl!!repeatable_q3gn!!15862358690400",
                    "name": "measure_dnkl",
                    "label": "Energie verwendet",
                    "tags": []
                }
            ],
            "type": "list"
        },
        {
            "value": [
                {
                    "type": "dropdown",
                    "value": [
                        {
                            "name": "Solar",
                            "value": "100"
                        }
                    ],
                    "id": "measure_fc2t!!repeatable_q3gn!!15862359182380",
                    "name": "measure_fc2t",
                    "label": "Quelle",
                    "tags": []
                },
                {
                    "type": "numeric",
                    "value": 250000,
                    "unit": "kWh",
                    "id": "measure_dnkl!!repeatable_q3gn!!15862359182380",
                    "name": "measure_dnkl",
                    "label": "Energie verwendet",
                    "tags": []
                }
            ],
            "type": "list"
        },
        {
            "value": [
                {
                    "type": "dropdown",
                    "value": [
                        {
                            "name": "Nuklear"
                        }
                    ],
                    "id": "measure_fc2t!!repeatable_q3gn!!15862359243871",
                    "name": "measure_fc2t",
                    "label": "Quelle",
                    "tags": []
                },
                {
                    "type": "numeric",
                    "value": 3000000,
                    "unit": "kWh",
                    "id": "measure_dnkl!!repeatable_q3gn!!15862359243871",
                    "name": "measure_dnkl",
                    "label": "Energie verwendet",
                    "tags": []
                }
            ],
            "type": "list"
        }
    ],
    "id": "wiederholbar_q3gn",
    "name": "wiederholbar_q3gn"
}

Datei

Ein Wert, der die vom Reporter*in hochgeladenen Dateien darstellt. Die Reporter*in kann eine oder mehrere Dateien hochladen. Sie enthalten einen Namen und einen Link. Der Name ist der Dateiname und der Link ist ein URL-Pfad zum Herunterladen des Anhangs.


Objekt

Beschreibung
ValueEin Array von Dateien (Name und Link)


Beispiel


{
    "Typ": "file",
    "value": [
        {
            "name": "Invoice ACME.pdf",
            "link": "/attachment/get/3ef994e5-81ee-4958-bb99-3812be0d305a"
        },
        {
            "name": "Invoice FOO.xlsx",
            "link": "/attachment/get/ba602707-0055-48b2-b6ed-879eabfa217b"
        }
    ],
    "id": "measure_gtby",
    "name": "measure_gtby",
    "label": "Hochladen von Quellmaterial",
    "tags": []
}


Registrierungen abrufen


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


Rückgabe von Registrierungen


Abfrage-Parameter


NameTypBeschreibung
yearId*some translationId des Jahres (Guid)
measureIdsArrayIds der Metrik (Guid)
orgUnitIds
ArrayOrganisation Einheit Ids (Guid)
orgUnitIds
Array
Organisation Einheit Ids (Guid)
includeChildren
boolGibt an, ob Kinder der angegebenen Organisationseinheiten in das Angebot einbezogen werden sollen. (Default = false)
measurePrettyIds
ArrayHübsche Ids von Metriken (String)
startDate
some translationDatum des Beginns der Registrierungen für (jjjj-mm-tt)

endDate

some translationEnddatum der Registrierungen für (jjjj-mm-tt)
erste
asdf
Anzahl der zurückzuschickenden Registrierungen. Default = 10. Minimum 1 und Maximum 100.
nach
some translationCursor auf den Ort, von dem aus Sie weiterhin Registrierungen erhalten
sortBy
some translationPunkt
sortDirection
some translationAufsteigend", "Absteigend


{
    "totalCount": 178,
    "pageInfo": {
        "hasNextPage": true,
        "startCursor": "cGFnZTsw",
        "endCursor": "cGFnZTs5"
    },
    "items": [
        {
            "cursor": "cGFnZTs0MTQ=",
            "node": {
                "id": "715117fd-a8c5-4cf7-9a4b-8cc7aafee0f4",
                "organizationUnit": "Björn Johansson",
                "measureName": "Report energy usage",
                "responsibleUser": "Björn Johansson",
                "data": {
                    "value": [
                        {
                            "type": "Wiederholungsmodul",
                            "value": [
                                {
                                    "value": [
                                        {
                                            "type": "dropdown",
                                            "value": [
                                                {
                                                    "name": "Wind",
                                                    "value": "{\"renewable\":true}"
                                                }
                                            ],
                                            "id": "measure_fc2t!!repeatable_q3gn!!15862358690400",
                                            "name": "measure_fc2t",
                                            "label": "Quelle",
                                            "tags": []
                                        },
                                        {
                                            "type": "numeric",
                                            "value": 65000,
                                            "unit": "kWh",
                                            "id": "measure_dnkl!!repeatable_q3gn!!15862358690400",
                                            "name": "measure_dnkl",
                                            "label": "Energie verwendet",
                                            "tags": []
                                        }
                                    ],
                                    "type": "list"
                                },
                                {
                                    "value": [
                                        {
                                            "type": "dropdown",
                                            "value": [
                                                {
                                                    "name": "Solar",
                                                    "value": "100"
                                                }
                                            ],
                                            "id": "measure_fc2t!!repeatable_q3gn!!15862359182380",
                                            "name": "measure_fc2t",
                                            "label": "Quelle",
                                            "tags": []
                                        },
                                        {
                                            "type": "numeric",
                                            "value": 250000,
                                            "unit": "kWh",
                                            "id": "measure_dnkl!!repeatable_q3gn!!15862359182380",
                                            "name": "measure_dnkl",
                                            "label": "Energie verwendet",
                                            "tags": []
                                        }
                                    ],
                                    "type": "list"
                                },
                                {
                                    "value": [
                                        {
                                            "type": "dropdown",
                                            "value": [
                                                {
                                                    "name": "Nuklear"
                                                }
                                            ],
                                            "id": "measure_fc2t!!repeatable_q3gn!!15862359243871",
                                            "name": "measure_fc2t",
                                            "label": "Quelle",
                                            "tags": []
                                        },
                                        {
                                            "type": "numeric",
                                            "value": 3000000,
                                            "unit": "kWh",
                                            "id": "measure_dnkl!!repeatable_q3gn!!15862359243871",
                                            "name": "measure_dnkl",
                                            "label": "Energie verwendet",
                                            "tags": []
                                        }
                                    ],
                                    "type": "list"
                                }
                            ],
                            "id": "wiederholbar_q3gn",
                            "name": "wiederholbar_q3gn"
                        },
                        {
                            "type": "file",
                            "value": [
                                {
                                    "name": "ReportTest.pdf",
                                    "link": "/attachment/get/3ef294e5-81ee-4958-bb99-3812be0d305a"
                                },
                                {
                                    "name": "Information.pdf",
                                    "link": "/anhang/get/bb602707-0055-48b2-b6ed-879eabfa217b"
                                }
                            ],
                            "id": "measure_gtby",
                            "name": "measure_gtby",
                            "label": "Filuppladdning",
                            "tags": []
                        }
                    ],
                    "type": "list"
                },
                "period": "Y0"
            }
        }
    ]
}


Die Abfrage unter Verwendung von startDate und endDate liefert Registrierungen, bei denen periodEndDate innerhalb des Bereichs liegt. Das heißt, wenn Sie nach dem Startdatum '2019-12-01' filtern, erhalten Sie alle Registrierungen, bei denen das PeriodEndDate nach dem 2019-12-01 liegt. Dies könnte bedeuten, dass die Metrik so konfiguriert ist, dass sie jährlich gemeldet wird, dann ist das Startdatum der Registrierung der 01.01.2019 und das Enddatum der Registrierung der 31.12.2019 (wenn das Jahr auf ein Kalenderjahr folgt).

War dieser Artikel hilfreich?

Das ist großartig!

Vielen Dank für das Feedback

Leider konnten wir nicht helfen

Vielen Dank für das Feedback

Wie können wir diesen Artikel verbessern?

Wählen Sie wenigstens einen der Gründe aus
CAPTCHA-Verifikation ist erforderlich.

Feedback gesendet

Wir wissen Ihre Bemühungen zu schätzen und werden versuchen, den Artikel zu korrigieren