Login

Try consentmanager
Book a call

Ogólny interfejs API: typy akcji

preauth

Aby uwierzytelnić użytkownika, proszę najpierw zapytać o typ akcji preauth . Wraz z żądaniem prześlij nazwę użytkownika, a otrzymasz informację, czy użytkownik musi się zalogować za pomocą hasła i/lub uwierzytelnienia dwuskładnikowego, czy też konieczne jest przekierowanie na serwery stron trzecich (SAML/OAuth).

Przykładowe dane wejściowe:

{
  "accessType": 0|1|2|...,
  "kname":      "...",     //Username  
  "api_key":    ""         //API-Key
}

Przykładowy wynik:

{
  ...
  "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:

Dziedzina Opis
sso_type

Rodzaj logowania jednokrotnego:

0: Brak 2FA

1: LDAP

2: SAML

3: OAuth
sso_redirect Adres URL, na który ma zostać przekierowany użytkownik (używany z SAML + OAuth)
twofactor_type

Rodzaj uwierzytelniania dwuskładnikowego

0: Brak 2FA

1: OTP

2: E-mail

3: SMS
twofactor_required Czy wymagany jest drugi czynnik (wszystkie typy dwuskładnikowe, z wyjątkiem 0)

Uwaga: Gdy sso_redirect adres URL, musisz przekierować użytkownika do punktu końcowego SSO w celu uwierzytelnienia. Gdy użytkownik powróci, możesz przejść do kolejnych kroków uwierzytelniania.

Uwaga: W przypadkach, gdy jako uwierzytelnianie dwuskładnikowe wykorzystywane są wiadomości e-mail lub SMS, system automatycznie wyśle wiadomość e-mail/SMS z żądaniem wstępnego uwierzytelnienia.

auth

W celu uwierzytelnienia użytkownika proszę użyć typu akcji auth. W żądaniu prześlij nazwę użytkownika i hasło (oraz kod 2FA, jeśli to konieczne), a w odpowiedzi otrzymasz token uwierzytelniający. Token ten można następnie wykorzystać do przetworzenia kolejnych żądań.

Przykładowe dane wejściowe:

{
  "accessType": 0|1|2|...,
  "kname":      "...",     //Username
  "kpass":      "...",     //Password
  "2fa":        "...",     //optional
  "longlife":   0|1 ,      //optional
  "api_key":    ""         //optional
}

Przykładowy wynik:

{
  ...
  "data":
  {
    "kmd":"token"
  }
}

Zapisz wartość znajdującą się pod kmd i wysyłaj ją we wszystkich kolejnych wywołaniach API jako wartość wejściową kmd.

Uwaga: w przypadku uwierzytelniania dwuskładnikowego wywołanie funkcji auth zwróci kod błędu w zależności od metody uwierzytelniania, jeśli 2fa nie został wysłany. W takim przypadku musisz wyświetlić użytkownikowi stronę uwierzytelniania dwuskładnikowego, która odpowiada kodowi błędu (np. w celu wprowadzenia kodu e-mailowego lub OTP). Użyj tokenu (kmd), który otrzymałeś, i użyj akcji verifyauth w celu (ponownego) przesłania kodu 2fa.

verifyauth

Akcja verifyauth może służyć do sprawdzenia, czy token (kmd) jest nadal ważny i/lub do przesłania kodu 2fa w celu uwierzytelnienia dwuskładnikowego.

Przykładowe dane wejściowe:

{
  "accessType": 0|1|2|...,
  "token":      "...",     //Token from auth  
  "2fa":        "...",     //2fa code    
}

Przykładowy wynik:

{
  ...
  "data":
  {
    "kmd":"token"
  }
}

Zapisz wartość znajdującą się pod kmd i wysyłaj ją we wszystkich kolejnych wywołaniach API jako wartość wejściową kmd.

wyloguj się

Akcja logout działanie kończy istniejącą sesję (wylogowanie).

Przykładowe dane wejściowe:

{
  "accessType": 0|1|2|...,
  "token":      "...",     //Token from auth  
}

prawa

Typ działania rights można wykorzystać w celu uzyskania przeglądu modeli i działań, do których użytkownik ma uprawnienia dostępu.

Przykładowe dane wejściowe:

{
  "accessType": 0|1|2|...,
  "token":      "..."
}

Przykładowy wynik:

{
  ...
  "data":
  [
    {
      "model":   "User",
      "actions": ["get","list","update"]
    },
    {
      "model":   "Subaccount",
      "actions": ["get","list","update","create","delete","deleteinfo"]
    }
  ]
}

lista

Typ akcji list można wykorzystać w celu uzyskania listy wpisów określonego modelu z bazy danych. Ten typ akcji jest przeznaczony do przedstawiania użytkownikowi przeglądu elementów (a nie pokazywania konkretnych szczegółów).

Przykład oczekiwanego tekstu źródłowego:

{
  ... 
 "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)
}

Przykładowa odpowiedź:

{
  "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 tablicy data tablicy i odpowiadającej jej tablicy nagłówkowej. Tablica danych zawiera wiersze, które mają być wyświetlone użytkownikowi. Tablica nagłówkowa będzie zawierać konkretne informacje nagłówkowe (np. sortowanie, tekst nagłówka itp.) dla każdej kolumny tabeli

Powyższe przykładowe dane spowodowałyby wyświetlenie następującej tabeli:

Wartości przeliczone

W przypadku pól typu lista (podtypy pól 1, 2 i 12) można użyć sufiksów :convert w cols właściwości żądania, aby uzyskać czytelny zapis treści zamiast wartości surowej (np. nazwę kolumny zamiast identyfikatora). Jeśli zostanie znaleziona kolumna z tym sufiksem, wynik będzie zawierał tę kolumnę dwukrotnie: raz jako wartość surową i raz jako wartość przekonwertowaną.

Przykład oczekiwanego tekstu źródłowego:

{
  ... 
 "model":   "Design",  
 "action":  "list",
 "cols":    ['strName', 'intPosition:convert']  
}

Przykładowa odpowiedź:

{
 ...
  "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

The

filters

W żądaniu JSON można użyć właściwości w celu wyszukania konkretnych elementów lub ograniczenia listy wyników.

filters

Właściwość składa się z tablicy elementów filtru. Każdy element jest obiektem 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 wyszukiwać we wszystkich polach, można użyć nazwy pola query można użyć nazwy pola

Możliwe comparison wartości to:

Typ porównania Opis
eql Równe. Znajdź wiersze, w których treść fieldname jest dokładnie taka sama jak value. (Ten typ jest domyślny, jeśli comparison nie jest używany w obiekcie.)
lt Mniejsze niż. Znajdź wiersze, w których zawartość fieldname jest mniejsza niż value.
gt Większe niż. Znajdź wiersze, w których zawartość fieldname jest większa niż value.
lte Mniejsze lub równe. Znajdź wiersze, w których zawartość fieldname jest mniejsza niż value lub równa value.
gte Większe lub równe. Znajdź wiersze, w których zawartość fieldname jest większa niż value lub równa value.
like Zawiera. Znajdź wiersze, w których value jest zawarta w treści fieldname (częściowo lub całkowicie).
in Znajduje się na liście. Znajdź wiersze, w których zawartość fieldname jest dokładnie taka sama jak jedna z value. W tym przypadku value powinna być tablicą.
is Ma wartość NULL. Znajdź wiersze, w których zawartość fieldname jest 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ówne lub większe niż 27 oraz lastname zawiera słowo „man” (np. Hofmann, Superman lub Mandy)

uzyskaj

Typ akcji get może być użyty w celu zażądania jednego lub więcej wpisów określonego modelu z bazy danych, gdy identyfikatory tych wpisów są już znane. Przeznaczeniem tego typu akcji jest wyświetlenie danych w formularzu do edycji. W związku z tym odpowiedź będzie zawierała również szczegółowe informacje o każdym polu.

Przykład oczekiwanego tekstu źródłowego:

{
  ... 
 "ids":     [...]  // Array of IDs
 }

Prześlij pustą tablicę ids , aby uzyskać wyłącznie definicję pola. Pomoże Ci to utworzyć nowy wpis na podstawie definicji pola.

Przykładowa odpowiedź:

{
  "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 mógłby dać formularz wyglądający następująco:

utwórz

Aby utworzyć nowe wpisy, możesz użyć typu akcji create.

Przykład oczekiwanego tekstu źródłowego:

{
  "ids":        [],
  "data":       {
    "intID":     "0",    
    "strLogin":  "new User",
    "strPass":   "ABCabc123!",
    "intStatus": "1"
  }
}

Wynik udanej aktualizacji odpowiada przykładowi podanemu dla get typu działania. Przykład wyniku:

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

Pamiętaj, że create nie powiedzie się, jeśli model o tym samym ID już istnieje. Jeśli chcesz nadpisać istniejące ustawienia, możesz wysłać dwa pola insertIgnore (value=1) i/lub onDuplicateUpdate (value=1). Wysłanie insertIgnore poinformuje system, aby nie zwracał błędu, jeśli wstawianie się nie powiedzie. onDuplicateUpdate poinformuje system, aby zaktualizował wszystkie wartości w przypadku istnienia elementu o tym samym identyfikatorze.

aktualizacja

Aby zmienić jeden lub więcej istniejących wpisów, możesz użyć typu akcji update.

Przykład oczekiwanego tekstu źródłowego:

{
  "ids":        [ 542 ],
  "data":       
  {
    "intID":     "542",
    "strLogin":  "aaa",
    "strPass":   "abcabc",
    "intStatus": "1"
  }  
}

Wynik udanej aktualizacji odpowiada przykładowi podanemu dla get typu działania. Przykład wyniku:

{
  "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 wyświetli komunikat o błędzie w następującej formie:

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

usuń

Typ akcji delete można wykorzystać w celu usunięcia jednego lub więcej wpisów określonego modelu z bazy danych, gdy identyfikatory (ID) tych wpisów są już znane.

Przykład oczekiwanego tekstu źródłowego:

{
  ... 
 "ids":     [...]  // Array of IDs
 }

Przykładowa odpowiedź:

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

 

We do our best to keep this purely informative documentation up to date. However, if you notice that any of these guides need a little touch-up, let us know!