Wykorzystanie i użycie komunikacji REST API w systemie AMAGE
Wstęp
System AMAGE udostępnia możliwość komunikacji z zewnętrznymi systemami za pomocą REST API. W celu ułatwienia integracji z systemem AMAGE udostępniamy przykładowe skrypty, które mogą być wykorzystane do integracji z systemem AMAGE. W tym dokumencie przedstawiamy przykłady wykorzystania REST API w systemie AMAGE.
Klucze API, autoryzacja i nagłówki danych
Aby umożliwić dostęp do interfejsu API oraz mieć możliwość komunikacji się poprzez ten interfejs, musimy utworzyć klucze API służące do autoryzacji/podpisywania zapytań, tak aby system AMAGE był w stanie poprawnie rozpoznać zapytanie i udostępnić dane. Wygeneruj klucze API w sekcji konfiguracji i nie zapomnij go aktywować. Zapisz trzy parametry - device-uuid, klucz oraz sekret, które zostaną użyte do generowania podpisu zapytania.
Więcej:
Identyfikacja obiektów/UUID
Obiekty w systemie identyfikują się poprzez swój unikalny identyfikator UUID. W celu pobrania obiektu z systemu należy znać jego UUID. UUID można znaleźć w interfejsie użytkownika, w plikach eksportu, w bazie danych, w logach systemowych. Zwykle w interfejsie użytkownika, dla każdego obiektu pojawia się dodatkowy przycisk w podglądzie danych lub jego edytorze z ikoną (I). Po jego wybraniu wyświetla się informacja o danych identyfikacyjnych obiektu, w tym UUID. Użyj tego UUID do interakcji, tam gdzie wymagane jest podanie UUID.
Podpis API
Do każdej komunikacji z systemem AMAGE przez interfejs REST wymagane jest dołączenie trzech nagłówków (headers) z danymi:
-
amage-device-uuid- identyfikator urządzenia, dla którego generowany jest podpis -
amage-api-key- klucz API -
amage-api-sign- podpis zapytania
Device UUID oraz klucz API podajemy bezpośrednio z wygenerowanego klucza API. Podpis generowany jest na podstawie ścieżki zapytania oraz sekretu klucza API. Podpis jest generowany za pomocą algorytmu SHA-256, a wynik jest przekazywany w postaci binarnej. Następnie wynik jest konwertowany do postaci szesnastkowej i przekazywany jako nagłówek amage-api-sign.
Więcej w przykładach kodu poniżej.
Przykład Pobranie załącznika
Aby pobrać załącznik z systemu AMAGE, należy wykonać zapytanie HTTP GET na odpowiedni adres URL. W zapytaniu należy podać UUID załącznika, który chcemy pobrać. W odpowiedzi otrzymamy plik binarny, który należy zapisać na dysku lokalnym.
Metoda: GET Ścieżka: rest/amage/v1/attachment/get/by-uuid/{uuid} Generuje: APPLICATION_OCTET_STREAM_VALUE Wymaga: TEXT_PLAIN_VALUE, APPLICATION_JSON_VALUE Autoryzacja: podpis API (device-uuid, api-key, api-sign)
Po wykonaniu zapytania w odpowiedzi otrzymamy plik binarny, który należy zapisać na dysku lokalnym. Kod przykładu w Pythonie poniżej.
Przykłady pobrania treści raportu w formacie JSON
Aby otrzymać treść raportu z systemu AMAGE, należy wykonać zapytanie HTTP GET na odpowiedni adres URL. W zapytaniu należy podać UUID zakładki raportu, który chcemy pobrać. W odpowiedzi otrzymamy dane JSON, które można przetworzyć w dowolny sposób. W tm przypadku (dla raportów) możemy przesyłać w zapytaniu parametry device-uuid, api-key oraz bezpośrednio api-secret. Ułatwia to generowanie zapytań i wykorzystani API raportów przy pomocy systemów Business Intelligence (BI). Należy podkreślić, że metoda z podpisywaniem za pomocą api-sign zawsze działa.
Metoda: GET Ścieżka: rest/amage/v1/reports/generate/raw-json/by-bookmark-uuid/{uuid}
Przykładowe wywołanie poprzez HTTP Client:
Wynik zapytania dla raportu w formacie JSON:
{
"item": {
"GROUP_UUID": "",
"INVENTORY_NUMBER": "X/23/333/2023",
"TESTING_LABORATORY_UUID": "",
"MANUFACTURER_NAME": "AMAGE",
"TYPE_MANUFACTURER_UUID": "b133c9d3-a018-405e-b632-d124ea5c342e",
"SERIAL_NUMBER": "XX15/1/1[A]",
"MANUFACTURER_UUID": "b133c9d3-a018-405e-b632-d124ea5c342e",
"TYPE_MANUFACTURER_NAME": "AMAGE",
"MAP_SHAPE_MAP_NAME": "",
"NOTE": "Testowe urządzenie",
"PARENT_NAME": "100DE15 SPOOL-1",
"IS_EQUIPMENT": "false",
"UUID": "1d3b6c7a-d522-4062-9f23-3376694a6ac5",
"TESTING_LABORATORY_NAME": "",
"PARENT_UUID": "da6243db-abef-44ee-b535-3b1556de6407",
"IDENTIFIERS": " ",
"TYPE_CATALOG_NUMBER": "",
"LOCATION_UUID": "",
"NAME": "100DE15 SPOOL-1 PT-NO-1[A] IC 26_LL PIPE SL, CS, CE, TC2, 114.3X6.3",
"TYPE_UUID": "b4b0c37e-7c39-4946-ab81-7c373c17e37c",
"GROUP_NAME": "",
"TYPE_ORDER_NUMBER": "",
"EQUIPMENT_VALID_TILL_DATE": "-",
"MAP_SHAPE_LONGITUDE": "",
"MAP_SHAPE_LATITUDE": "",
"COUNT": "0,00",
"TYPE_NAME": "Element Produktu",
"LOCATION_NAME": ""
}
}Przykład Python
Kod w przykładzie poniżej przedstawia skrypt w języku Python, który pobiera załącznik z systemu AMAGE. Skrypt wykorzystuje bibliotekę requests do komunikacji z serwerem oraz hashlib do generowania podpisu API. W miejscu <amage_server_address> należy podać adres serwera AMAGE.
#!/usr/bin/python3
import binascii
import requests
import hashlib
PARAM_SEPARATOR = ";"
path = 'attachment/get/by-uuid/d18ed480-febd-4f0c-a979-a773bca83423'
device_uuid = "86947df1-ba7d-46d7-83a8-a90e1fdca8bf"
api_key = "e3d1acd2c8b5e47d9e612cf46f08523f"
api_secret = "7fe1cde52dc14ecc4b222090c72b4380"
def calc_api_sign(path, api_secret):
message_digest = hashlib.sha256()
message_digest.update(api_secret)
message_digest.update(PARAM_SEPARATOR.encode('utf-8'))
message_digest.update(path.encode('utf-8'))
return message_digest.digest()
def download_file(url, headers, local_filename):
with requests.get(url, headers=headers, stream=True) as r:
r.raise_for_status()
with open(local_filename, 'wb') as f:
for chunk in r.iter_content(chunk_size=8192):
f.write(chunk)
return local_filename
api_sign = binascii.hexlify(calc_api_sign(path, bytearray.fromhex(api_secret))).decode()
url = "https://<amage_server_address>/rest/amage/v1/" + path
headers = {
"Content-Type": "text/plain",
"Accept": "application/octet-stream",
"amage-device-uuid": device_uuid,
"amage-api-key": api_key,
"amage-api-sign": api_sign
}
local_filename = "item.png"
download_file(url, headers, local_filename)Więcej
| Howto powstało na bazie wersji systemu 1.27.0.0 (05.2024) oraz przedstawia funkcje, które mogą nie być dostępne w Twoim systemie. Zapytaj AMAGE o udostępnienie tej funkcjonalności. |
| Ze względu na ciągły rozwój systemu niektóre ekrany lub pliki konfiguracji mogą wyglądać nieznacznie inaczej, ale zachowają nadal pełną funkcjonalność tutaj opisaną. Nie wpływa to na zasadnicze funkcje opisywane w tym dokumencie. |