Uso del SDK de Node.js para Azure Mobile Apps

En este artículo se ofrece información detallada y ejemplos sobre cómo trabajar con un backend de Node.js en Azure Mobile Apps.

Introducción

Azure Mobile Apps proporciona la funcionalidad de agregar una API web de acceso a datos optimizada para móviles a una aplicación web. El SDK de Azure Mobile Apps se proporciona para las aplicaciones web de ASP.NET Framework y Node.js. El SDK proporciona las siguientes operaciones:

• Operaciones de tabla (lectura, inserción, actualización, eliminación) para el acceso a datos
• Operaciones API personalizadas

Ambas operaciones proporcionan autenticación a través de todos los proveedores de identidad que Azure App Service permite. Estos proveedores incluyen proveedores de identidades sociales, como Facebook, Twitter, Google y Microsoft Entra ID para la identidad empresarial.

Plataformas compatibles

El SDK de Node.js de Azure Mobile Apps admite Node 6.x y versiones posteriores, y se ha probado hasta Node 12.x. Aunque es posible que funcionen otras versiones de Node, no son compatibles.

El SDK de Node.js de Azure Mobile Apps admite dos controladores de base de datos:

• El controlador de node-mssql admite instancias de SQL Server locales y de Azure SQL Database.
• El controlador sqlite3 admite bases de datos de SQLite en una sola instancia.

Creación de un back-end de Node básico mediante la línea de comandos

Todos los backend de Node.js de Azure Mobile Apps se inician como una aplicación Express. Express es el marco del servicio web más utilizado disponible para Node.js. Puede crear una aplicación Express básica de la forma siguiente:

1. En una ventana de comandos o de PowerShell, cree un directorio para el proyecto:

   $ mkdir basicapp
   

2. Ejecute npm init para inicializar la estructura del paquete:

   $ cd basicapp
   $ npm init
   

   El comando npm init le formulará una serie de preguntas para inicializar el proyecto. Vea el resultado del ejemplo:

   

3. Instale las bibliotecas express y azure-mobile-apps desde el repositorio de npm:

   npm install --save express azure-mobile-apps
   

4. Cree un archivo app.js para implementar el servidor móvil básico:

   var express = require('express'),
       azureMobileApps = require('azure-mobile-apps');
   
   var app = express(),
       mobile = azureMobileApps();
   
   // Define a TodoItem table.
   mobile.tables.add('TodoItem');
   
   // Add the Mobile API so it is accessible as a Web API.
   app.use(mobile);
   
   // Start listening on HTTP.
   app.listen(process.env.PORT || 3000);
   

Esta aplicación crea una API web sencilla optimizada para móviles con un único punto de conexión (/tables/TodoItem) que proporciona el acceso no autenticado a un almacén de datos SQL subyacente mediante un esquema dinámico. Es adecuado para los siguientes inicios rápidos de la biblioteca de cliente:

• Apache Cordova
• Windows (UWP)
• Windows (WPF)
• Xamarin.Android
• Xamarin.Forms
• Xamarin.iOS

Puede encontrar el código de esta aplicación básica en el área de ejemplos en GitHub.

Habilitación de una página de inicio para la aplicación

Muchas aplicaciones son una combinación de aplicaciones móviles y web. Puede usar el marco Express para combinar las dos facetas. Sin embargo, es posible que en ocasiones solo quiera implementar una interfaz móvil. Es útil proporcionar una página principal para garantizar que el servicio de aplicaciones está en funcionamiento. Puede proporcionar su propia página de inicio o habilitar una de carácter temporal. Para habilitar una página principal temporal, use el siguiente código para crear una instancia de Azure Mobile Apps:

var mobile = azureMobileApps({ homePage: true });

Puede agregar esta opción disponible al desarrollar localmente, puede agregar este valor al archivo de configuración azureMobile.js:

module.exports = {
    homePage: true,
};

Puede agregar otros valores al archivo azureMobile.js, según sea necesario.

Operaciones de tabla

El SDK del servidor de Node.js de azure-mobile-apps proporciona mecanismos para exponer las tablas de datos almacenadas en Azure SQL Database como una API web. Proporciona cinco operaciones:

Esta API web admite OData v3 y amplía el esquema de tabla para admitir la sincronización de datos sin conexión.

Definición de tablas con un esquema dinámico

Para poder usar una tabla, debe definirla. Puede definir tablas con un esquema estático (en el que define las columnas en el esquema) o dinámicamente (en el que el SDK controla el esquema según las solicitudes entrantes). Además, puede controlar aspectos específicos de la API web agregando código JavaScript a la definición.

Como procedimiento recomendado, debe definir cada tabla en un archivo de JavaScript en el directorio tables y, luego, usar el método tables.import() para importar las tablas. Al ampliar el ejemplo basic-app, el archivo app.js debe ajustarse:

var express = require('express'),
    azureMobileApps = require('azure-mobile-apps');

var app = express(),
    mobile = azureMobileApps();

// Define the database schema that is exposed.
mobile.tables.import('./tables');

// Provide initialization of any tables that are statically defined.
mobile.tables.initialize().then(function () {
    // Add the Mobile API so it is accessible as a Web API.
    app.use(mobile);

    // Start listening on HTTP.
    app.listen(process.env.PORT || 3000);
});

Defina la tabla en ./tables/TodoItem.js:

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Additional configuration for the table goes here.

module.exports = table;

Las tablas usan un esquema dinámico de forma predeterminada.

Definición de tablas con un esquema estático

Puede definir explícitamente las columnas que desea exponer a través de la API web. El SDK de Node.js de azure-mobile-apps agregará automáticamente todas las columnas adicionales necesarias para la sincronización de datos sin conexión a la lista que se proporcione. Por ejemplo, las aplicaciones de cliente de inicio rápido requieren una tabla con dos columnas: text (una cadena) y complete (un booleano). Esta tabla se puede definir en el archivo JavaScript de definición de la tabla (ubicado en el directorio de tables) de la forma siguiente:

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Define the columns within the table.
table.columns = {
    "text": "string",
    "complete": "boolean"
};

// Turn off the dynamic schema.
table.dynamicSchema = false;

module.exports = table;

Si define las tablas estáticamente, también debe llamar al método tables.initialize() para crear el esquema de base de datos en el inicio. El método tables.initialize() devuelve promise, que se usa para asegurarse de que el servicio web no atienda solicitudes antes de que la base de datos se inicialice.

Uso de SQL Server Express como almacén de datos de desarrollo en el equipo local

El SDK de Node.js de Azure Mobile Apps proporciona tres opciones para servidor datos de forma estándar:

• Use el controlador memory para proporcionar un almacén de ejemplos no persistente.
• Utilice el controlador mssql para ofrecer un almacén de datos SQL Server Express para desarrollo.
• Use el controlador mssql para ofrecer un almacén de datos de Azure SQL Database para producción.

El SDK de Node.js de Azure Mobile Apps usa el paquete de mssql para Node.js para establecer y usar una conexión tanto a SQL Server Express como a SQL Database. Este paquete requiere que habilite las conexiones TCP en la instancia de SQL Server Express.

1. Descargue e instale Microsoft SQL Server 2019 Developer.

2. Ejecute Configuration Manager:

   • Expanda el nodo Configuración de red de SQL Server en el menú de árbol.
   • Seleccione Protocolos para nombre de instancia.
   • Haga clic con el botón derecho en TCP/IP y seleccione Habilitar. Seleccione Aceptar en el cuadro de diálogo emergente.
   • Seleccione Servicios de SQL Server en el menú de árbol.
   • Haga clic con el botón derecho en SQL Server (nombre de instancia) y seleccione Reiniciar.
   • Cierre Configuration Manager.

También tendrá que crear un nombre de usuario y una contraseña que Azure Mobile Apps pueda usar para conectarse a la base de datos. Asegúrese de que el usuario que crea tiene el rol del servidor dbcreator. Para más información sobre la configuración de usuarios, consulte la documentación SQL Server.

Asegúrese de registrar el nombre de usuario y la contraseña que seleccionó. Puede que necesite asignar más permisos o roles de servidor en función de los requisitos de la base de datos.

La aplicación de Node.js lee la variable de entorno SQLCONNSTR_MS_TableConnectionString de la cadena de conexión de esta base de datos. Se puede establecer en el entorno. Por ejemplo, puede usar PowerShell para establecer esta variable de entorno:

$env:SQLCONNSTR_MS_TableConnectionString = "Server=127.0.0.1; Database=mytestdatabase; User Id=azuremobile; Password=T3stPa55word;"

Acceda a la base de datos a través de una conexión TCP/IP. Proporcione un nombre de usuario y una contraseña para la conexión.

Configuración del proyecto para el desarrollo local

Azure Mobile Apps lee un archivo de JavaScript denominado azureMobile.js del sistema de archivos local. No utilice este archivo para configurar el SDK de Azure Mobile Apps en producción. En su lugar, use Configuración de aplicaciones en Azure Portal.

El archivo azureMobile.js debe exportar un objeto de configuración. La configuración más común es la siguiente:

• Configuración de base de datos
• Configuración del registro de diagnóstico
• Configuración de CORS alternativa

Este archivo azureMobile.js de ejemplo implementa la configuración de la base de datos anterior:

module.exports = {
    cors: {
        origins: [ 'localhost' ]
    },
    data: {
        provider: 'mssql',
        server: '127.0.0.1',
        database: 'mytestdatabase',
        user: 'azuremobile',
        password: 'T3stPa55word'
    },
    logging: {
        level: 'verbose'
    }
};

Se recomienda que agregue azureMobile.js a su archivo .gitignore (o a otro archivo de omisiones de control de código fuente) para evitar que las contraseñas se almacenen en la nube.

Configuración de aplicaciones móviles

La mayoría de los valores del archivo azureMobile.js tienen una configuración de aplicación equivalente en Azure Portal. Para configurar la aplicación en Configuración de aplicaciones, use la siguiente lista:

Si cambia la mayoría de las opciones de configuración de la aplicación habrá que reiniciar el servicio.

Uso de Azure SQL como almacén de datos de producción

El uso de Azure SQL Database como almacén de datos es idéntico en todos los tipos de aplicaciones de Azure App Service. Si aún no lo ha hecho, siga estos pasos para crear un backend de Azure App Service. Cree una instancia de Azure SQL y, después, establezca la configuración de la aplicación SQLCONNSTR_MS_TableConnectionString en la cadena de conexión de la instancia de Azure SQL que desea usar. Asegúrese de que la instancia de Azure App Service que ejecuta el backend puede comunicarse con la instancia de Azure SQL.

Requerir autenticación para acceder a las tablas

Si quiere usar la autenticación de App Service con el punto de conexión tables, debe configurar la autenticación de App Service en Azure Portal primero. Para obtener más información, consulte la guía de configuración del proveedor de identidades que quiere usar:

• Configuración de la autenticación de Microsoft Entra
• Configurar la autenticación de Facebook
• Configurar la autenticación de Google
• Configuración de la autenticación de Microsoft
• Configurar la autenticación de Twitter

Cada tabla tiene una propiedad de acceso que se puede usar para controlar el acceso a la tabla. En el ejemplo siguiente se muestra una tabla definida estáticamente con la autenticación necesaria.

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Define the columns within the table.
table.columns = {
    "text": "string",
    "complete": "boolean"
};

// Turn off the dynamic schema.
table.dynamicSchema = false;

// Require authentication to access the table.
table.access = 'authenticated';

module.exports = table;

La propiedad de acceso puede tomar uno de tres valores:

• anonymous indica que la aplicación cliente puede leer los datos sin autenticación.
• authenticated indica que la aplicación cliente tiene que enviar un token de autenticación válido con la solicitud.
• disabled indica que esta tabla está deshabilitada actualmente.

Si la propiedad de acceso no está definida, se permite el acceso no autenticado.

Uso de notificaciones de autenticación con las tablas

Puede configurar varias notificaciones que se solicitan cuando se configura la autenticación. Estas notificaciones no suelen estar disponibles por medio del objeto context.user . Sin embargo, se pueden recuperar mediante el uso del método context.user.getIdentity(). El método getIdentity() devuelve una promesa que se resuelve en un objeto. El objeto se protege con clave mediante el método de autenticación (facebook, google, twitter, microsoftaccount o aad).

Por ejemplo, si configura la autenticación de Microsoft Entra y solicita la notificación de direcciones de correo electrónico, puede agregar la dirección de correo electrónico al registro con el controlador de tabla siguiente:

var azureMobileApps = require('azure-mobile-apps');

// Create a new table definition.
var table = azureMobileApps.table();

table.columns = {
    "emailAddress": "string",
    "text": "string",
    "complete": "boolean"
};
table.dynamicSchema = false;
table.access = 'authenticated';

/**
* Limit the context query to those records with the authenticated user email address
* @param {Context} context the operation context
* @returns {Promise} context execution Promise
*/
function queryContextForEmail(context) {
    return context.user.getIdentity().then((data) => {
        context.query.where({ emailAddress: data.aad.claims.emailaddress });
        return context.execute();
    });
}

/**
* Adds the email address from the claims to the context item - used for
* insert operations
* @param {Context} context the operation context
* @returns {Promise} context execution Promise
*/
function addEmailToContext(context) {
    return context.user.getIdentity().then((data) => {
        context.item.emailAddress = data.aad.claims.emailaddress;
        return context.execute();
    });
}

// Configure specific code when the client does a request.
// READ: only return records that belong to the authenticated user.
table.read(queryContextForEmail);

// CREATE: add or overwrite the userId based on the authenticated user.
table.insert(addEmailToContext);

// UPDATE: only allow updating of records that belong to the authenticated user.
table.update(queryContextForEmail);

// DELETE: only allow deletion of records that belong to the authenticated user.
table.delete(queryContextForEmail);

module.exports = table;

Para ver qué notificaciones están disponibles, use un explorador web para ver el punto de conexión /.auth/me de su sitio.

Deshabilitación del acceso a operaciones de tabla específicas

Además de aparecer en la tabla, la propiedad de acceso puede usarse para controlar operaciones individuales. Hay cuatro operaciones:

• read es la operación GET de RESTful en la tabla.
• insert es la operación POST de RESTful en la tabla.
• update es la operación PATCH de RESTful en la tabla.
• delete es la operación DELETE de RESTful en la tabla.

Por ejemplo, es posible que quiera proporcionar una tabla de solo lectura no autenticada:

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Read-only table. Only allow READ operations.
table.read.access = 'anonymous';
table.insert.access = 'disabled';
table.update.access = 'disabled';
table.delete.access = 'disabled';

module.exports = table;

Ajuste de la consulta que se usa con las operaciones de tabla

Un requisito común para las operaciones de tabla consiste en proporcionar una vista restringida de los datos. Por ejemplo, puede proporcionar una tabla etiquetada con el identificador del usuario autenticado de modo que solo pueda leer o actualizar sus propios registros. La definición de la tabla siguiente proporcionará esta funcionalidad:

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Define a static schema for the table.
table.columns = {
    "userId": "string",
    "text": "string",
    "complete": "boolean"
};
table.dynamicSchema = false;

// Require authentication for this table.
table.access = 'authenticated';

// Ensure that only records for the authenticated user are retrieved.
table.read(function (context) {
    context.query.where({ userId: context.user.id });
    return context.execute();
});

// When adding records, add or overwrite the userId with the authenticated user.
table.insert(function (context) {
    context.item.userId = context.user.id;
    return context.execute();
});

module.exports = table;

Las operaciones que normalmente ejecutan una consulta tendrán una propiedad de consulta que se puede ajustar con una cláusula where. La propiedad de consulta es un objeto QueryJS que se usa para convertir una consulta de OData en algo que puede procesar el back-end de datos. En los casos de igualdad simple (como el anterior), puede usarse una asignación. También puede agregar cláusulas SQL específicas:

context.query.where('myfield eq ?', 'value');

Configuración de una eliminación temporal en una tabla

Una eliminación temporal no elimina realmente los registros. Los marca como eliminados dentro de la base de datos al establecer la columna de eliminados en true. El SDK de Azure Mobile Apps quita automáticamente los registros eliminados temporalmente de los resultados, salvo que el SDK de cliente móvil use includeDeleted(). Si quiere configurar una tabla para la eliminación temporal, establezca la propiedad softDelete en el archivo de definición de tabla:

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Define the columns within the table.
table.columns = {
    "text": "string",
    "complete": "boolean"
};

// Turn off the dynamic schema.
table.dynamicSchema = false;

// Turn on soft delete.
table.softDelete = true;

// Require authentication to access the table.
table.access = 'authenticated';

module.exports = table;

Establezca un mecanismo para eliminar registros de forma permanente, como una aplicación cliente, un trabajo web, una función de Azure o una API personalizada.

Inicialización de la base de datos con datos

Al crear una nueva aplicación, puede inicializar una tabla con datos. Puede inicializar los datos del archivo JavaScript de definición de la tabla de la forma siguiente:

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Define the columns within the table.
table.columns = {
    "text": "string",
    "complete": "boolean"
};
table.seed = [
    { text: 'Example 1', complete: false },
    { text: 'Example 2', complete: true }
];

// Turn off the dynamic schema.
table.dynamicSchema = false;

// Require authentication to access the table.
table.access = 'authenticated';

module.exports = table;

La inicialización de datos solo se produce si usó el SDK de Azure Mobile Apps para crear la tabla. Si la tabla ya existe en la base de datos, no se inserta ningún dato en la tabla. Si el esquema dinámico está activado, se deducirá el esquema de los datos inicializados.

Se recomienda llamar expresamente al método tables.initialize() para crear la tabla cuando el servicio comienza a ejecutarse.

Habilitación de la compatibilidad con Swagger

Azure Mobile Apps incorpora compatibilidad con Swagger. Para habilitar la compatibilidad con Swagger, instale primero el archivo swagger-ui como una dependencia:

npm install --save swagger-ui

Puede habilitar la compatibilidad con Swagger en el constructor de Azure Mobile Apps:

var mobile = azureMobileApps({ swagger: true });

Es probable que solo quiera habilitar la compatibilidad con Swagger en las ediciones de desarrollo. Mediante la configuración de la aplicación NODE_ENV puede habilitar la compatibilidad con Swagger:

var mobile = azureMobileApps({ swagger: process.env.NODE_ENV !== 'production' });

El punto de conexión swagger se encuentra en http://yoursite.azurewebsites.net/swagger. Puede acceder a la interfaz de usuario de Swagger a través del punto de conexión de /swagger/ui . Si elige pedir autenticación en la aplicación entera, se producirá un error en Swagger. Para obtener los mejores resultados, permita las solicitudes no autenticadas en la configuración de autenticación y autorización de Azure App Service y, luego, controle la autenticación mediante la propiedad table.access.

También puede agregar la opción de Swagger a su archivo azureMobile.js si solo quiere que haya compatibilidad con Swagger para el desarrollo local.

API personalizadas

Además de Data Access API a través del punto de conexión /tables, Azure Mobile Apps puede proporcionar cobertura de API personalizada. Las API personalizadas se definen de forma similar a las definiciones de tabla y pueden tener acceso a las mismas utilidades, incluida la autenticación.

Definición de una API personalizada

La definición de API personalizadas es muy similar a la de API de tablas:

1. Crear un directorio api.
2. Cree un archivo JavaScript de definición de API en el directorio api.
3. Use el método import para importar el directorio api.

A continuación se muestra la definición de la API de prototipo basada en el ejemplo de aplicación básica usado anteriormente:

var express = require('express'),
    azureMobileApps = require('azure-mobile-apps');

var app = express(),
    mobile = azureMobileApps();

// Import the custom API.
mobile.api.import('./api');

// Add the Mobile API so it is accessible as a Web API.
app.use(mobile);

// Start listening on HTTP
app.listen(process.env.PORT || 3000);

Veamos un ejemplo de una API sencilla que devolverá la fecha del servidor mediante el método Date.now(). Este es el archivo api/date.js:

var api = {
    get: function (req, res, next) {
        var date = { currentTime: Date.now() };
        res.status(200).type('application/json').send(date);
    });
};

module.exports = api;

Cada parámetro es uno de los verbos estándar de RESTful: GET, POST, PATCH o DELETE. El método es una función estándar de ExpressJS middleware que envía la salida necesaria.

Autenticación necesaria para el acceso a una API personalizada

El SDK de Azure Mobile Apps implementa la autenticación de la misma manera tanto para el punto de conexión tables como para las API personalizadas. Para agregar autenticación a la API desarrollada en la sección anterior, agregue una propiedad access:

var api = {
    get: function (req, res, next) {
        var date = { currentTime: Date.now() };
        res.status(200).type('application/json').send(date);
    });
};
// All methods must be authenticated.
api.access = 'authenticated';

module.exports = api;

También puede especificar la autenticación en operaciones específicas:

var api = {
    get: function (req, res, next) {
        var date = { currentTime: Date.now() };
        res.status(200).type('application/json').send(date);
    }
};
// The GET methods must be authenticated.
api.get.access = 'authenticated';

module.exports = api;

Debe usar el mismo token que se utiliza para el punto de conexión tables en las API personalizadas que requieren autenticación.

Control de cargas de archivos de gran tamaño

El SDK de Azure Mobile Apps usa el middleware de analizador de cuerpo para aceptar y descodificar el contenido del cuerpo del envío. Puede configurar previamente el analizador de cuerpo para aceptar tamaños mayores de cargas de archivos:

var express = require('express'),
    bodyParser = require('body-parser'),
    azureMobileApps = require('azure-mobile-apps');

var app = express(),
    mobile = azureMobileApps();

// Set up large body content handling.
app.use(bodyParser.json({ limit: '50mb' }));
app.use(bodyParser.urlencoded({ limit: '50mb', extended: true }));

// Import the custom API.
mobile.api.import('./api');

// Add the Mobile API so it is accessible as a Web API.
app.use(mobile);

// Start listening on HTTP.
app.listen(process.env.PORT || 3000);

El archivo está codificado en Base 64 antes de la transmisión, por lo que aumenta el tamaño de la carga real y, por tanto, el que debe tener en cuenta.

Ejecución de instrucciones SQL personalizadas

El SDK de Azure Mobile Apps permite el acceso a todo el contexto a través del objeto de solicitud. Puede ejecutar fácilmente instrucciones SQL con parámetros para el proveedor de datos definido:

var api = {
    get: function (request, response, next) {
        // Check for parameters. If not there, pass on to a later API call.
        if (typeof request.params.completed === 'undefined')
            return next();

        // Define the query. Anything that the mssql
        // driver can handle is allowed.
        var query = {
            sql: 'UPDATE TodoItem SET complete=@completed',
            parameters: [{
                completed: request.params.completed
            }]
        };

        // Execute the query. The context for Azure Mobile Apps is available through
        // request.azureMobile. The data object contains the configured data provider.
        request.azureMobile.data.execute(query)
        .then(function (results) {
            response.json(results);
        });
    }
};

api.get.access = 'authenticated';
module.exports = api;

Depuración

Depuración, diagnóstico y solución de problemas de Azure Mobile Apps

Azure App Service proporciona varias técnicas de depuración y de solución de problemas para las aplicaciones Node.js. Para empezar a solucionar problemas de su backend de Node.js de Azure Mobile Apps, consulte los siguientes artículos:

• Supervisión de Azure App Service
• Habilitación del registro de diagnóstico para aplicaciones web en Azure App Service
• Solución de problemas de aplicaciones de nodo Azure App Service

Las aplicaciones Node.js tienen acceso a una amplia gama de herramientas de registro de diagnóstico. Internamente, el SDK de Node.js de Azure Mobile Apps usa [Winston] para el registro de diagnóstico. El registro se habilita automáticamente al habilitar el modo de depuración o al establecer la configuración de la aplicación MS_DebugMode en True en Azure Portal. Los registros generados aparecerán en los registros de diagnóstico en Azure Portal.