Existe una nueva versión de Velneo Cloud Api. Puede consultar la documentación.
Conceptos básicos
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 V7). El servicio REST consiste en una llamada HTTPS con una serie de parámetros. Los verbos soportados son POST, GET y DELETE.Por ejemplo:GET https://cloudapi.velneo.com/v1/vserver Obtiene el estado de tu Velneo vServerEl servicio RFC tiene un funcionamiento similar.Por ejemplo:[php]set status, rfc:vserver("vatp://cloudapi.velneo.com", "cloudapi_1", "cloudapi", "cloudapi", "GET" )[/php][php]set result, rfc:users("vatp://cloudapi.velneo.com", "cloudapi_1", "cloudapi", "cloudapi", "POST", params.json )[/php]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:[php]{ "name": "Luis", "password": "xxx"}[/php]Todas las respuestas vienen en JSON y siempre retorna como mínimo el parámetro status_code.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 V7 es currentUTCDateTime()) y un campo signed que representa el cifrado de sesión+timestamp+apikey. El cálculo sería:[php]signed=sha1(sesion+timestamp+apikey)[/php]El valor de sesión (o email cuando se llama a iniciar sesión), el timestamp y el valor de signed 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".Importante: Si vas a utilizar el servicio usando RFC, en el catálogo de Velneo Open Apps tienes el componente vCloudApi que abstrae todo ese trabajo en una serie de funciones, que son las que se explican en esta documentación. Te recomendamos que te apoyes en el tutor indicado para seguir esta documentación.En el caso de usar REST, ya depende del software que uses para las llamadas (php, rails, python, etc) el cómo debes calcular el valor de signed.Nota versión beta: En esta versión para el servicio REST estamos usando un certificado digital no reconocido por lo organismos reguladores, por lo que habrá que indicar el modificador correspondiente en el software que usemos. Por ejemplo, en el caso de usar curl tendremos que indicar el parámetro -k.
Autenticación
Todas las operaciones requieren autenticación. El primer paso para iniciar una sesión es una llamada POST.Los parámetros son:[php]params={'email': '', 'timestamp': , 'signed': ''}[/php]Nota: 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:[php]POST https://cloudapi.velneo.com/v1/session[/php]
Retorna
- status_code: 200 (si todo ok), 401 (si fallo autenticación)
- session: Identificador de la sesión creada
Ejemplo curl desde línea de comandos:
[php] curl -H 'Accept: application/json' \-d method=POST \--data-urlencode "params={'email': '', 'timestamp': , 'signed': ''}" \-k \https://cloudapi.velneo.com/v1/session[/php]
En el caso de usar el servicio RFC:[php]fun:SESSION_CREATE@vCloudApi.dat($EMAIL@vCloudApi.dat, $APIKEY@vCloudApi.dat)[/php]Retorna:
- status_code: 200 (si todo ok), 401 (si fallo 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 el API vía múltiples aplicaciones, cuando se termina la sesión se termina para todos.
vServer
Tu Velneo vServer puede ser iniciado, parado y consultado su estado. Los parámetros son:[php]GET https://cloudapi.velneo.com/v1/vserver[/php]Parámetros
- obligatorios
Obtiene el estado de tu Velneo vServer
Parámetros:
- session: identificador de sesión retornada por la llamada a POST.session
Retorna
- status_code: 200 (si todo ok), 401 (si fallo 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://v7cloud3.velneo.com:6676"
- version: La version en la que se está ejecutando tu Velneo vServer, por ejemplo, "7.8.0"
[php]PUT https://cloudapi.velneo.com/v1/vserver[/php]
Inicia tu Velneo vServer
Parámetros:
- obligatorios
- action: "start"
Retorna
- status_code: 200 (si todo ok), 401 (si fallo autenticación), 403 (otro error)
Ejemplo curl desde línea de comandos:
[php]curl -H 'Accept: application/json' \-d method=PUT \--data-urlencode "params={'session': '', 'timestamp': , 'signed': '', 'action': 'start'}" \-k \https://cloudapi.velneo.com/v1/vserver[/php]
Usando RFC sería:[php]fun:VSERVER_START@vCloudApi.dat($EMAIL@vCloudApi.dat)[/php][php]PUT https://cloudapi.velneo.com/v1/vserver[/php]
Detiene tu Velneo vServer Parámetros:
- obligatorios
- action: "stop"
Retorna
- status_code: 200 (si todo ok), 401 (si fallo autenticación), 403 (otro error)
[php]PUT https://cloudapi.velneo.com/v1/vserver[/php]
Establece las credenciales para poder acceder a tu Velneo vServer
Parámetros:
- obligatorios
- username: nombre de un usuario supervisor de tu Velneo vServer
- password: password del usuario indicado en el parámetro anterior
Retorna
- status_code: 200 (si todo ok), 401 (si fallo autenticación), 403 (otro error)
Copia de seguridad de tu Velneo vServer
Parámetros:
- obligatorios
- action: "backup"
Retorna
- status_code: 200 (si todo ok), 401 (si fallo autenticación), 403 (otro error)
- url: Enlace para la descarga de la copia
[php]GET https://cloudapi.velneo.com/v1/vserver[/php]
Groups
Puedes agregar y modificar grupos en tu Velneo vServer
[php]PUT https://cloudapi.velneo.com/v1/group[/php]Agrega si no existe o modifica un grupo en tu Velneo vServerParámetros:
- obligatorios
- 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 (en versiones anteriores a Velneo V7 7.12, en esta propiedad hay que indicar el nombre de la instancia).
Retorna
- status_code: 200 (si todo ok), 401 (si fallo autenticación), 403 (otro error)
- message: Mensaje descriptivo del error
Users
Puedes agregar y modificar usuarios en tu Velneo vServer.[php]PUT https://cloudapi.velneo.com/v1/user[/php]
Agrega si no existe o modifica un usuario en tu Velneo vServer
Parámetros:
- obligatorios
- username: nombre del usuario a agregar. No se puede modificar una vez creado.
- password: password a establecer para este usuario
- [fullname]: Nombre completo del usuario
- group: Grupo en el que se incluirá al usuario
- [isSupervisor]: yes|no. Indica si el usuario añadido es supervisor de tu Velneo vServer
Retorna
- status_code: 200 (si todo ok), 401 (si fallo autenticación), 403 (otro error)
- message: Mensaje descriptivo del error
Folders
Puedes agregar o modificar carpetas compartidas en tu Velneo vServer.[php]PUT https://cloudapi.velneo.com/v1/folder[/php]
Agrega si no existe o modifica una carpeta compartida en tu Velneo vServer
Parámetros:
- obligatorios
- name: nombre de la carpeta. No se puede modificar una vez creada.
- path: Directorio relativo a tu HOME donde se creará la carpeta. Sólo 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 fallo autenticación), 403 (otro error)
- message: Mensaje descriptivo del error
App instances
Puedes agregar o modificar instancias de aplicación en tu Velneo vServer.[php]PUT https://cloudapi.velneo.com/v1/instance[/php]
Agrega si no existe o modifica una instancia de aplicación en tu Velneo vServer
Parámetros:
- obligatorios
- 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
Retorna
- status_code: 200 (si todo ok), 401 (si fallo autenticación), 403 (otro error)
- message: Mensaje descriptivo del error
- id_instancia: Identificador único de la instancia creada (a partir de Velneo V7 7.12)
