Fuentes de datos externas

¿Qué son las fuentes de datos externas?

DatAscend permite a los usuarios conectar bases de datos externas a su sistema y gestionarlas desde DatAscend. Por ejemplo, un usuario podría tener una antigua base de datos SQL cuyos registros desea conservar, pero no quiere perder tiempo migrando, ahí es donde entran en juego las fuentes de datos externas.

Definición y finalidad de las fuentes de datos externas en el sistema.

El propósito de las fuentes de datos externas es permitir a los usuarios conectar y gestionar sus bases de datos externas desde dentro de DatAscend, utilizando las entidades de DatAscend. Esto significa que la interacción con las entidades externas y las entidades internas debería ser prácticamente igual.

Explicación de cómo se integran y utilizan (por ejemplo, conexión a bases de datos externas para el acceso dinámico a los datos).

Para integrar fuentes de datos externas, el primer paso es importar la fuente de datos externa utilizando el punto final específico. Después de la importación, se almacena un objeto de fuente de datos en DatAscend, con operaciones CRUD disponibles para gestionar la conexión.

La importación de la fuente de datos importa automáticamente las tablas de la base de datos externa como entidades externas a DatAscend.

Cómo realizar operaciones CRUD en fuentes de datos (no en entidades)

Traer todos los origenes de datos

GET /api/v1/datasources/

Respuesta:

{
  "error": false,
  "status": 200,
  "message": "string",
  "errors": [{}],
  "data": [
    {
      "id": "05f44d27-4450-4f96-886d-684cd290827a",
      "name": "DatasourceName",
      "type": "mysql",
      "host": "localhost",
      "port": 3306,
      "username": "DatabaseUsername",
      "password": "DatabasePassword",
      "database": "DatabaseName",
      "external": true
    }
  ],
  "pagination": {
    "hasPreviousPage": true,
    "hasNextPage": true,
    "previousPage": 0,
    "nextPage": 0,
    "recordsTotal": 0,
    "currentPage": 0,
    "startIndex": 0,
    "numPages": 0,
    "limit": 0
  }
}

Agrega un nuevo origen de datos

POST /api/v1/datasources/

Cuerpo:

{
  "name": "DatasourceName",
  "type": "mysql",
  "host": "localhost",
  "port": 3306,
  "username": "DatabaseUsername",
  "password": "DatabasePassword",
  "database": "DatabaseName",
  "external": true
}

• name: Nombre que utilizará DatAscend.
• type: Tipo de base de datos. Actualmente, solo se admiten mysql y postgres.
• host: Dirección donde se aloja la base de datos externa.
• port: Puerto del host mencionado anteriormente donde la base de datos acepta conexiones.
• username: nombre de usuario necesario para acceder a la base de datos externa (no es el nombre de usuario de DatAscend).
• password: contraseña necesaria para autenticarse en la base de datos externa (no es el nombre de usuario de DatAscend).
• database: nombre de la base de datos externa a la que conectarse.
• external: si la fuente de datos es externa, siempre debe ser true.

Respuesta:

{
  "error": true,
  "status": 0,
  "message": "string",
  "data": [
    {
      "id": "05f44d27-4450-4f96-886d-684cd290827a",
      "name": "DatasourceName",
      "type": "mysql",
      "host": "localhost",
      "port": 3306,
      "username": "DatabaseUsername",
      "password": "DatabasePassword",
      "database": "DatabaseName",
      "external": true
    }
  ],
  "entityName": "string"
}

Trae un origen de datos especifico

GET /api/v1/datasources/{datasourceName}

Parametros:

Nombre	Tipo	Desde	Descripcion
datasourceName	string	path	nombre de un origen de datos

Respuesta:

{
  "error": false,
  "status": 200,
  "message": "string",
  "errors": [{}],
  "data": [
    {
      "id": "05f44d27-4450-4f96-886d-684cd290827a",
      "name": "DatasourceName",
      "type": "mysql",
      "host": "localhost",
      "port": 3306,
      "username": "DatabaseUsername",
      "password": "DatabasePassword",
      "database": "DatabaseName",
      "external": true
    }
  ],
  "pagination": {
    "hasPreviousPage": true,
    "hasNextPage": true,
    "previousPage": 0,
    "nextPage": 0,
    "recordsTotal": 0,
    "currentPage": 0,
    "startIndex": 0,
    "numPages": 0,
    "limit": 0
  }
}

Borrar un origen de datos

DELETE /api/v1/datasources/{datasourceName}

Parametros:

Nombre	Tipo	Desde	Descripcion
datasourceName	string	path	Nombre del origen de datos

Respuesta:

{
  "error": false,
  "status": 200,
  "message": "string",
  "errors": [{}],
  "data": [
    {
      "id": "05f44d27-4450-4f96-886d-684cd290827a",
      "name": "DatasourceName",
      "type": "mysql",
      "host": "localhost",
      "port": 3306,
      "username": "DatabaseUsername",
      "password": "DatabasePassword",
      "database": "DatabaseName",
      "external": true
    }
  ],
  "pagination": {
    "hasPreviousPage": true,
    "hasNextPage": true,
    "previousPage": 0,
    "nextPage": 0,
    "recordsTotal": 0,
    "currentPage": 0,
    "startIndex": 0,
    "numPages": 0,
    "limit": 0
  }
}

Actualizar un origen de datos

PUT /api/v1/datasources/{UUID}

Parametros:

Nombre	Tipo	Desde	Descripcion
UUID	string	path	Identificador único universal del origen de datos

Cuerpo:

{
  "host": "localhost",
  "port": 3306,
  "username": "DatabaseUsername",
  "password": "DatabasePassword",
  "database": "DatabaseName"
}

• host: Dirección donde se aloja la base de datos externa.
• port: Puerto del host mencionado anteriormente donde la base de datos acepta conexiones.
• username: Nombre de usuario necesario para acceder a la base de datos externa (no es el nombre de usuario de DatAscend).
• password: Contraseña necesaria para autenticarse en la base de datos externa (no es la contraseña de DatAscend).
• database: Nombre de la base de datos externa a la que conectarse.

Respuesta:

{
  "error": false,
  "status": 200,
  "message": "string",
  "errors": [{}],
  "data": [
    {
      "id": "05f44d27-4450-4f96-886d-684cd290827a",
      "name": "DatasourceName",
      "type": "mysql",
      "host": "localhost",
      "port": 3306,
      "username": "DatabaseUsername",
      "password": "DatabasePassword",
      "database": "DatabaseName",
      "external": true
    }
  ],
  "pagination": {
    "hasPreviousPage": true,
    "hasNextPage": true,
    "previousPage": 0,
    "nextPage": 0,
    "recordsTotal": 0,
    "currentPage": 0,
    "startIndex": 0,
    "numPages": 0,
    "limit": 0
  }
}

Actualizar toda la estructura de metadatos de los origenes de datos.

POST /api/v1/datasources/metadata/update

Parametros:

Nombre	Tipo	Desde	Descripcion
version	string	query	Versión de la aplicación

Respuesta:

{
  "error": false,
  "status": 200,
  "message": "string",
  "errors": [{}],
  "data": [],
  "pagination": {
    "hasPreviousPage": true,
    "hasNextPage": true,
    "previousPage": 0,
    "nextPage": 0,
    "recordsTotal": 0,
    "currentPage": 0,
    "startIndex": 0,
    "numPages": 0,
    "limit": 0
  }
}

Consideraciones de seguridad.

• Tanto la contraseña como el nombre de usuario están cifrados en la base de datos.
• Las consideraciones de seguridad para la base de datos externa deben gestionarse en la base de datos original.

¿Cómo gestionar las entidades importadas?

Obtener un registro de entidad

Para obtener un registro de entidad de una entidad externa específica, se utiliza el mismo “endpoint” que para las entidades internas:

GET /api/v1/entities/{entity}

Obtener los metadatos de una entidad específica en un origen de datos específico.

GET /api/v1/datasources/{datasourceName}/{entity}/metadata

Parametros:

Nombre	Tipo	Desde	Descripcion
datasourceName	string	path	nombre del origen de datos
entityName	string	path	nombre de la entidad
version	string	query	versión de la aplicación

Respuesta:

{
  "error": true,
  "status": 0,
  "message": "string",
  "data": [
    {
      "id": "05f44d27-4450-4f96-886d-684cd290827a",
      "type": "internal",
      "objectLabel": "breed",
      "objectName": "breed",
      "datasource": "",
      "showOnMenu": true,
      "importable": true,
      "readOnly": false,
      "audited": true,
      "listAs": ["name"],
      "relationships": [
        {
          "name": "RS_cattle_breed",
          "label": "Relationship between cattle and breed",
          "relationName": "RS_cattle_breed",
          "relationshipType": "one-to-one",
          "lEntity": "cattle",
          "rEntity": "breed",
          "lKey": "id",
          "rKey": "id",
          "key": "K_id_id",
          "joinEntity": "J_cattle_breed",
          "joinLKey": "cattle_id",
          "joinRKey": "breed_id",
          "dependency": "breed",
          "dependencyRelation": "breed",
          "required": true
        }
      ],
      "fields": [
        {
          "type": "text",
          "inlineEdit": true,
          "reportable": true,
          "searchable": true,
          "importable": false,
          "indexable": false,
          "editable": true,
          "readonly": false,
          "required": true,
          "audited": true,
          "visible": true,
          "unique": false,
          "defaultValue": "",
          "defaultExp": "",
          "comments": "",
          "group": "basicInfo",
          "label": "Name",
          "regex": "",
          "name": "name",
          "help": "",
          "precision": 0,
          "size": 0,
          "len": 0,
          "options": [],
          "optionsExp": "",
          "schema": ""
        }
      ],
      "schema": "dasec"
    }
  ],
  "entityName": "string"
}

Obtener registros externos entre múltiples origenes de datos con una query

POST /api/v1/datasources/querybuilder/get

Parametros:

Nombre	Tipo	Desde	Descripcion
page	number	query	página para paginación
limit	number	query	límite para la paginación
version	string	query	versión de la aplicación

Cuerpo:

{
  "datasource": "employees",
  "entity": "departments",
  "columns": ["dept_name"],
  "combinator": "and",
  "not": false,
  "rules": [
    {
      "field": "dept_no",
      "operator": "=",
      "value": "10004"
    }
  ]
}

• datasource: origen de datos desde la que realizar la consulta
• entity: entidad a consultar
• columns: lista de columnas a consultar
• combinator: combinador de la consulta (and u or)
• not: si el combinador se niega
• rules: lista de cláusulas que se van a comparar
• field: campo con el que se va a comparar
• operator: operador de comparación
• value: el valor con el que se va a comparar o una subconsulta anidada

Respuesta:

{
  "error": false,
  "status": 200,
  "message": "string",
  "errors": [{}],
  "data": [
    {
      "queriedColumn": "0000"
    }
  ],
  "pagination": {
    "hasPreviousPage": true,
    "hasNextPage": true,
    "previousPage": 0,
    "nextPage": 0,
    "recordsTotal": 0,
    "currentPage": 0,
    "startIndex": 0,
    "numPages": 0,
    "limit": 0
  }
}

Agregar un registro en una tabla externa

POST /api/v1/datasources/{datasourceName}/{entity}

Parametros:

Nombre	Tipo	Desde	Descripcion
datasourceName	string	path	nombre del origen de datos
entity	string	path	nombre de la entidad externa
version	string	query	versión de la aplicación

Cuerpo:

{
  "column": ""
}

• column: Ejemplo. El cuerpo de la solicitud variará en función de la estructura de la entidad externa.

Respuesta:

{
  "error": true,
  "status": 0,
  "message": "string",
  "data": [
    {
      "column": ""
    }
  ],
  "entityName": "string",
  "datasource": "employees"
}

Actualizar un registro en una tabla externa

PUT /api/v1/datasources/{datasourceName}/{entity}/{id}

Parámetros:

Nombre	Tipo	Desde	Descripción
datasourceName	string	path	nombre del origen de datos
entity	string	path	nombre de la entidad externa
id	string	path	id del registro
version	string	query	versión de la aplicación
column	string	query	columna para referenciar como llave primaria

Cuerpo:

{
  "column": ""
}

• column: Ejemplo. El cuerpo de la solicitud variará en función de la estructura de la entidad externa.

Respuesta:

{
  "error": true,
  "status": 0,
  "message": "string",
  "data": [
    {
      "column": ""
    }
  ],
  "entityName": "string",
  "datasource": "employees"
}

Borrar un registro en una tabla externa

DELETE /api/v1/datasources/{datasourceName}/{entity}/{id}

Parametros:

Nombre	Tipo	Desde	Descripcion
datasourceName	string	path	nombre del origen de datos
entity	string	path	nombre de la entidad externa
id	string	path	id del registro
version	string	query	versión de la aplicación
column	string	query	columna para referenciar como llave primaria

Respuesta:

{
  "error": true,
  "status": 0,
  "message": "string",
  "data": [
    {
      "column": ""
    }
  ],
  "entityName": "string",
  "datasource": "employees"
}

• column: Ejemplo. El cuerpo de la solicitud variará en función de la estructura de la entidad externa.

¿Cómo se sincronizan o actualizan las entidades importadas?

Para permitir la sincronización entre el origen de datos externa importado y los cambios en la base de datos original, el sistema se actualiza y reimporta automáticamente cada 5 minutos.

Limitaciones

• Solo se pueden gestionar registros utilizando origenes de datos externas. La estructura o los metadatos de los origenes de datos externas (por ejemplo, crear nuevas tablas, añadir o modificar columnas, cambiar claves primarias o restricciones) no se pueden actualizar desde DatAscend y deben gestionarse en la base de datos original.
• Actualmente solo se admiten bases de datos PostgreSQL y MySQL.
• Todas las fuentes de datos externas deben tener su propio nombre único cuando se importan al sistema (puede importar dos bases de datos llamadas «empleados», pero al importarlas, cada una debe tener su propio nombre único, como «empleados1» y «empleados2»).
• Las bases de datos originales deben configurarse para aceptar conexiones http.
• La importación de fuentes de datos MySQL debe configurarse para utilizar el complemento de autenticación mysql_native_password.
• El rendimiento de las fuentes de datos externas depende de la conexión a Internet.

Tipos de bases de datos compatibles

• PostgreSQL
• MySQL