Interfejs REST API AMAGE - załączniki

Wstęp/Kontekst

Kontekst dla pobierania załączników w systemie AMAGE, którą należy w zapytaniu rozszerzony o odpowiednią metodę.

  • rest/amage/v1/attachments

Struktury danych

Struktury i typy danych wykorzystywane w zapytaniach i odpowiedziach.

Typ obiektów, na których wykonujemy operacje z załącznikami

  • object-type - typ obiektu, dla którego chcemy pobrać załączniki. Możliwe wartości:

    • folder - folder w strukturze

    • asset - zasób

    • element-type - typ elementów

    • work-order - zlecenie pracy

Lista głównych katalogów

Wyświetla listę katalogów głównych w systemie AMAGE.

  • Metoda: GET

  • Ścieżka: /list/folders

  • Generuje: application/json

  • Wymaga: text/plain, application/json

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

Zwraca listę wszystkich folderów głównych w systemie AMAGE.

Zapytanie

/rest/amage/v1/attachments/list/folders/

Odpowiedź

[
  {"uuid":"f6b0430e-e441-4927-adaf-bbaf0099aa2b","name":"Test 1"},
  {"uuid":"a7bcd271-2699-4aea-9aee-e637da12d38a","name":"Test 2"},
  {"uuid":"db01b47c-68aa-4c12-8786-9992201d8ea9","name":"Test 3"}
]

Lista katalogów

Wyświetla listę katalogów w danym katalogu nadrzędnym.

  • Metoda: GET

  • Ścieżka: /list/folders/{parent-uuid}

  • Generuje: application/json

  • Wymaga: text/plain, application/json

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

Zwraca listę wszystkich folderów w danym katalogu nadrzędnym. Jeśli katalog nadrzędny nie istnieje, zwraca pustą listę.

Zapytanie

/rest/amage/v1/attachments/list/folders/f6b0430e-e441-4927-adaf-bbaf0099aa2b

Odpowiedź

[{"uuid":"14f80a0d-b7ae-4ff7-99f6-d5a60a73400d","name":"test 1-1"},{"uuid":"75c90ac5-6ec8-448f-a345-1be0407548b1","name":"test 1-2"}]

Lista kategorii załączników

Zwraca listę kategorii załączników

  • Metoda: GET

  • Ścieżka: /list/attachment-categories

  • Generuje: application/json

  • Wymaga: text/plain, application/json

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

Zwraca listę kategorii załączników dostępnych w systemie. Zwracana nazwa kategorii oraz UUID kategorii.

Zapytanie

/rest/amage/v1/attachments/list/attachment-categories

Odpowiedź

[
  {
    "uuid":"8982a7bb-916e-469a-bce0-1194d7e26844",
    "name":"CATEGORY 1"
  },
  {
    "uuid":"ddb7a579-9a4e-42a0-8384-ce95be56f16c",
    "name":"CATEGORY 2"
  }
]

Lista załączników dla obiektów

Zwraca listę załączników przypisanych do obiektu.

  • Metoda: GET

  • Ścieżka: list/by-object/{object-type}/{uuid}

  • Generuje: application/json

  • Wymaga: text/plain, application/json

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

W zapytaniu object-type to typ obiektu, dla którego chcemy pobrać załączniki. Możliwe wartości podane w sekcji "Struktury danych". UUID to identyfikator obiektu, dla którego chcemy pobrać załączniki. W odpowiedzi otrzymamy listę załączników przypisanych do obiektu. Każdy załącznik zawiera UUID, nazwę pliku, hash MD5 oraz rozmiar pliku. Jeśli nie znajdujemy obiektu, to zwracana jest pusta lista.

Zapytanie

/rest/amage/v1/attachments/list/by-object/folder/f6b0430e-e441-4927-adaf-bbaf0099aa2b

Odpowiedź

[
  {
    "uuid":"be80c1f3-b2e7-4617-9767-d0c516e836d4",
    "fileName":"file1.jpg",
    "hash":"14DAED0F5B6A3B1147D75458DF910BAC",
    "fileSize":3710094
  },
  {
    "uuid":"079e76d6-c360-4c76-b6d5-cb98d6132f91",
    "fileName":"file2.jpg",
    "hash":"275635D68FCB03543DDF3695C9C43746",
    "fileSize":295349
  }
]

Pobranie załącznika po podaniu UUID

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: get/by-uuid/{uuid}

  • Generuje: application/octet-stream

  • Wymaga: text/plain, application/json

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

UUID to identyfikator załącznika, który chcemy pobrać.

Po wykonaniu zapytania w odpowiedzi otrzymamy plik binarny, który należy zapisać na dysku lokalnym. Kod przykładu w Pythonie poniżej.

Zapytanie

/rest/amage/v1/attachments/get/by-uuid/e900899f-8899-414c-9570-6bb3ed69cf9d

Odpowiedź

<plik binarny>

Pobranie załącznika po podaniu HASH MD5 załącznika

Pobiernie załącznika z systemu AMAGE po podaniu jego hashu MD5. W zapytaniu należy podać hash MD5 załącznika, który chcemy pobrać. W odpowiedzi otrzymamy plik binarny, który należy zapisać na dysku lokalnym.

  • Metoda: GET

  • Ścieżka: /get/by-hash/{hash}

  • Generuje: application/octet-stream

  • Wymaga: text/plain, application/json

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

HASH to hash MD5 załącznika, który chcemy pobrać.

Zapytanie

/rest/amage/v1/attachments/get/by-hash/275635D68FCB03543DDF3695C9C43746

Odpowiedź

<plik binarny>

Wgranie pliku do obiektu

Pozwala wgrać plik do obiektu w systemie AMAGE. W zapytaniu należy podać typ obiektu, do którego chcemy wgrać plik, UUID obiektu oraz plik, który chcemy wgrać. W odpowiedzi otrzymamy UUID załącznika, hash MD5 oraz informację o powodzeniu operacji.

  • Metoda: PUT

  • Ścieżka: /put/to-object/{object-type}/{uuid}

  • Generuje: application/json

  • Wymaga: multipart/form-data

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

W zapytaniu należy podać następujące parametry:

  • filename - nazwa pliku jako parametr URL

  • public - czy plik ma być publiczny (true/false) jako parametr URL

  • category-uuid - UUID kategorii załączników

  • file (Multipart) - plik, który chcemy wgrać do obiektu w formacie Multipart

Zapytanie

/rest/amage/v1/attachments/put/to-object/element-type/1c4066e6-cdd6-4903-803a-b6bffe689527?filename=item.png&public=true&category-uuid=feed29b6-d093-42af-8de6-7bda99c37a3b

<plik binarny>

Odpowiedź

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

Odpowiedź błędna (błędnie podany UUID kategorii załącznika)

Kod odpowiedzi: BAD_REQUEST (400)

Odpowiedź

{
    "uuid": null,
    "hash": "",
    "success": false,
    "errorCode": 404,
    "message":"Attachment Category not found"
}

Dołączenie istniejącego pliku do innego obiektu

Pozwala dołączyć już istniejący plik w systemie AMAGE do innego obiektu. W zapytaniu należy podać typ obiektu, do którego chcemy wgrać plik, UUID obiektu oraz UUID załącznika, który będziemy łączyć do nowego obiektu. W odpowiedzi otrzymamy UUID nowego załącznika, hash MD5 oraz informację o powodzeniu operacji.

  • Metoda: POST

  • Ścieżka: /join/to-object-by-uuid/{object-type}/{uuid}

  • Generuje: application/json

  • Wymaga: application/json, text/plain

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

W zapytaniu należy podać następujące parametry:

  • attachment-uuid - UUID załącznika, który chcemy dołączyć do nowego obiektu

  • filename - nazwa pliku jako parametr URL

  • public - czy plik ma być publiczny (true/false) jako parametr URL

  • category-uuid - UUID kategorii załączników

Zapytanie

/rest/amage/v1/attachments/join/to-object-by-uuid/element-type/1c4066e6-cdd6-4903-803a-b6bffe689527?filename=item.png&public=true&category-uuid=feed29b6-d093-42af-8de6-7bda99c37a3b&attachment-uuid=455d6797-625f-467b-9640-cb9ee5d9d449

Odpowiedź

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

Aktualizacja załącznika

Aktualizujemy parametry istniejącego załącznika. Podajemy UUID załącznika oraz nowe parametry takie jak nazwa pliku, UUID kategorii załącznika oraz status publiczny/prywatny. System aktualizuje informacje.

  • Metoda: POST

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

  • Generuje: application/json

  • Wymaga: application/json, text/plain

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

W zapytaniu należy podać następujące parametry:

  • uuid - UUID załącznika, który modyfikujemy

  • filename - nazwa pliku jako parametr URL

  • public - czy plik ma być publiczny (true/false) jako parametr URL

  • category-uuid - UUID kategorii załączników

Zapytanie

/rest/amage/v1/attachments/update/1c4066e6-cdd6-4903-803a-b6bffe689527?filename=newitem.png&public=false&category-uuid=feed29b6-d093-42af-8de6-7bda99c37a3b

Odpowiedź

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

Usunięcie załącznika

Usuwamy załącznik. Podajemy UUID załącznika, który chcemy usunąć. System usuwa załącznik z systemu. System sprawdza podłączenie załącznika do innych obiektów i w przypadku, gdy załącznik jest podłączony do innych obiektów, które nie są jego źródłowym obiektem (np. dokumentacja zasobu), to nie pozwala na usunięcie załącznika.

  • Metoda: DELETE

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

  • Generuje: application/json

  • Wymaga: application/json, text/plain

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

W zapytaniu należy podać następujące parametry:

  • uuid - UUID załącznika, który modyfikujemy

Zapytanie

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

Odpowiedź

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

Przykład pobierania załącznika w Pythonie

import binascii
import requests
import hashlib

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 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:
            print("received return code: {0}".format(r.status_code))
            for chunk in r.iter_content(chunk_size=8192):
                f.write(chunk)
    return local_filename


# define local filename
local_filename = r"/home/user/filename.pdf"
attachment_uuid = "67dc0c69-b1f3-437e-8d9b-f4722bffe2ab"
request_path = 'attachments/get/by-uuid/' + attachment_uuid

# define headers' values
device_uuid = "75d2b25d-4698-48b9-bb62-7569ffb763fc"
api_key = "690f8eaecc5743bfcd82121a15abb5b1"
api_secret = "f4affb2db24b2b0903ad89ceeb622ece"
api_sign = binascii.hexlify(calc_api_sign(request_path, api_secret)).decode()

# define url
url = "https://app.amage24.com/999-99/rest/amage/v1/" + request_path

# define headers
headers = {
    "Content-Type": "text/plain",
    "Accept": "application/octet-stream",
    "amage-device-uuid": device_uuid,
    "amage-api-key": api_key,
    "amage-api-sign": api_sign
}

# download file
download_file(url, headers, local_filename)

Przykład wysyłania pliku do serwera za pomocą kodu w Pythonie

#!/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 put_file(server_url, headers, filename, path):
    if 'Content-Type' in headers:
        del headers['Content-Type']

    print(server_url + path)
    with open(filename, 'rb') as f:
        files = {'file': (filename, f)}
        response = requests.put(server_url + path, headers=headers, files=files)
        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

local_filename = "item.png"
asset_uuid = "bb424ebd-5bba-49aa-8503-2edc31f5fc05"

server_url = "https://amage-server-example.com/999-99/rest/amage/v1/"

device_uuid = "75d2b25d-4698-48b9-ca23-7569343323fc"
api_key = "690f8eaecc574343543521a15abb5b1"
api_secret = "f4affb2d234246903ad89ceeb622ece"

# dodaje plik do zasobu
put_file(server_url, get_header("attachments/put/to-object/asset/" + asset_uuid, "multipart/form-data", "application/json"), local_filename
"attachments/put/to-object/asset/" + asset_uuid + "?filename=" + local_filename + "&public=true")