Interfejs REST API AMAGE - zasoby/parametry

Wstęp/Kontekst

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

rest/amage/v1/assets

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":""
}

Typ parametru. Element wyliczeniowy, który określa typ parametru (ParameterType):

STRING,
FLOAT,
INTEGER,
ENUM,
DATETIME,
DATE,
TIME

Ź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

Typ identyfikatora

BARCODE,
DATAMATRIX
QRCODE
RFID_LF
RFID_HF
RFID_MIFARE
RFID_UHF
BEACON

Typ załącznika:

TEXT("txt")
HTML("html", "htm")
SPEECH("spc")
AUDIO("wav", "mp2", "mp3")
VIDEO("avi", "mpeg", "mp4", "mov")
PHOTO("jpg", "jpeg", "png", "bmp", "gif")
PDF("pdf")
OFFICE("doc", "docx", "xls", "xlsx", "xlsm", "odt", "ods")
MODEL3D("j3o", "obj")
IFC("ifc")
BINARY()

Operacje API

Pobieranie liczby zasobów/produktów

Metoda: GET
Ścieżka: /count
Generuje: text/plain
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Zwraca liczbę wszystkich zasobów w systemie.

{
    123456
}

Pobranie listy zasobów

Metoda: GET
Ścieżka: /list
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

page - RequestParam - strona - liczona od 1
size - RequestParam - rozmiar strony - liczba rekordów na stronie, sugerujemy ograniczenie do 1000 elementów. W zależności od implementacji API, wartość może być ograniczona do mniejszej liczby.

Zwracane dane to obiekt JSON ze strukturą:

{
    "id": 12345,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "globalId": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "ifcTag": "1sd3df3d3dfd",

    "name": "Nazwa elementu",
    "serialNumber": "123456",
    "inventoryNumber": "123456",
    "count": 123.45,
    "note": "Notatka",

    "parentUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "typeUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "groupUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "locationUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "objectStateUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",

    "mapShapeLatitude": 123.45,
    "mapShapeLongitude": 123.45,
    "mapShapeMapCode": "default",

    "identifierList": [
        {
            "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "value": "P1234-445644",
            "type": "DATAMATRIX"
        }
    ],

    "attachmentList": [
        {
            "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "fileName": "plik.pdf",
            "attachmentType": "PDF",
            "hash": "c1534f7c2e65f4b93e284c6f878c1ba1"
        }
    ],

    "parameterSettingList": [
        {
            "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "parameterName": "parametr",
            "parameterUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "value": "Testowa wartość",
            "availability": true,
            "userUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "timestamp": "2021-01-01T12:00:00"
        }
    ],

    "contractUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "contractScopeUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "customerUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "recipientUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "dateOfProduction": "2021-01-01T12:00:00",
    "dateOfSale": "2021-01-01T12:00:00",
    "dateOfCommissioning": "2021-01-01T12:00:00",
    "warrantyExpirationDate": "2021-01-01T12:00:00",
    "warrantyPeriod": 123,
    "customWarranty": true,

    "equipmentObjectStateUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "equipmentEnabled": true,
    "equipmentOwnerUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "equipmentHolderUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "equipmentRequesterUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "equipmentCheckerUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "equipmentValidTillDate": "2021-01-01T12:00:00",
    "equipmentTestingLaboratoryUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "equipmentValidationDocument": "Dokument.pdf",
    "equipmentValidationNotes": "Notatka"

}

Identifier:

{

    "id": 12345,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "value": "X-234-222",
    "type": "DATAMATRIX"
}

Attachment:

{

    "id": 12345,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "fileName": "plik.pdf",
    "attachmentType": "PDF",
    "hash": "c1534f7c2e65f4b93e284c6f878c1ba1"
}

ParameterSetting:

{

    "id": 12345,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "parameterName": "parametr",
    "parameterUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "value": "Testowa wartość",
    "availability": true,
    "userUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "timestamp": "2021-01-01T12:00:00"
}

Pobranie zasobu/produktu po UUID

Metoda: GET
Ścieżka: /get/by-uuid/{uuid}
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

UUID - identyfikator zasobu/produktu

Zwracane dane to pojedynczy obiekt JSON ze strukturą zasobu tożsamą z metodą /list.

Dodanie nowego zasobu

Metoda: PUT
Ścieżka: /add
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

ProductDto - BodyContent - struktura JSON tożsama z pojedynczym elementem z metody /list. Pole ID zostanie zastąpione podczas zapisu rekordu

Zwracane dane to obiekt odpowiedzi z polem ID/UUID nowo utworzonego typu elementów.

Aktualizacja zasobu/produktu

Metoda: POST
Ścieżka: /update/{uuid}
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

UUID - identyfikator zasobu/produktu
ProductDto - BodyContent - struktura JSON tożsama z pojedynczym elementem z metody /list. Pole ID/UUID zostają zignorowane podczas aktualizacji.

Zwracane dane to obiekt odpowiedzi z polem ID/UUID modyfikowanego typu elementów.

W przypadku tej metody próba zmiany typu elementu się nie powiedzie. Wykorzystaj metodę /update-type/{uuid}/to/{element-type-uuid} do zmiany typu elementu, która zajmie się procedurą połączenia parametrów pochodzących ze starego i nowego typu elementów. Ma to na celu uniknięcie problemu związanego z utratą danych parametrów po zmianie typu elementu.

W przypadku aktualizacji listy identyfikatorów, parametrów i załączników system sprawdza istnienie danego obiektu - za pomocą identyfikatora UUID w liście elementów zasobu. Jeśli już istnieje, to jest aktualizowany lub pomijany w dodawaniu.

Aktualizacja typu elementu

Metoda: POST
Ścieżka: /update-type/{uuid}/to/{element-type-uuid}
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

uuid - identyfikator zasobu/produktu
element-type-uuid - identyfikator UUID nowego typu elementów

Operacja dedykowana specjalnie dla zmiany typu elementu dla danego zasobu. Wyciągnięta ze standardowej procedury /update ze względu na konieczność operowania na parametrach/ustawieniach parametrów w powiązanych rekordach. Aplikacja w trakcie wykonywania tej operacji przeprowadza procedurę POŁĄCZENIA parametrów istniejących w nowym typie elementów ORAZ parametrów ze starego typu elementu. Spowodowane to jest chęcią zachowania pełnej historii zmian ustawień parametrów pomiędzy zmianą typów. W przeciwnym przypadku istniałaby możliwość usunięcia historii zmiany parametrów zasobu w przypadku zmiany typu elementu.

Realizowane działania:

Ustawienia parametrów w oryginalnym zasobie (przed zmianą) są przepisywane do nowego zasobu (po zmianie)
Jeśli w nowym typie elementów ISTNIEJE parametr o takiej samej nazwie jak w oryginalnym typie elementów, to wartość ustawienia parametru z oryginalnego zasobu jest przepisywana do nowego zasobu (zamieniane jest wskazanie na parametr w nowym typie)
Jeśli w starym typie istniał parametr np. "długość", a w nowym typie elementów nie jest on dostępny, to procedura automatycznie DODA ten parametr do nowego typu elementów i powiąże go z ustawieniem parametru z oryginalnego zasobu
Nowe ustawienia parametrów są ustawiane zgodnie z definicją domyślnych wartości w nowym typie.

Taka operacja pozwala na zachowanie pełnej historii zmian parametrów zasobu w przypadku zmiany typu elementu. Użytkownik za pomocą dodatkowych operacji dotyczących określonych ustawień parametrów może zaktualizować wartości lub je usunąć, ale z pełną kontrolą nad historią zmian.

Usunięcie zasobu

Metoda: DELETE
Ścieżka: /delete/{uuid}
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

uuid - identyfikator UUID zasobu/produktu

Zwracane dane to obiekt odpowiedzi z polem ID/UUID usuwanego zasobu/produktu.

Usunięcie zasobu może się nie powieść ze względu na powiązanie zasobu z innymi rekordami w systemie. W takim przypadku zwrócony zostanie błąd z informacją dotyczącą problemu.

Odczytanie wartości ustawień parametru

Metoda: GET
Ścieżka: /parametersetting/{uuid}
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

UUID - identyfikator ustawień parametru w zasobie

Zwracane dane to obiekt JSON ze strukturą:

{
    "id": 12345,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "parameter": {
        "id": 34567,
        "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
        "name": "parametr",
        "description": "opis parametru",
        "category": "kategoria parametru",
        "type": "STRING"
    },
    "value": "Testowa wartość",
    "availability": true,
    "userUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "timestamp": "2021-01-01T12:00:00"
}

Zapisanie historii do istniejącego ustawienia parametru

Metoda: POST
Ścieżka: /add-parametersetting-history/{uuid}
Generuje: application/json
Wymaga: application/json
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

UUID - identyfikator ustawień parametru

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

{
    "date": "2021-01-01T12:00:00",
    "parameterSettingUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "userUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "currentValue": "Testowa wartość",
    "source": "FROM_WEB_SERVICE"
}

Zapytanie

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

Odpowiedź

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