¿Cómo exportar e importar datos vía API REST de la Onesait Platform?

Hoy vamos a hablar de cómo usar las API REST para exportar e importar elementos de la Plataforma.

¿Interesante, verdad? Veamos primero qué podemos hacer con las APIs de importación y con las de exportación, y cuales son sus propiedades.

APIs de exportación

Con este tipo de APIs:

• Se podrá exportar un único elemento, o varios de ellos.
• Para poder exportar una entidad de la Plataforma, el usuario debe tener permisos sobre la misma o tener rol de «administrador».
• Para poder exportar varias entidades, el usuario debe ser el propietario (exportará todas las suyas) o tener rol de «administrador» (exportará todas).
• Cuando se exportan varios elementos de la Plataforma con un usuario con rol tipo «developer» o «analytics», solo se exportarán los que sean propiedad del usuario. Si se realiza con un usuario de tipo «administrador» se exportarán todos.

APIs de importación

• Como en el caso anterior, se podrá importar un único elemento, o varios de ellos.
• Si el usuario tiene rol administrador, se importarán los elementos con los propietarios que tengan asignados (si no existen estos usuarios no se crearán y se notificará en el json de respuesta).
• Si el usuario tiene rol developer o analytics, se importarán los elementos asignando como propietario el usuario que realiza la importación.
• Existe un parámetro opcional overwrite (por defecto a false) con el que se indica si se quieren sobreescribir los elementos que se están importando (el usuario debe ser propietario o administrador). Si este parámetro está a false notifica en el json de respuesta las entidades que se han importado y las que no. Si este parámetro está a true se eliminan aquellos que coincidan con los que se quieren importar, notificando en el json todos los elementos importados y los que no.
• Existe un parámetro opcional que permite importar los elementos asociados a la entidad (permisos).

Vale pero, ¿cómo utilizo las APIs para exportar o importar?

Es muy sencillo; desde el Control Panel, en la parte superior derecha de la pantalla tenemos el acceso a los APIs de nuestra instancia de la Plataforma.

Desde dicho menú, podemos acceder a todas las APIs de gestión de la Plataforma, así como al OAuth2 Token de usuario.

Seleccionando el API de «Control Panel», podemos acceder a la documentación de todas las APIs asociadas a los recursos de la Plataforma. El listado de APIs disponibles lo encontramos en el listado de la parte superior derecha.

Bien, pues seleccionemos el API que nos interese del listado para poder acceder al recurso para manipularlo (es decir, consultarlo, crear un elemento nuevo, editar una existente o borrarlo).

Eso si, para poder invocar estas APIs y sus operaciones, necesitamos usar nuestro token de usuario, el cual según el tipo de usuario que tengamos, estaremos autorizados o no a consultar ciertas cosas.

Este token lo obtendremos haciendo clic, nuevamente, sobre el menú de APIs situado en la parte superior derecha del Control Panel, en donde copiaremos el pequeño código alfanumérico que nos aparece.

Por ejemplo, a continuación vemos la operación de exportación de todas las ontologías asociadas a un usuario denominado «Noether» en el entorno de CloudLab.

Si nos interesa guardar la respuesta de estas APIs, para luego poder importar los recursos en otro entorno, podemos hacerlo fácilmente desde la línea de comandos con la siguiente línea:

curl --insecure -X GET 'https://$OP_HOST/controlpanel/api/ontologies/ontologies/export/' -H 'accept: */*' -H 'Authorization: $BEARER_TOKEN' > /mnt/ontologies.json

Aquí como detalle a tener en cuenta es que tenemos que haber guardado previamente el DNS de nuestro entorno en la variable denominada como «OP_HOST», así como el token de usuario en la variable de «BEARER_TOKEN».

Ejecutando esta línea, como os decíamos, podemos tener guardadas nuestras ontologías en el archivo «/mnt/ontologies.json».

Bueno, pues una vez que lo tenemos exportado, podemos proceder a importarlo en otro entorno. Esto lo podemos hacer volviendo al listado de APIs nuevamente, y seleccionando el API de importar.

Una vez invocada la operación de importación, tendremos que copiar en el apartado «ontologyDTOsArrayString» el archivo JSON de nuestra ontología exportada previamente.

Invocar estas APIs desde un pipeline de Jenkins

Vale, ya hemos visto cómo exportar una ontología y luego importarla en otro lado. Interesante pero poco práctico si tenemos que hacerlo a mano. Veamos por tanto cómo automatizar estas tareas usando un pipeline de Jenkins.

La principal ventaja, aparte de automatizar el proceso, es que podemos crear un ciclo para versionar los recursos de la Plataforma en Git.

Veamos el siguiente ejemplo, con un pipeline en el que se exportan todas las ontologías y APIs para subirlas a GitHub.

En este caso se ha aplantillado algunas variables, las cuales tendremos que introducir a mano cada vez que queramos ejecutar este pipeline. El código en cuestión será el siguiente:

pipeline {
   // Execute the Pipeline, or stage, on any available agent   
   agent { node { label 'master' } }
 
   environment {         
      // Base sources path
      SOURCESPATH = 'sources'
      FLOWENGINEPATH = 'sources/modules/flow-engine/docker'
      DOCKERSCRIPTS = 'devops/build-deploy/docker/scripts'
      EMBEDDEDGIT = 'git'
   }
    
   parameters {
        
       string(name: 'OP_HOST',
              defaultValue: '<host> eg: lab.onesaitplatform.com',
              description: 'DNS or IP which host the platform')
       string(name: 'BEARER_TOKEN',
              defaultValue: '<token> eg: Bearer XXX',
              description: 'OP user Bearer token')
       string(name: 'COMMIT_MSG',
              defaultValue: '<msg> eg: Comentario del commit',
              description: 'Comentario del commit')
       string(name: 'GIT_BRANCH',
              defaultValue: '<branch> eg: master',
              description: 'Rama donde hacer el push')
   }  
    
   stages {    
        
       stage('Get platform ontologies') {
                         
            steps {    
              sh "cd /mnt/"
              sh "curl --insecure -X GET 'https://$OP_HOST/controlpanel/api/ontologies' -H 'accept: */*' -H 'Authorization: $BEARER_TOKEN' | jq '.' > /mnt/ontologies.json"
            }         
       }
        
       stage('Get platform APIs') {
                         
            steps {    
              sh "cd /mnt/"
              sh "curl --insecure -X GET 'https://$OP_HOST/controlpanel/api/apis' -H 'accept: */*' -H 'Authorization: $BEARER_TOKEN' | jq '.' > /mnt/apis.json"
            }         
       }
        
       stage('push to git') {
                         
            steps {
              sh "rm -rf /var/jenkins_home/workspace/export-import/*"
              // Fetch code from develop branch
              git url: 'https://github.com/cheessee/op-resources.git',
                  credentialsId: '4b7fa4a2-f4f1-49e1-9f74-97dd52529a20' ,
                  branch: '$GIT_BRANCH'
              sh "cd /var/jenkins_home/workspace/export-import"
              sh "cp -R /mnt/* /var/jenkins_home/workspace/export-import/"
              sh "git add ."
              sh "whoami"
              sh "git config --global user.name jriveiro"
              sh "git config --global user.email jriveiro@minsait.com"
              sh "git remote set-url origin git@github.com:cheessee/op-resources.git"
              sh "git commit -m '$COMMIT_MSG'"
              sh "git push origin $GIT_BRANCH"
               
               
            }           
       }
        
   }
    
   post {
        always {
            echo "POST always section"
        }  
        failure {  
            echo "Failure section"
        }
   }     
}

Pero hay más; si ya aparte de exportar y subir al Git nuestro API, quisiéramos hacer una importación en otro entorno, deberíamos añadir el siguiente paso:

stage('Import platform ontologies') {
                        
           steps {    
             sh "cd /mnt/"
             sh "curl -X POST 'https://$OP_HOST_DESTINO/controlpanel/api/ontologies/ontologies/import?importAuthorizations=false&overwrite=true' -H 'accept: */*' -H 'Authorization: $BEARER_TOKEN_DESTINO' -H "Content-Type: application/json" -d '$(cat /mnt/ontologies.json)'"
           }         
      }

Esperamos que os haya parecido interesante y que, si os surge alguna duda, nos dejéis un comentario.

✍🏻 Author(s)