¿Cómo utilizar el intérprete %onesaitplatform?
En este tutorial se realiza un ejemplo de uso del grupo de intérpretes %onesaitplatform desde los Notebooks.
Para conocer más en profundidad las funcionalidades de los intérpretes se puede consultar las referencias: (Notebooks) (ES) %onesaitplatform Referencia de intérpretes.
Antes de comenzar
Antes de comenzar hay que tener en cuenta los siguientes puntos:
Este tutorial se basa en la base de datos Restaurants disponible por defecto en la plataforma.
Se creará una ontología denominada RestaurantTutorialDB para realizar las inserciones.
Se creará un Digital Client denominado RestaurantTutorialClient de comunicación con las ontologías Restaurant y RestaurantTutorialDB.
Se creará un API REST denominada RestaurantTutorialAPI sobre la ontología RestaurantTutorial.
Si los componentes ya existen, deben borrarse en el siguiente orden: RestaurantTutorialClient, RestaurantTutorialAPI y RestaurantTutorialDB.
Se recomienda encarecidamente que el tutorial no se haga con un usuario administrador.
El usuario debe tener el rol ANALYTICS para disponer del módulo de Notebooks.
Creación de elementos necesarios
Creación de la ontología RestaurantTutorialDB
El primer paso es crear la ontología RestaurantTutorialDB con el mismo esquema que la ontología Restaurants. Se puede copiar y pegar el esquema siguiente para definir el esquema de la ontología:
{"$schema": "http://json-schema.org/draft-04/schema#","title": "Restaurants","type": "object","required": ["Restaurant"],"properties": {"Restaurant": {"type": "string","$ref": "#/datos"}},"datos": {"description": "Info Restaurant","type": "object","required": ["address"],"properties": {"address": {"type": "object","required": ["building"],"properties": {"building": {"type": "string"},"coordinates": {"type": "object","required": ["coordinates","type"],"properties": {"coordinates": {"type": "object","properties": {"latitude": {"type": "number"},"longitude": {"type": "number"}}},"type": {"type": "string","enum": ["Point"]}}},"street": {"type": "string"},"zipcode": {"type": "string"}}},"borough": {"type": "string"},"cuisine": {"type": "string"},"grades": {"type": "array","properties": {"date": {"type": "object","properties": {"$date": {"type": "string","format": "date-time"}}},"grade": {"type": "string"},"score": {"type": "number"}}},"name": {"type": "string"},"restaurant_id": {"type": "string"}}},"description": "Ontology Restaurants for testing","additionalProperties": true} |
|---|
De esta forma ya tenemos una ontología nueva con el mismo esquema que Restaurants.
Creación del Digital Client RestaurantTutorialClient
A continuación se crea un Digital Client con acceso a las ontologías Restaurants y RestaurantTutorialDB para consultar e insertar datos. El token será nuestro DIGITAL_CLIENT_TOKEN en el Notebook.
Ya tenemos un Client de comunicación con el Digital-Broker de la plataforma.
Creación de la API REST RestaurantTutorialAPI
Por último, se crea una API REST para consultar los datos de la ontología por REST. Establecemos dos tipos de operaciones: all e {id}
Ya está disponible una API REST de consulta sobre los datos que se inserten.
Set variables necesarias
Con los elementos creados, entramos en el Notebook denominado OnesaitPlatformZeppelinInterpretes o creamos una copia.
En las primeras celdas, se establecen las variables necesarias obtenidas de la creación de los elementos y del usuario.
Se introducen en el contexto Zeppelin (serán accesibles desde todas las celdas, independientemente del intérprete).
Cómo utilizar el intérprete ﹪onesaitplatform
A continuación se muestra un ejemplo de intercambio de datos con la plataforma (queries e inserts).
Mostrar help
La ayuda se muestra si se introduce la palabra help o una expresión no reconocible.
Modo debug
El modo debug permite ver la traza de ejecución del código.
Introducir credenciales
Se puede observar la traza de debug cuando el modo debug está activo para la ejecución de initConnection().
Hacer una query
Un ejemplo de query SQL:
Un ejemplo de query NATIVE:
Consultar los datos como tabla
Para realizar una consulta de datos que Zeppelin puede interpretar:
Hacer un insert de datos
Para hacer un insert de datos, primero se deben guardar los objetos serializados en el contexto, desde donde se recuperarán en la función insert:
Hacer una query paginada (batch)
En los casos en los que se hace queries de gran tamaño para descargar datos en crudo, se recomienda utilizar las queries paginadas, que descargan los datos en batches. La configuración de los batches de datos se puede cambiar en el gestor de intérpretes:
Un ejemplo de consulta y guardado en una variable:
Hacer un archivo desde una query
Para facilitar el manejo de sentencias, se puede crear una función llamada, queryfile(“<ontology>”, “<query>”, “<queryType>”, “<responseType>”), cuya tarea es volcar el resultado de la consulta en un archivo.
Ver el estado del proceso de QueryFile
Para comprobar si el archivo solicitado anteriormente o cualquier otro ha finalizado o está en proceso de volcar el contenido de la query en el archivo, se utiliza la función QueryFileStatus, en la cual debemos ingresar el queryId proporcionado por la función queryFile.
El funcionamiento de esta función es el siguiente: realiza una primera solicitud para obtener el estado, que puede ser "in_progress" o "finished". Si el estado es "finished", se mostrará por pantalla. Si el estado es "in_progress", la función realizará múltiples solicitudes durante el tiempo definido por el “timeout”, haciendo una pausa entre ellas según el valor de “timesleep”. Una vez se reciba el estado "finished", se imprimirá en pantalla. Si al finalizar el tiempo del “timeout” no se ha recibido el estado "finished", se devolverá "in_progress".
Esta función puede ser utilizada de varias maneras si se desea modificar el valor de 'timeout' o 'timesleep'. Si no deseas modificar estos valores y prefieres usar los valores predeterminados (timeout=60 y timesleep=5), basta con realizar la solicitud de la siguiente manera, solo indicando el queryId.
queryFileStatus("<queryId>")
Si se desea modificar ambos parámetros, se utilizará el siguiente formato: → queryFileStatus("<queryId>", timeout, timesleep)
Si solo se desea modificar el valor de timeout, se utilizará: → queryFileStatusTimeout("<queryId>", timeout) )
Si solo se desea modificar el valor de timesleep, se utilizará: → queryFileStatusTimesleep("<queryId>", timesleep)
Esto devolverá:
IN_PROGRESS: la sentencia se está ejecutando.
FINISHED: la sentencia ha terminado y su resultado se ha volcado por completo al fichero.
Cómo utilizar el intérprete ﹪onesaitplatform.apimanager
A continuación se muestra un ejemplo de llamadas al API- Manager de la plataforma.
Mostrar help
La ayuda se muestra si se introduce la palabra help o una expresión no reconocible.
Modo debug
El modo debug permite ver la traza de ejecución del código.
Introducir credenciales
Se establece el token que se utilizará para las peticiones. En esta version %onesaitplatform.apimanager se pueden pasar expresiones z.get() para todos los argumentos de sus funciones.
Listar todas las APIs del usuario
Se listan las APIs de nuestro usuario para obtener la información básica de la API. También se pueden listar las APIs de otro usuarios (públicas y compartidas con el usuario correspondiente al token utilizado), y se podran listar todas las APIs a las que el usuario tenga acceso (con el token utilizado), utilizando → listAPIS()
En el contexto se guardan objectos lista de java, por lo que hay que acceder a la lista para obtener los resultados mediante índices.
Obtener más información sobre una API
Si se quiere obtener una información más amplia de una API se utiliza la siguiente expresión, findAPI("<api_name>", "<api_version>")
Hacer una petición a la API
Se realiza una llamada a la API creada para listar los elementos que hemos insertado en los pasos anteriores.
Crear una nueva API
Para crear una nueva API, se puede utilizar la función createAPI("<json_object>"). Esta función recibe un objeto JSON como parámetro y devuelve el siguiente resultado:
id: El identificador único de la nueva API.
identification: Un identificador adicional o un nombre asociado a la API creada.
version: La versión de la API. Si ya existían versiones anteriores, la nueva versión será incrementada automáticamente.
msg: Un mensaje que confirma la creación exitosa de la API, indicando "OK".
Eliminar una API
También es posible eliminar una API existente utilizando la función deleteAPI("<api_name>", "<api_version>"). Para ello, se debe proporcionar el nombre de la API (api_name) y la versión de la API (api_version) que se desea eliminar.
La función realizará la eliminación de la API correspondiente y, si la operación es exitosa, devolverá un mensaje de confirmación indicando que la API ha sido eliminada correctamente.
