Interfejs REST API AMAGE - nadzór nad wykonaniem

Wstęp/Kontekst

Kontekst dla operacji na obiektach modułu nadzoru (Supervision) w systemie AMAGE, którą należy w zapytaniu rozszerzyć o odpowiednią metodę.

  • rest/amage/v1/supervisions

Struktury danych

Struktury i typy danych wykorzystywane w zapytaniach i odpowiedziach.

Rezultat:

W polach ID/UUID znajduje się identyfikator nowo utworzonego lub edytowanego obiektu. W przypadku poprawnego wykonania operacji pole success jest ustawiane na true. W przypadku wystąpienia błędu pole success jest ustawiane na false, a w polu message znajduje się opis błędu. Kod błędu zawiera wtedy kod HTTP typu NOT_FOUND lub BAD_REQUEST. Zwracany w zapytaniu wtedy jest również kod BAD_REQUEST. W zależności od typu błędu podczas przetwarzania zapytania kod błędu może być różny niż zwracany główny kod zapytania. Kod zapytania będzie BAD_REQUEST, a kod wewnętrzny będzie ustawiony na NOT_FOUND w przypadku takim, gdy zapytanie będzie ustawiało właściwość obiektu na inny obiekt w systemie. Parametr JSON będzie poprawny (UUID rekordu), ale takiego rekordu nie będzie w systemie. W związku z tym w polu errorCode pojawi się kod NOT_FOUND. W polu opisowym message komunikat informujący jakiego rekordu nie znaleziono, a główny kod błędu zapytania będzie wynosił BAD_REQUEST.

{
    "id": 1,
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}

Źródło informacji. Pole wyliczeniowe jako lista wartości separowana przecinkami. Dostępne wartości:

  • FROM_DESKTOP,

  • FROM_MOBILE,

  • FROM_IDENTIFIER,

  • FROM_DIFFERENCE,

  • FROM_IMPORT,

  • FROM_WEB_SERVICE,

  • FROM_DATA_AGGREGATOR,

  • FROM_AUTOMATION

Operacje API

Odczytanie danych zapisu historii nadzoru

  • Metoda: GET

  • Ścieżka: /history/{uuid}

  • Generuje: application/json

  • Wymaga: application/json, text/plain

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • UUID - identyfikator wpisu historii dla nadzorowanego elementu

Zwracane dane to obiekt JSON ze strukturą:

{
    "id": 12345,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "invalid":false,
    "timestamp":"2021-01-01T12:00:00",
    "supervisionElementUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "userUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "supervisionStateTemplateItemUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "progress":100,
    "addedCount":0,
    "locationUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "mapShapeLatitude":50.0,
    "mapShapeLongitude":20.0,
    "mapShapeMapCode":"default",
    "parameters":[
        {
            "id": 3456,
            "parameterSettingUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
            "date": "2021-01-01T12:00:00",
            "userUuid": "1c4066e6-cdd6-4903-803a-b6bffe689527",
            "currentValue":"100.0",
            "source":"FROM_WEBSERVICE"
        }
    ]
}

Zapisanie historii do istniejącego elementu nadzorowanego

  • Metoda: POST

  • Ścieżka: /add-history/{uuid}

  • Generuje: application/json

  • Wymaga: application/json

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • UUID - identyfikator elementu nadzorowanego

W treści zapytania (body) należy zamieścić obiekt JSON z danymi historii nadzorowania. Obiekt ma strukturę:

{
    "invalid":false,
    "timestamp":"2021-01-01T12:00:00",
    "supervisionElementUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "userUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "supervisionStateTemplateItemUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "progress":100,
    "addedCount":0,
    "locationUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "mapShapeLatitude":50.0,
    "mapShapeLongitude":20.0,
    "mapShapeMapCode":"default",
    "parameters":[
        {
            "id": -1,
            "parameterSettingUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
            "date": "2021-01-01T12:00:00",
            "userUuid": "1c4066e6-cdd6-4903-803a-b6bffe689527",
            "currentValue":"100.0",
            "source":"FROM_WEBSERVICE"
        }
    ]
}

Zapytanie

/rest/amage/v1/supervisions/add-history/1c4066e6-cdd6-4903-803a-b6bffe689527

Odpowiedź

{
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}

Edycja historii nadzoru

  • Metoda: POST

  • Ścieżka: /edit-history/{uuid}

  • Generuje: application/json

  • Wymaga: application/json

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • UUID - identyfikator historii nadzoru

Ze względu na operacje na istniejących danych, nieuwzględniane w edycji są zmiany w powiązanych parametrach. Parametry pozostają bez zmian. Modyfikujemy tylko parametry głównego obiektu historii nadzoru.

W treści zapytania (body) należy zamieścić obiekt JSON z danymi historii nadzorowania. Obiekt ma strukturę:

{
    "invalid":false,
    "timestamp":"2021-01-01T12:00:00",
    "supervisionElementUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "userUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "supervisionStateTemplateItemUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "progress":100,
    "addedCount":0,
    "locationUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "mapShapeLatitude":50.0,
    "mapShapeLongitude":20.0,
    "mapShapeMapCode":"default"
}

Zapytanie

/rest/amage/v1/supervisions/edit-history/1c4066e6-cdd6-4903-803a-b6bffe689527

Odpowiedź

{
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}

Usunięćie historii nadzoru

  • Metoda: DELETE

  • Ścieżka: /delete-history/{uuid}

  • Generuje: application/json

  • Wymaga: application/json

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • UUID - identyfikator historii nadzoru

Treść zapytania (body): pusta.

Zapytanie

/rest/amage/v1/supervisions/delete-history/1c4066e6-cdd6-4903-803a-b6bffe689527

Odpowiedź

{
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}

Przykłady

Przykładowy kod w języku python wykorzystujący bibliotekę requests do dodania historii nadzoru.

#!/usr/bin/python3

import binascii
import hashlib

import requests

PARAM_SEPARATOR = ";"

def calc_api_sign(path, api_secret):
    message_digest = hashlib.sha256()
    message_digest.update(bytearray.fromhex(api_secret))
    message_digest.update(PARAM_SEPARATOR.encode('utf-8'))
    message_digest.update(path.encode('utf-8'))
    return message_digest.digest()

def post_method(server_url, headers, path, json):
    print(server_url + path)
    url = server_url + path
    response = requests.post(url, headers=headers, json=json)
    print("received return code: {0}".format(response.status_code))
    print("received data: {0}".format(response.text))

def get_header(path, content_type, accept):
    headers = {
        "Content-Type": content_type,
        "Accept": accept,
        "amage-device-uuid": device_uuid,
        "amage-api-key": api_key,
        "amage-api-sign": binascii.hexlify(calc_api_sign(path, api_secret)).decode()
    }
    return headers

server_url = "https://server.url/rest/amage/v1/"

device_uuid = "b0b135db-14f7-4d35-92d8-8357815185df"
api_key = "f4affb2db24b2b0903ad89ceeb622ece"
api_secret = "f4affb2db24b2b0903ad89ceeb622ede"

supervision_state_item_uuid = '1ba796f7-4a56-4ce1-ad6c-6d9c528974ad'
supervision_element_uuid = '1c4066e6-cdd6-4903-803a-b6bffe689527'
parameter_setting_uuid = '1c4066e6-cdd6-4903-803a-b6bffe689528'

request_path = "supervisions/add-history/" + supervision_element_uuid;

#ItemSource available values:
#    FROM_DESKTOP,
#    FROM_MOBILE,
#    FROM_IDENTIFIER,
#    FROM_DIFFERENCE,
#    FROM_IMPORT,
#    FROM_WEB_SERVICE,
#    FROM_DATA_AGGREGATOR,
#    FROM_AUTOMATION

json = {
    'invalid': False,
    'timestamp': '2024-10-06T12:00:00',
    'supervisionElementUuid': supervision_element_uuid,
    'userUuid': 'b0b135db-14f7-4d35-92d8-8357815185de',
    'supervisionStateTemplateItemUuid': supervision_state_item_uuid,
    'progress': 100,
    'addedCount': 1,
    'mapShapeLatitude': 0,
    'mapShapeLongitude': 0,
    'mapShapeMapCode': 'default',
    'parameters': [
        {
            'date': '2024-10-06T12:00:00',
            'parameterSettingUuid': 'e3588070-5ccf-47fa-aa9d-e7ca0b929d90',
            'userUuid': 'b0b135db-14f7-4d35-92d8-8357815185de',
            'currentValue': '99',
            'source': 'FROM_WEB_SERVICE'
        }
    ]
}

post_method(server_url, get_header(request_path, "application/json", "application/json"), request_path, json)

Wykonanie przykładów

Przykładowe wyniki zapytań dotyczące dodania historii nadzoru.

json = {
    'invalid': False,
    'timestamp': '2024-10-06T12:00:00',
    'supervisionElementUuid': supervision_element_uuid,
    'userUuid': '75d2b25d-4698-48b9-bb62-7569ffb763fc',
    'supervisionStateTemplateItemUuid': supervision_state_item_uuid,
    'progress': 100,
    'addedCount': 1,
    'locationUuid': '75d2b25d-4698-48b9-bb62-7569ffb763fc',
    'mapShapeLatitude': 0,
    'mapShapeLongitude': 0,
    'mapShapeMapCode': 'default',
    'parameters': [
        {
            'date': '2024-10-06T12:00:00',
            'parameterSettingUuid': 'e3588070-5ccf-47fb-aa9d-e7ca0b929d90',
            'userUuid': '75d2b25d-4698-48b9-bb62-7569ffb763fc',
            'currentValue': '99',
            'source': 'FROM_WEB_SERVICE'
        }
    ]
}

Błędny UUID lokalizacji:

httpd://server.url/rest/amage/v1/supervisions/add-history/1ba796f7-4a56-4ce1-ad6c-6d9c528974ad
received return code: 400
received data: {"id":null,"uuid":null,"success":false,"errorCode":400,"message":"Location not found with UUID: 75d2b25d-4698-48b9-bb62-7569ffb763fc"}

Błędny UUID użytkownika, brak lokalizacji:

/usr/bin/python3 example_supervision.py
http://localhost:8000/assetweb/rest/amage/v1/supervisions/add-history/1ba796f7-4a56-4ce1-ad6c-6d9c528974ad
received return code: 400
received data: {"id":null,"uuid":null,"success":false,"errorCode":400,"message":"User not found with UUID: 75d2b25d-4698-48b9-bb62-7569ffb763fc"}

Poprawne dane:

json = {
    'invalid': False,
    'timestamp': '2024-10-06T12:00:00',
    'supervisionElementUuid': supervision_element_uuid,
    'userUuid': 'b0b135db-14f7-4d35-92d8-8357815185df',
    'supervisionStateTemplateItemUuid': supervision_state_item_uuid,
    'progress': 100,
    'addedCount': 1,
    'mapShapeLatitude': 0,
    'mapShapeLongitude': 0,
    'mapShapeMapCode': 'default',
    'parameters': [
        {
            'date': '2024-10-06T12:00:00',
            'parameterSettingUuid': 'e3588070-5ccf-47fb-aa9d-e7ca0b929d90',
            'userUuid': 'b0b135db-14f7-4d35-92d8-8357815185df',
            'currentValue': '99',
            'source': 'FROM_WEB_SERVICE'
        }
    ]
}
/usr/bin/python3 example_supervision.py
http://server.url/rest/amage/v1/supervisions/add-history/1ba796f7-4a56-4ce1-ad6c-6d9c528974ad
received return code: 200
received data: {"id":1000816683,"uuid":"d020d04c-756c-453e-8458-28590dc5c0fa","success":true,"errorCode":0,"message":""}

Process finished with exit code 0