Información
Mi contenido

API general: tipos de acción

preautorización

Para autenticar a un usuario, consulte el tipo de acción preauth primero. Con su solicitud, envíe el nombre de usuario y recibirá información sobre si el usuario necesita iniciar sesión mediante contraseña y / o 2Factor o si es necesario un redireccionamiento a servidores de terceros (SAML / OAuth).

Ejemplo de entrada:

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

Ejemplo de salida:

{
  ...
  "data":
  {
    "sso_type":          0/1/2/3,
    "sso_redirect":      "https://...",
    "twofactor_type":     0/1/2/3,
    "twofactor_required": true|false
  }
}

La respuesta contiene la siguiente información:

Campo Descripción
sso_type

Tipo de inicio de sesión único:

0: No 2FA

1: LDAP

2: SAML

3: OAuth

sso_redirect URL a la que redirigir al usuario (usado con SAML + OAuth)
twofactor_type

Tipo de autorización de dos factores

0: No 2FA

1: OTP

2: correo electrónico

3: SMS

twofactor_required Si se requiere o no un segundo factor (todos los dos tipos de factores, excepto 0)

Nota: Cuando un sso_redirect La URL está presente, debe reenviar al usuario al punto final SSO para la autenticación. Una vez que el usuario regrese, puede continuar con los siguientes pasos de autenticación.

Nota: En los casos en que el correo electrónico o SMS se utilizan como autenticación de dos factores, el sistema enviará automáticamente el correo electrónico / SMS con la solicitud de autorización previa.

auth

Para autenticar al usuario, utilice el tipo de acción auth. Con su solicitud, envíe el nombre de usuario y la contraseña (y el código 2FA si es necesario) y recibirá un token de autenticación como respuesta. El token se puede utilizar para procesar solicitudes posteriores.

Ejemplo de entrada:

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

Ejemplo de salida:

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

Guarde el valor que se encuentra en kmd y enviarlo en todas las llamadas posteriores a la API como valor de entrada kmd.

Tenga en cuenta: En caso de autenticación de dos factores, la llamada a auth devolverá un código de error dependiendo del método de autenticación si 2fa no fue enviado. Si ese es el caso, deberá mostrar una página de Autenticación de dos factores al usuario que coincida con el código de error (por ejemplo, para ingresar el código de correo electrónico u OTP). Utilice el token (kmd) que recibió y usa la acción verifyauth para (re) enviar el código 2fa.

Verificación

La acción verifyauth se puede usar para verificar si un token (kmd) sigue siendo válido y / o enviar un código 2fa para la autenticación de dos factores.

Ejemplo de entrada:

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

Ejemplo de salida:

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

Guarde el valor que se encuentra en kmd y enviarlo en todas las llamadas posteriores a la API como valor de entrada kmd.

Iniciar sesión

La logout La acción finaliza una sesión existente (cierre de sesión).

Ejemplo de entrada:

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

derechos

Tipo de acción rights se puede utilizar para obtener una descripción general de los modelos y las acciones a las que el usuario tiene derecho de acceso.

Ejemplo de entrada:

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

Ejemplo de salida:

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

--

El tipo de acción list se puede utilizar para solicitar una lista de entradas de un modelo específico de la base de datos. Este tipo de acción está diseñado para ofrecer una descripción general de los elementos a un usuario (en lugar de mostrar detalles específicos).

Ejemplo de entrada esperado:

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

Ejemplo de salida de respuesta:

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

Los datos de salida constan de un data matriz y una matriz de cabeza correspondiente. La matriz de datos contiene las filas que se mostrarán al usuario. La matriz de encabezados contendrá la información específica del título (por ejemplo, clasificación, texto del título, etc.) para cada columna de la tabla.

Los datos de ejemplo anteriores resultarían en la siguiente tabla que se mostraría:

Valores convertidos

Para los campos de la lista de tipos (subtipos de campo 1, 2 y 12) puede usar el sufijo :convert in cols propiedad de la solicitud para obtener el valor legible del contenido en lugar del valor bruto (por ejemplo, el nombre de una columna en lugar del ID). Si se encuentra una columna con este sufijo, la salida contendrá la columna dos veces, una como valor sin procesar y otra como valor convertido.

Ejemplo de entrada esperado:

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

Ejemplo de salida de respuesta:

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

Filtros

La filters La propiedad JSON de la solicitud se puede utilizar para buscar elementos específicos o reducir la lista de salida. los filters La propiedad consta de una matriz de elementos de filtro. Cada artículo es un objeto de la siguiente estructura:
{
"fieldname": "...", // Field the filter should apply to
"comparison": "...", // (optional) Comparison type, see description
"value" : "..." // Value to compare the field to
}

Para buscar en todos los campos, el nombre del campo query puede ser usado.

Posibles comparison los valores son:

Tipo de comparación Descripción
eql Igual. Encuentra filas donde el contenido de fieldname es exactamente lo mismo que value. (Este tipo es predeterminado si comparison no se utiliza en el objeto.)
lt Más bajo que. Encuentra filas donde el contenido de fieldname es más pequeño que value.
gt Mas grande que. Encuentra filas donde el contenido de fieldname es mayor que value.
lte Menor que / Igual. Encuentra filas donde el contenido de fieldname es más pequeño que value o igual a value.
gte Mayor que / Igual. Encuentra filas donde el contenido de fieldname es mayor que value o igual a value.
like Contiene. Encuentra filas donde value está incluido en el contenido de fieldname (en parte o en su totalidad).
in Está en la lista. Encuentra filas donde el contenido de fieldname es exactamente igual que uno de value. En este caso value debería ser una matriz.
is Es nulo. Encuentra filas donde el contenido de fieldname is NULL.
isnot No es nulo. Encuentra filas donde el contenido de fieldname no es NULL.

Ejemplo:

{
  ...
  "filters":
  [
    {
      "fieldname": "age",
      "comparison": "gte",
      "value" : 27
    },
    {
      "fieldname": "lastname",
      "comparison": "like",
      "value" : "man"
    }
  ]
}

... encontrará filas donde age es igual o mayor que 27 y lastname contiene al hombre (por ejemplo, Hofmann o Superman o Mandy)

obtener

El tipo de acción get se puede utilizar para solicitar una o más entradas de un modelo específico de la base de datos cuando ya se conocen los ID de las entradas. El uso previsto de este tipo de acción es mostrar los datos en un formulario para su edición. Por lo tanto, la respuesta también proporcionará información detallada sobre cada campo.

Ejemplo de entrada esperado:

{
  ... 
 "model":   "...",  
 "action":  "get",
 "ids":     [...]  // Array of IDs
 }

Envíe una matriz vacía de ids para obtener solo la definición del campo. Esto puede ayudarlo a crear una nueva entrada basada en la definición del campo.

Ejemplo de salida de respuesta:

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

El ejemplo anterior podría resultar en un formulario con este aspecto:

Para crear

Para crear nuevas entradas, puede utilizar el tipo de acción create.

Ejemplo de entrada esperado:

{
  "action":     "create",
  "accessType": 1,
  "model":      "Subaccount",
  "ids":        [],
  "data":       {
    "intID":     "0",    
    "strLogin":  "new User",
    "strPass":   "ABCabc123!",
    "intStatus": "1"
  }
}

El resultado de una actualización exitosa corresponde al ejemplo dado para el get tipo de acción. Ejemplo de salida:

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

este producto está hecho por encargo con un tiempo de producción de XNUMX a XNUMX semanas create fallará si el modelo con el mismo ID ya existe. Si desea anular la configuración existente, puede enviar los dos campos insertIgnore (valor = 1) y / o onDuplicateUpdate (valor = 1). Enviando insertIgnore le dirá al sistema que no devuelva un error si falla la inserción. onDuplicateUpdate le dice al sistema que actualice todos los valores en caso de que exista un artículo con el mismo ID.

actualización

Para cambiar una o más entradas existentes, puede usar el tipo de acción update.

Ejemplo de entrada esperado:

{
  "action":     "update",
  "accessType": 1,
  "model":      "Subaccount",
  "ids":        [ 542 ],
  "data":       
  {
    "intID":     "542",
    "strLogin":  "aaa",
    "strPass":   "abcabc",
    "intStatus": "1"
  }  
}

El resultado de una actualización exitosa corresponde al ejemplo dado para el get tipo de acción. Ejemplo de salida:

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

En caso de un error de actualización, el sistema responderá con un mensaje de error como este:

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

borrar

El tipo de acción delete se puede utilizar para eliminar una o más entradas de un modelo específico de la base de datos cuando ya se conocen los ID de las entradas.

Ejemplo de entrada esperado:

{
  ... 
 "model":   "...",  
 "action":  "delete",
 "ids":     [...]  // Array of IDs
 }

Ejemplo de salida de respuesta:

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