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:

{
  "action":     "preauth",
  "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:

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:

{
  "action":     "auth",
  "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:

{
  "action":     "verifyauth",
  "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ę

Połączenia logout akcja kończy istniejącą sesję (wylogowanie).

Przykład wprowadzania:

{
  "action":     "logout",
  "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:

{
  "action":     "rights",
  "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:

{
  ... 
 "model":   "...",  
 "action":  "list",
 "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

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

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:

{
  ... 
 "model":   "...",  
 "action":  "get",
 "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:

{
  "action":     "create",
  "accessType": 1,
  "model":      "Subaccount",
  "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:

{
  "action":     "update",
  "accessType": 1,
  "model":      "Subaccount",
  "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:

{
  ... 
 "model":   "...",  
 "action":  "delete",
 "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
  }
}