Ogólne API: typy akcji
preautoryzacja
Aby uwierzytelnić użytkownika, zapytaj o typ akcji preauth pierwszy. Wraz ze swoim żądaniem wyślij nazwę użytkownika, a otrzymasz informację, czy użytkownik musi się zalogować za pomocą hasła i/lub 2Factor, czy też konieczne jest przekierowanie na serwery firm trzecich (SAML/OAuth).
Przykład wprowadzania:
{
"accessType": 0|1|2|...,
"kname": "...", //Username
"api_key": "" //API-Key
}Przykład wyjścia:
{
...
"data":
{
"sso_type": 0/1/2/3,
"sso_redirect": "https://...",
"twofactor_type": 0/1/2/3,
"twofactor_required": true|false
}
}Odpowiedź zawiera następujące informacje:
| Pole | Opis Projektu |
sso_type |
Rodzaj jednokrotnego logowania: 0: Nie 2FA 1: LDAP 2: SAML 3: Autoryzacja OAuth |
sso_redirect |
Adres URL, do którego ma zostać przekierowany użytkownik (używany z SAML + OAuth) |
twofactor_type |
Rodzaj autoryzacji dwuetapowej 0: Nie 2FA 1: hasło jednorazowe 2: E-mail 3: SMS-y |
twofactor_required |
Czy drugi czynnik jest wymagany (wszystkie typy twofactor_types, z wyjątkiem 0) |
Uwaga: Kiedy a sso_redirect URL jest obecny, musisz przekazać użytkownika do punktu końcowego SSO w celu uwierzytelnienia. Po powrocie użytkownika możesz przejść do kolejnych kroków uwierzytelniania.
Uwaga: W przypadkach, gdy e-mail lub SMS są używane jako uwierzytelnianie dwuskładnikowe, system automatycznie wyśle e-mail/sms z żądaniem wstępnego autoryzacji.
auth
W celu uwierzytelnienia użytkownika użyj typu akcji auth. Wraz z żądaniem wyślij nazwę użytkownika i hasło (i kod 2FA, jeśli to konieczne), a w odpowiedzi otrzymasz token uwierzytelniający. Token może być następnie wykorzystany do przetwarzania kolejnych żądań.
Przykład wprowadzania:
{
"accessType": 0|1|2|...,
"kname": "...", //Username
"kpass": "...", //Password
"2fa": "...", //optional
"longlife": 0|1 , //optional
"api_key": "" //optional
}Przykład wyjścia:
{
...
"data":
{
"kmd":"token"
}
}Zapisz wartość znalezioną pod kmd i wysyłaj go we wszystkich kolejnych wywołaniach do API jako wartość wejściową kmd.
Uwaga: w przypadku uwierzytelniania dwuskładnikowego należy zadzwonić do auth zwróci kod błędu w zależności od metody uwierzytelniania, jeśli 2fa nie został wysłany. Jeśli tak jest, będziesz musiał pokazać użytkownikowi stronę Two Factor Authentication, która pasuje do kodu błędu (np. w celu wprowadzenia kodu e-mail lub OTP). Użyj tokena (kmd) otrzymany i użyty przez Ciebie verifyauth w celu (ponownie) przesłania kodu 2fa.
weryfikacja
Akcja verifyauth może służyć do sprawdzenia, czy token (kmd) jest nadal ważny i/lub przesłać kod 2fa do uwierzytelniania dwuskładnikowego.
Przykład wprowadzania:
{
"accessType": 0|1|2|...,
"token": "...", //Token from auth
"2fa": "...", //2fa code
}Przykład wyjścia:
{
...
"data":
{
"kmd":"token"
}
}Zapisz wartość znalezioną pod kmd i wysyłaj go we wszystkich kolejnych wywołaniach do API jako wartość wejściową kmd.
wyloguj się
Opona logout akcja kończy istniejącą sesję (wylogowanie).
Przykład wprowadzania:
{
"accessType": 0|1|2|...,
"token": "...", //Token from auth
}prawa
Rodzaj działania rights może być używany w celu uzyskania przeglądu modeli i działań, do których użytkownik ma prawa dostępu.
Przykład wprowadzania:
{
"accessType": 0|1|2|...,
"token": "..."
}Przykład wyjścia:
{
...
"data":
[
{
"model": "User",
"actions": ["get","list","update"]
},
{
"model": "Subaccount",
"actions": ["get","list","update","create","delete","deleteinfo"]
}
]
}podstęp
Rodzaj akcji list może służyć do żądania listy wpisów konkretnego modelu z bazy danych. Ten typ akcji ma służyć do oferowania użytkownikowi przeglądu elementów (zamiast przedstawiania konkretnych szczegółów).
Oczekiwany przykład danych wejściowych:
{
...
"filters": [...], // Filters to apply, see description (optional)
"limit": 100, // Limit of output rows (optional)
"offset": 0, // Start index of first row (optional)
"order": "...", // Column to sort (optional)
"sort": "asc|desc", // Sorting direction of output (optional)
"cols": [...] // If set, will output the named fields, otherwise a default set of fields will be shown
//optional: "assoc": true // If set, returns and associative array instead of a data list
//optional: "dataonly": true // If set, returns the data list only (no header information)
}Wyjściowy przykład odpowiedzi:
{
"status": "Success",
"statuscode": 0,
"msg": "Erfolgreich",
"model": "Subaccount",
"action": "list",
"data":
{
"data":
[
{
"id": "542",
"row":
[
"542",
"aaa",
"Aktiv"
]
},
{
"id": "543",
"row":
[
"543",
"bbb",
"Aktiv"
]
}
],
"head":
[
{
"headline": "ID",
"colsort": false,
"colorder": "intID",
"colname": "intID"
},
{
"headlineType": "string",
"headline": "Nutzername",
"colsort": false,
"colorder": "strLogin",
"colname": "strLogin"
},
{
"headlineType": "string",
"headline": "Status",
"colsort": false,
"colorder": "intStatus",
"colname": "intStatus"
}
],
"caption": "User",
"count": 2,
"total": 2
}
}Dane wyjściowe składają się z data tablica i odpowiadająca jej tablica nagłówkowa. Tablica danych zawiera wiersze, które mają być wyświetlane użytkownikowi. Tablica head będzie zawierać określone informacje dotyczące nagłówka (np. sortowanie, tekst nagłówka itd.) dla każdej kolumny tabeli.
Powyższe przykładowe dane skutkowałyby wyświetleniem poniższej tabeli:
Przeliczone wartości
Dla pól listy typów (podtypy pól 1, 2 i 12) możesz użyć sufiksu :convert in cols właściwość żądania w celu uzyskania czytelnej wartości treści zamiast wartości surowej (np. nazwa kolumny zamiast identyfikatora). Jeśli zostanie znaleziona kolumna z tym przyrostkiem, dane wyjściowe będą zawierały kolumnę dwukrotnie, raz jako wartość surową i raz jako wartość przekonwertowaną.
Oczekiwany przykład danych wejściowych:
{
...
"model": "Design",
"action": "list",
"cols": ['strName', 'intPosition:convert']
}Wyjściowy przykład odpowiedzi:
{
...
"data":
{
"data":
[
{
"id": "542",
"row":
[
"myDesign",
"3",
"Center middle"
]
},
...
],
"head":
[
{
"headline": "name",
"colsort": false,
"colorder": "strName",
"colname": "strName"
},
{
"headline": "Position",
"colsort": false,
"colorder": "intPosition",
"colname": "intPosition"
},
{
"headline": "Position",
"colsort": false,
"colorder": "intPosition",
"colname": "intPosition:convert"
}
],
...
}
}filtry
filters Właściwość w żądaniu JSON może być użyta w celu wyszukania określonych elementów lub zmniejszenia listy wyników. ten filters właściwość składa się z tablicy elementów filtra. Każdy przedmiot jest przedmiotem o następującej strukturze:{
"fieldname": "...", // Field the filter should apply to
"comparison": "...", // (optional) Comparison type, see description
"value" : "..." // Value to compare the field to
}Aby przeszukać wszystkie pola, nazwa pola query może być użyty.
Możliwy comparison wartości to:
| Typ porównania | Opis Projektu |
eql |
Równy. Znajdź wiersze, w których zawartość fieldname jest dokładnie taki sam jak value. (Ten typ jest domyślny, jeśli comparison nie jest używany w obiekcie.) |
lt |
Niższe niż. Znajdź wiersze, w których zawartość fieldname jest mniejszy od value. |
gt |
Lepszy niż. Znajdź wiersze, w których zawartość fieldname jest większa value. |
lte |
Niższe niż/równe. Znajdź wiersze, w których zawartość fieldname jest mniejszy od value lub równy value. |
gte |
Większe niż/równe. Znajdź wiersze, w których zawartość fieldname jest większa value lub równy value. |
like |
Zawiera. Znajdź wiersze, w których value jest zawarty w treści fieldname (w części lub w całości). |
in |
Jest na liście. Znajdź wiersze, w których zawartość fieldname jest dokładnie taki sam jak jeden z value. W tym przypadku value powinna być tablicą. |
is |
jest NULL. Znajdź wiersze, w których zawartość fieldname is NULL. |
isnot |
Nie jest NULL. Znajdź wiersze, w których zawartość fieldname nie jest NULL. |
Przykład:
{
...
"filters":
[
{
"fieldname": "age",
"comparison": "gte",
"value" : 27
},
{
"fieldname": "lastname",
"comparison": "like",
"value" : "man"
}
]
}... znajdzie wiersze, w których age jest równy lub większy niż 27 i lastname zawiera człowieka (np. Hofmann lub Superman lub Mandy)
otrzymać
Rodzaj akcji get może służyć do żądania jednego lub więcej wpisów określonego modelu z bazy danych, gdy identyfikatory wpisów są już znane. Zamierzonym zastosowaniem tego typu akcji jest wyświetlenie danych w formularzu do edycji. Stąd odpowiedź dostarczy również szczegółowych informacji o każdym polu.
Oczekiwany przykład danych wejściowych:
{
...
"ids": [...] // Array of IDs
}Proszę wysłać pustą tablicę ids aby uzyskać tylko definicję pola. Może to pomóc w utworzeniu nowego wpisu na podstawie definicji pola.
Wyjściowy przykład odpowiedzi:
{
"status": "Success",
"statuscode": 0,
"msg": "Erfolgreich",
"model": "Subaccount",
"action": "get",
"data":
{
"fields":
[
{
"fieldname": "intID",
"displayname": "ID",
"type": 2,
"subtype": 8,
"required": true,
"defaultvalue": null,
"disabled": false,
"infotext": false,
"value": "542",
"displayvalue": "",
"listkeys": [],
"listvalues": []
},
{
"fieldname": "strLogin",
"displayname": "Nutzername",
"type": 1,
"subtype": 0,
"required": true,
"defaultvalue": null,
"disabled": false,
"infotext": false,
"value": "aaa",
"displayvalue": "aaa",
"listkeys": [],
"listvalues": []
},
{
"fieldname": "strPass",
"displayname": "Passwort",
"type": 1,
"subtype": 5,
"required": true,
"defaultvalue": null,
"disabled": false,
"infotext": false,
"value": "%%unchanged%%",
"displayvalue": "********",
"listkeys": [],
"listvalues": []
},
{
"fieldname": "intStatus",
"displayname": "Status",
"type": 2,
"subtype": 1,
"required": false,
"defaultvalue": null,
"disabled": false,
"infotext": false,
"value": "1",
"displayvalue": "Aktiv",
"listkeys": [ 0, 1 ],
"listvalues": [ "Inaktiv", "Aktiv" ]
}
],
"caption": "User: aaa",
"groups": [],
"ids": [ 542 ],
"canDelete": true,
"canSave": true,
"canSaveNew": true
}
}Powyższy przykład może skutkować formą wyglądającą tak:
Stwórz
W celu stworzenia nowych całości możesz użyć typu akcji create.
Oczekiwany przykład danych wejściowych:
{
"ids": [],
"data": {
"intID": "0",
"strLogin": "new User",
"strPass": "ABCabc123!",
"intStatus": "1"
}
}Dane wyjściowe pomyślnej aktualizacji odpowiadają przykładowi podanemu dla get Rodzaj działania. Przykład wyjścia:
{
"status": "Success",
"statuscode": 0,
"msg": "Erfolgreich",
"model": "Subaccount",
"action": "get",
"previousAction": "create",
"data":
{
"fields": [...],
"caption": "User: new User",
"groups": [],
"subgroups": [],
"ids": [ 544 ],
"canDelete": true,
"canSave": true,
"canSaveNew": true
}
}Należy pamiętać, że create nie powiedzie się, jeśli model o tym samym identyfikatorze już istnieje. Jeśli chcesz zastąpić istniejące ustawienia, możesz wysłać dwa pola insertIgnore (wartość=1) i/lub onDuplicateUpdate (wartość=1). Wysyłanie insertIgnore poinformuje system, aby nie zwracał błędu, jeśli wstawienie nie powiedzie się. onDuplicateUpdate nakazuje systemowi zaktualizowanie wszystkich wartości w przypadku istniejącego elementu o tym samym identyfikatorze.
aktualizacja
Aby zmienić jedną lub więcej istniejących całości, możesz użyć typu akcji update.
Oczekiwany przykład danych wejściowych:
{
"ids": [ 542 ],
"data":
{
"intID": "542",
"strLogin": "aaa",
"strPass": "abcabc",
"intStatus": "1"
}
}Dane wyjściowe pomyślnej aktualizacji odpowiadają przykładowi podanemu dla get Rodzaj działania. Przykład wyjścia:
{
"status": "Success",
"statuscode": 0,
"msg": "Erfolgreich",
"model": "Subaccount",
"action": "get",
"previousAction": "update",
"data":
{
"fields": [...],
"caption": "User: aaa",
"groups": [],
"subgroups": [],
"ids": [ 542 ],
"canDelete": true,
"canSave": true,
"canSaveNew": true
}
}W przypadku błędu aktualizacji system odpowie takim komunikatem o błędzie:
{
"status": "Error",
"statuscode": 113,
"msg": "Update error, see error message. Field specific messages see response.data",
"model": "Subaccount",
"action": "update",
"data":
{
"strLogin": "Wert muss mindestens 6 Zeichen lang sein",
"strPass": "Wert muss Sonderzeichen beinhalten"
}
}usunąć
Rodzaj akcji delete może służyć do usunięcia jednego lub więcej wpisów określonego modelu z bazy danych, gdy identyfikatory wpisów są już znane.
Oczekiwany przykład danych wejściowych:
{
...
"ids": [...] // Array of IDs
}Wyjściowy przykład odpowiedzi:
{
"status": "Success",
"statuscode": 0,
"msg": "Erfolgreich",
"model": "Subaccount",
"action": "create",
"previousAction": "delete",
"data":
{
"fields": [...],
"caption": "User: new User",
"groups": [],
"subgroups": [],
"ids": [ ],
"canDelete": true,
"canSave": true,
"canSaveNew": true
}
}
