Uso de Velneo cloud API
Se habilitan dos posibles formas de interactuar con Velneo Cloud API. Por un lado disponemos de un servicio REST y de un servicio RFC (usando funciones remotas de Velneo).El servicio REST consiste en una llamada HTTPS con una serie de parámetros. Los verbos soportados son POST, GET, PUT y DELETE.
Por ejemplo:
El servicio RFC tiene un funcionamiento similar. Por ejemplo:
set status, rfc:vserver("vatp://cloudapi.velneo.com", "cloudapi_1", "cloudapi", "cloudapi", "GET" )
set result, rfc:users("vatp://cloudapi.velneo.com", "cloudapi_1", "cloudapi", "cloudapi", "POST", params.json )
Los parámetros necesarios se envían en un sola variable en formato JSON representado en el ejemplo anterior por params.json. Siempre se usan las mismas variables que en el caso del servicio REST salvo que se indique lo contrario, y siempre en minúsculas.
Un ejemplo es:
{"name":"Luis", "password":"xxx"}
Todas las respuestas vienen en JSON.
Para poder usar el servicio RFC necesitas una API Key que puedes conseguir a través de nuestro centro de soporte indicando el email asociado al Velneo vServer que quieres gestionar con la API. Este API Key es privada y NO debes compartirla con otras personas.
En la descripción de los parámetros se establecen varios criterios:
- Si la variable va entre corchetes indica que es opcional.
- Los posibles valores se separan por el carácter “|”.
- Si alguno de los posibles valores está en negrita indica el valor por defecto si se omite esa variable.
Ten en cuenta que Velneo API Cloud puede usar diferentes versiones. Confirma que estás usando la versión correcta en la url en el caso de REST o en el nombre de instancia en el caso de RFC asociada a esta documentación.
Para utilizar cualquiera de las operaciones primero es necesario validarse en el servicio y obtener un identificador de sesión.
Salvo en el proceso de validación, en el resto de operaciones es necesario incluir el identificador de sesión, la hora actual (timestamp con zona horaria UTC) en formato número (por ejemplo en php: gmdate("U"); y en Velneo es currentUTCDateTime()) y un campo signed que representa el cifrado de sesión+timestamp+apikey. El cálculo sería:
signed=sha1(sesion+timestamp+apikey)
El valor de sesión (o email cuando se llama a iniciar sesión), el timestamp, el valor de signed y el método a usar son obligatorios en todas las llamadas y se omiten en la definición de los parámetros durante la documentación. Nos referiremos a ellos como "obligatorios".
En el caso de usar REST, ya depende del software que uses para las llamadas (php, python, etc.) el cómo debes calcular el valor de signed.
El valor de signed, al incluir el timestamp, hay que calcularlo antes de cada petición a la api cloud.
Todas las operaciones requieren autenticación. El primer paso para iniciar una sesión es una llamada POST.
Los parámetros son:
params={'email':'','timestamp': ,'signed':''}
Debemos tener en cuenta que sólo en esta llamada se incluye el email, tanto como parámetro como en el cálculo de signed (email+timestamp+apikey).
Usando REST sería:
POST https://cloudapi.velneo.com/v1/session
Retorna
- status_code: 200 (si todo ok), 401 (si falló la autenticación).
- session: identificador de la sesión creada,
Un ejemplo completo de obtener la sesión en Linux usando bash sería:
#!/bin/bash
timestamp=$(date +%s)
apikey=NyraFY6GMz8lu1fameMdrH0V
signed=$(echo -n "$email$timestamp$apikey" | sha1sum | awk '{print $1}')
curl -H 'Accept: application/json' \
-d method=POST \
--data-urlencode "params={'email': '$email', 'timestamp': $timestamp, 'signed': '$signed'}" \
https://cloudapi.velneo.com/v1/session
El código anterior retorna un JSON similar a este:
{ "status_code" : 200, "session": "796bcd1d-30da-433b-a36c-f0cf7737f73f"}
En el caso de usar el servicio RFC:
Retorna
- status_code: 200 (si todo ok), 401 (si falló la autenticación).
- session: identificador de la sesión creada.
Como comentamos antes el identificador de sesión retornado por esta llamada debe usarse en el resto de llamadas a Velneo Cloud API. Esta variable session es única mientras dure la sesión del usuario. Si un usuario intenta autenticarse de nuevo, se le retornará el mismo identificador de sesión. Si un usuario quiere terminar la sesión definitivamente debe llamar a la URL o a la RFC session con el verbo DELETE. Tener en cuenta que si un usuario ha iniciado sesión en la API vía múltiples aplicaciones, cuando se termina la sesión se termina para todos.
curl -H 'Accept: application/json'\
-d method=DELETE \
--data-urlencode"params="{'session':'796bcd1d-30da-433b-a36c-f0cf7737f73f','timestamp': <timestamp>,'signed': '<signed>'}" \
https://cloudapi.velneo.com/v1/session
Tu Velneo vServer puede ser iniciado, parado y consultado su estado. Los parámetros son:
GET https://cloudapi.velneo.com/v1/vserver
Parámetros
- session
- timestamp
- signed
Parámetros
Retorna
- status_code: 200 (si todo ok), 401 (si falló la autenticación), 403 (otro error).
- status: puede tener los valores "running", "stopped".
- vrl: la vrl completa de conexión a tu Velneo vServer Cloud. Por ejemplo, "vatp://c3.velneo.com:6676".
- version: la versión en la que se está ejecutando tu Velneo vServer, por ejemplo, "7.8.0".
GET https://cloudapi.velneo.com/v1/vserver
Ejemplo curl desde línea de comandos:
curl -H 'Accept: application/json' \
-d method=GET \
--data-urlencode"params="{'session':'796bcd1d-30da-433b-a36c-f0cf7737f73f','timestamp': <timestamp>,'signed':'<signed>'" \
https://cloudapi.velneo.com/v1/vserver
Usando RFC sería:
Un ejemplo de la salida es:
{"status_code": 200, "status": "running", "vrl": "vatps://c3.velneo.com:6070", "version": "25.0.4"}
Parámetros
- session
- timestamp
- signed
- action: "start"
Retorna
- status_code: 200 (si todo ok), 401 (si falló la autenticación), 403 (otro error).
Ejemplo curl desde línea de comandos:
curl -H 'Accept: application/json' \
-d method=PUT \
--data-urlencode"params="{'session':'796bcd1d-30da-433b-a36c-f0cf7737f73f','timestamp': <timestamp>,'signed':'<signed>','action':'start'}" \
https://cloudapi.velneo.com/v1/vserver
Usando RFC sería:
Un ejemplo de la salida es:
{"status_code": 200, "status": "running", "vrl": "vatps://c3.velneo.com:6070", "version": "25.0.4"}
Parámetros
- session
- timestamp
- signed
- action: "stop"
Retorna
- status_code: 200 (si todo ok), 401 (si falló la autenticación), 403 (otro error).
PUT https://cloudapi.velneo.com/v1/vserver
Ejemplo curl desde línea de comandos:
curl -H 'Accept: application/json' \
-d method=PUT \
--data-urlencode"params="{'session':'796bcd1d-30da-433b-a36c-f0cf7737f73f','timestamp': <timestamp>,'signed':'<signed>','action':'stop'}" \
https://cloudapi.velneo.com/v1/vserver
Usando RFC sería:
Un ejemplo de la salida es:
{"status_code": 200}
Parámetros
- session
- timestamp
- username: nombre de un usuario supervisor de tu Velneo vServer.
- password: contraseña del usuario indicado en el parámetro anterior.
Retorna
- status_code: 200 (si todo ok), 401 (si falló la autenticación), 403 (otro error).
PUT https://cloudapi.velneo.com/v1/vserver
Ejemplo curl desde línea de comandos:
curl -H 'Accept: application/json' \
-d method=PUT \
--data-urlencode"params="{'session':'796bcd1d-30da-433b-a36c-f0cf7737f73f','timestamp': <timestamp>,'signed':'<signed>', 'username': 'web', 'password': 'adsas1'}" \
https://cloudapi.velneo.com/v1/vserver
Usando RFC sería:
fun:[email protected]([email protected], "usuario", "pass")
Un ejemplo de la salida es:
{"status_code": 200}
La llamada para establecer credenciales no comprueba que estén correctas, sólo las establece para las futuras llamadas. Si las credenciales son erróneas, en la siguiente petición que se haga a la API retornará el siguiente JSON:
{"error":"Invalid user/password"}
Parámetros
- session
- timestamp
- signed
- action: "backup".
Retorna
- status_code: 200 (si todo ok), 401 (si falló la autenticación), 403 (otro error).
- url: enlace para la descarga de la copia.
GET https://cloudapi.velneo.com/v1/vserver
Permite gestionar los grupos de usuarios en tu Velneo vServer.
PUT https://cloudapi.velneo.com/v1/group
Parámetros
- session
- timestamp
- signed
- name: nombre del grupo.
- [manageSolutions]: yes |no.
- [addSolution]: "nombre". Indica el nombre de la solución a agregar al grupo.
- [addAppInstance]: "identificador de la instancia de aplicación". Añade permisos a este grupo para acceder a la instancia de aplicación con el identificador indicado. El identificador es obtenido cuando se agrega la instancia.
Retorna
- status_code: 200 (si todo ok), 401 (si falló la autenticación), 403 (otro error).
- message: mensaje descriptivo del error.
GET https://cloudapi.velneo.com/v1/group
Parámetros
- session
- timestamp
- signed
- name: nombre del grupo.
Retorna
- Un JSON con la información del grupo.
Ejemplo curl desde línea de comandos:
curl -H 'Accept: application/json' \
-d method=GET \
--data-urlencode"params="{'session':'796bcd1d-30da-433b-a36c-f0cf7737f73f','timestamp': <timestamp>,'signed':'<signed>', ‘name': 'test'}" \
https://cloudapi.velneo.com/v1/group
Un ejemplo de la salida es:
{"Name":"Administradores","codigo":1,"puedeBorrarSitios":true,"puedeCrearSitios":true,"puedeEjecutarConDataClient":true}
GET https://cloudapi.velneo.com/v1/groups
Parámetros
- session
- timestamp
- signed
Retorna
- Un JSON con la información de los grupos.
Ejemplo de salida:
["Name":"Administradores","codigo":1,"puedeBorrarSitios":true,"puedeCrearSitios":true,"puedeEjecutarConDataClient":true},{"Name":"Cajeros","codigo":2,"puedeBorrarSitios":false,"puedeCrearSitios":false,"puedeEjecutarConDataClient":false},{"Name":"Web","codigo":3,"puedeBorrarSitios":false,"puedeCrearSitios":false,"puedeEjecutarConDataClient":false}]}
DELETE https://cloudapi.velneo.com/v1/group
Parámetros
- session
- timestamp
- signed
- name: nombre del grupo.
Retorna
- status_code: 200 (si todo ok), 401 (si falló la autenticación), 403 (otro error).
- message: mensaje descriptivo del error.
Permite gestionar los usuarios en tu Velneo vServer.
PUT https://cloudapi.velneo.com/v1/user
Parámetros
- session
- timestamp
- signed
- [mustChangePassword]: yes|no. Indica si el usuario debe cambiar su contraseña en el siguiente inicio de sesión.
Retorna
- status_code: 200 (si todo ok), 401 (si falló la autenticación), 403 (otro error).
- message: mensaje descriptivo del error.
GET https://cloudapi.velneo.com/v1/user
Parámetros
- session
- timestamp
- signed
- username: nombre del usuario.
Retorna
- Un JSON con la información del usuario.
Ejemplo de salida:
{"FullName":"","Name":"velneo","bloqueado":false,"codigo":1,"debeCambiarPassword":false,"desactivado":false,"esSupervisor":true,"grupos":["Administradores"],"observaciones":"","passwordNuncaCaduca":true}
GET https://cloudapi.velneo.com/v1/users
Parámetros
- session
- timestamp
- signed
- groupname: si queremos todos los usuarios en esta propiedad hay que indicar "-all". Si queremos los usuarios de un determinado grupo, indicarlo como propiedad.
Retorna
- Un JSON con la información de los usuarios.
Ejemplo curl desde línea de comandos:
curl -H 'Accept: application/json' \
-d method=GET \
--data-urlencode"params="{'session':'796bcd1d-30da-433b-a36c-f0cf7737f73f','timestamp': <timestamp>,'signed':'<signed>', ‘groupname': 'test'}" \
https://cloudapi.velneo.com/v1/users
Un ejemplo de la salida es:
{"users":[{"FullName":"Antonio Carmona","Name":"acarmona","bloqueado":false,"debeCambiarPassword":false,"desactivado":false,"passwordNuncaCaduca":false},{"FullName":"Isabel Molina","Name":"imolina","bloqueado":false,"debeCambiarPassword":false,"desactivado":false,"passwordNuncaCaduca":false},{"FullName":"Luís González","Name":"lgonzalez","bloqueado":false,"debeCambiarPassword":false,"desactivado":false,"passwordNuncaCaduca":false}]}
Si queremos obtener información de todos los usuarios de todos los grupos hacemos:
curl -H 'Accept: application/json' \
-d method=GET \
--data-urlencode"params="{'session':'796bcd1d-30da-433b-a36c-f0cf7737f73f','timestamp': <timestamp>,'signed':'<signed>', ‘groupname': '-all'}" \
https://cloudapi.velneo.com/v1/users
Un ejemplo de la salida es:
{"users":[{"FullName":"David Garcia","Name":"dgarcia","bloqueado":false,"codigo":14,"debeCambiarPassword":false,"desactivado":false,"esSupervisor":true,"passwordNuncaCaduca":false},{"FullName":"Pedro Perez","Name":"pperez","bloqueado":false,"codigo":3482,"debeCambiarPassword":false,"desactivado":false,"esSupervisor":false,"passwordNuncaCaduca":false},{"FullName":"Ana De","Name":"anade","bloqueado":false,"codigo":1530,"debeCambiarPassword":false,"desactivado":false,"esSupervisor":false,"passwordNuncaCaduca":false},{"FullName":"Rafa Doe","Name":"rdoe","bloqueado":false,"codigo":24,"debeCambiarPassword":false,"desactivado":false,"esSupervisor":true,"passwordNuncaCaduca":true},{"FullName":"Alberto Mas","Name":"amas","bloqueado":false,"codigo":4991,"debeCambiarPassword":false,"desactivado":false,"esSupervisor":false,"passwordNuncaCaduca":false}]}
DELETE https://cloudapi.velneo.com/v1/user
Parámetros
- session
- timestamp
- signed
- username: nombre del usuario.
Retorna
- status_code: 200 (si todo ok), 401 (si falló la autenticación), 403 (otro error).
- message: mensaje descriptivo del error.
Permite gestionar las carpetas compartidas en tu Velneo vServer.
PUT https://cloudapi.velneo.com/v1/folder
Parámetros
- session.
- timestamp
- signed
- name: nombre de la carpeta. No se puede modificar una vez creada.
- path: directorio relativo a tu HOME donde se creará la carpeta. Solo necesario cuando se crea la carpeta. Por ejemplo, clientes/cliente1 creará la carpeta compartida en HOME/clientes/clientes1. Es obligatorio usar la barra (/).
- group: nombre del grupo al que se le darán permisos para acceder a esta carpeta. El grupo debe existir.
Retorna
- status_code: 200 (si todo ok), 401 (si falló la autenticación), 403 (otro error)
- message: mensaje descriptivo del error.
GET https://cloudapi.velneo.com/v1/folder
Parámetros
- session
- timestamp
- signed
- name: nombre de la carpeta.
Retorna
- Un JSON con la información de la carpeta.
Un ejemplo de retorno es:
{"nombre":"testapi","path":"/home/[email protected]/Velneo/datos/test/1"}
GET https://cloudapi.velneo.com/v1/folders
Parámetros
- session
- timestamp
- signed
Retorna
- Un JSON con la información de las carpetas.
Un ejemplo de salida es:
{"folders":[{"nombre":"/","path":"/"},{"nombre":"datos","path":"/home/[email protected]/Velneo/datos"},{"nombre":"testapi","path":"/home/[email protected]/Velneo/datos/test/1"}]}
DELETE https://cloudapi.velneo.com/v1/folder
Parámetros
- session
- timestamp
- signed
- name: nombre de la carpeta.
Retorna
- status_code: 200 (si todo ok), 401 (si falló la autenticación), 403 (otro error).
- message: mensaje descriptivo del error
Permite gestionar las instancias de aplicación en tu Velneo vServer.
PUT https://cloudapi.velneo.com/v1/instance
Parámetros
- session
- timestamp
- signed
- name: nombre de la instancia. No se puede modificar una vez creada.
- project: nombre del proyecto a instanciar.
- solution: nombre de la solución que contiene el proyecto.
- folderShared: nombre de la carpeta compartida donde se creará la instancia.Si en este parámetro indicas el nombre de una carpeta seguido del nombre de un directorio, te creará el directorio si no existe y le asigna esa ruta. Por ejemplo, si folderShared puede recibir el valor "datos/cliente1", creará el directorio cliente1 dentro de la carpeta compartida "datos" y le asignará la ruta "datos/cliente1" a las instancias de datos.
- inheritance: ese parámetro recibe una cadena similar a
1idProject1=codInstance1,idProject2=codInstance2,...,idProjectN=codInstanceN
donde idProject representa el identificador único del proyecto (que podemos obtener en las propiedades del proyecto en Velneo vDevelop) y codInstance el código de la instancia que se quiere reutilizar, que podemos ver en las propiedades de la instancia del proyecto en Velneo vAdimin:
-
Ejemplo:
6u65o9bq.vcd=7
- type: "app"
Retorna
- status_code: 200 (si todo ok), 401 (si falló la autenticación), 403 (otro error).
- message: mensaje descriptivo del error.
- id_instancia: identificador único de la instancia creada.
GET https://cloudapi.velneo.com/v1/instance
Parámetros
- session
- timestamp
- signed
- name: nombre de la instancia.
- byId: True|False. Indica que el nombre indicado en el parámetro name es el ID de la instancia
- type: "app".
Retorna
- Un JSON con la información de la instancia.
Un ejemplo de salida es:
{"nombre":"Biblio","proyecto":"2ewlh1l5.vca","solucion":"Biblioteca"}
GET https://cloudapi.velneo.com/v1/instances
Parámetros
- session
- timestamp
- signed
- type: "app".
Retorna
- Un JSON con la información de las instancias.
Ejemplo de salida es:
{"AppInstances":[{"nombre":"Biblio","proyecto":"2ewlh1l5.vca","solucion":"Biblioteca"},{"nombre":"Informes e impresoras logicas app","proyecto":"6vg5ikms.vca","solucion":"Informes e impresoras logicas"}]}
DELETE https://cloudapi.velneo.com/v1/instance
Parámetros
- session
- timestamp
- signed
- name: nombre de la instancia.
- byId: True|False. Indica que el nombre indicado en el parámetro name es el ID de la instancia
- type: "app".
Retorna
status_code: 200 (si todo ok), 401 (si falló la autenticación), 403 (otro error).
- message: mensaje descriptivo del error.
Permite gestionar las instancias de datos en tu Velneo vServer.
PUT https://cloudapi.velneo.com/v1/instance
- session
- timestamp
- signed
- name: nombre de la instancia. No se puede modificar una vez creada.
- byId: True|False. Indica que el nombre indicado en el parámetro name es el ID de la instancia
- project: nombre del proyecto a instanciar.
- solution: nombre de la solución que contiene el proyecto.
- folderShared: nombre de la carpeta compartida donde se creará la instancia.Si en este parámetro indicamos el nombre de una carpeta seguido del nombre de un directorio, creará el directorio, si no existe, y le asigna esa ruta. Por ejemplo, si folderShared recibe el valor "datos/cliente1", creará el directorio cliente1 dentro de la carpeta compartida "datos" y le asignará la ruta "datos/cliente1" a las instancias de datos.
- type: "data"
- inheritance: ese parámetro recibe una cadena similar a
1idProject1=codInstance1,idProject2=codInstance2,...,idProjectN=codInstanceN
donde idProject representa el identificador único del proyecto (que podemos obtener en las propiedades del proyecto en Velneo vDevelop) y codInstance el código de la instancia que se quiere reutilizar, que podemos ver en las propiedades de la instancia del proyecto en Velneo vAdmin: -
- Ejemplo:
6u65o9bq.vcd=7
Retorna
- status_code: 200 (si todo ok), 401 (si falló la autenticación), 403 (otro error).
- message: mensaje descriptivo del error.
- id_instancia: identificador único de la instancia creada.
GET https://cloudapi.velneo.com/v1/instance
Parámetros
- session
- timestamp
- signed
- name: nombre de la instancia.
- byId: True|False. Indica que el nombre indicado en el parámetro name es el ID de la instancia
- type: "data".
Retorna
- Un JSON con la información de la instancia.
Un ejemplo de salida es:
{"nombre":"Biblio_dBiblio","proyecto":"2ewlh1l5.vcd","ruta":"datos/Biblioteca","solucion":"Biblioteca"}
GET https://cloudapi.velneo.com/v1/instances
Parámetros
- session
- timestamp
- signed
- type: "data".
Retorna
- Un JSON con la información de las instancias.
Un ejemplo de salida es:
{"dataInstances":[{"nombre":"Biblio_dBiblio","proyecto":"2ewlh1l5.vcd","ruta":"datos/Biblioteca","solucion":"Biblioteca"},{"nombre":"Informes e impresoras logicas app_Informes e impresoras logicas dat","proyecto":"6vg5ikms.vcd","ruta":"datos/ImpresorasLogicas","solucion":"Informes e impresoras logicas"}]}
DELETE https://cloudapi.velneo.com/v1/instance
Parámetros
- session
- timestamp
- signed
- name: nombre de la instancia.
- byId: True|False. Indica que el nombre indicado en el parámetro name es el ID de la instancia
- type: "data".
Retorna
- status_code: 200 (si todo ok), 401 (si falló la autenticación), 403 (otro error)
- message: mensaje descriptivo del error.
Veamos varios ejemplos de cómo realizar ese cálculo en varios lenguajes.
$fecha = new DateTime();
$timestamp = $fecha->format("U");
// $session tiene el valor retornado por la llamada a post.Session
$hash = sha1( $session . $timestamp . $apiKey );
timestamp=$(date +%s)
# $session tiene el valor retornado por la llamada a post.Session
signed=$(echo -n "$session$timestamp$apikey" | shasum -a 1 | awk '{print $1}')
from datetime import datetime
import hashlib
ahora = datetime.now()
unixtime = int(time.mktime(ahora.timetuple()))
# session tiene el valor retornado por la llamada a post.Session
signed = hashlib.sha1( session + str(unixtime) + key ).hexdigest()
Última actualización 1mo ago