Uso del SDK de Node.js para Azure Mobile Apps

En este artículo se proporciona información detallada y ejemplos que muestran cómo trabajar con un back-end de NodeJS para Azure Mobile Apps.

Introducción

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

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

Ambas operaciones proporcionan autenticación en todos los proveedores de identidades 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 admitidas

Azure Mobile Apps Node.js SDK admite Node 6.x y versiones posteriores y se ha probado hasta Node 12.x. Otras versiones de Node podrían funcionar, pero no se admiten.

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

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

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

Cada back-end de Azure Mobile Apps Node.js se inicia como una aplicación de Express. Express es el marco de servicio web más popular disponible para Node.js. Puede crear una aplicación básica de Express de la siguiente manera:

1. En un comando o ventana 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 formula un conjunto de preguntas para inicializar el proyecto. Vea la salida de ejemplo:

   de salida de npm init

3. Instale las bibliotecas de 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 optimizada para dispositivos móviles con un único punto de conexión (/tables/TodoItem) que proporciona acceso no autenticado a un almacén de datos SQL subyacente mediante un esquema dinámico. Es adecuado para seguir los inicios rápidos de la biblioteca cliente:

• de 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 de en GitHub.

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

Muchas aplicaciones son una combinación de aplicaciones web y móviles. Puede usar el marco Express para combinar las dos facetas. A veces, sin embargo, es posible que quiera implementar solo una interfaz móvil. Resulta útil proporcionar una página principal para asegurarse de que app Service está en funcionamiento. Puede proporcionar su propia página principal o habilitar una página principal temporal. Para habilitar una página principal temporal, use el código siguiente para crear instancias de Azure Mobile Apps:

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

Si solo desea que esta opción esté disponible al desarrollar localmente, puede agregar esta configuración al archivo de configuración de azureMobile.js:

module.exports = {
    homePage: true,
};

Puede agregar otras opciones de configuración al archivo azureMobile.js, según sea necesario.

Operaciones de tabla

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

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

Definición de tablas mediante un esquema dinámico

Para poder usar una tabla, debe definirla. Puede definir tablas mediante un esquema estático (donde se definen las columnas del esquema) o dinámicamente (donde el SDK controla el esquema en función de 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 JavaScript en el directorio tables y, a continuación, usar el método tables.import() para importar las tablas. Al extender el ejemplo de aplicación básica, ajustaría el archivo app.js:

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 mediante un esquema estático

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

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 tablas estáticamente, también debe llamar al método tables.initialize() para crear el esquema de la base de datos al iniciarse. El método tables.initialize() devuelve un promesa para que el servicio web no sirva solicitudes antes de que se inicialice la base de datos.

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

El SDK de azure Mobile Apps Node.js proporciona tres opciones para servir datos de forma predeterminada:

• Use el controlador memoria para proporcionar un almacén de ejemplo no persistente.
• Use el controlador de mssql para proporcionar un almacén de datos de SQL Server Express para el desarrollo.
• Use el controlador de mssql para proporcionar 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 Node.js mssql para establecer y usar una conexión a SQL Server Express y 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 de 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 de SQL Server Services 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 cree tenga el rol de servidor dbcreator. Para obtener más información sobre cómo configurar usuarios, consulte la documentación de SQL Server

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

La aplicación Node.js lee la variable de entorno SQLCONNSTR_MS_TableConnectionString para la cadena de conexión de esta base de datos. Puede establecer esta variable 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 desde el sistema de archivos local. No use este archivo para configurar el SDK de Azure Mobile Apps en producción. En su lugar, use configuración de la aplicación en Azure Portal.

El archivo azureMobile.js debe exportar un objeto de configuración. Los valores más comunes son:

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

En este ejemplo azureMobile.js archivo se implementa la configuración de 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 agregar azureMobile.js al archivo de .gitignore (u otro archivo de omisión de control de código fuente) para evitar que las contraseñas se almacenen en la nube.

Configuración de las opciones de aplicación para la aplicación móvil

La mayoría de las opciones de configuración del archivo azureMobile.js tienen una configuración de aplicación equivalente en Azure Portal. Use la lista siguiente para configurar la aplicación en Configuración de la aplicación:

Cambiar la mayoría de la configuración de la aplicación requiere un reinicio del 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 aplicación de Azure App Service. Si aún no lo ha hecho, siga estos pasos para crear un back-end de Azure App Service. Cree una instancia de Azure SQL y establezca la configuración de la aplicación SQLCONNSTR_MS_TableConnectionString en la cadena de conexión de la instancia de Azure SQL que quiera usar. Asegúrese de que azure App Service que ejecuta el back-end pueda comunicarse con la instancia de Azure SQL.

Requerir autenticación para el acceso a tablas

Si quiere usar la autenticación de App Service con el punto de conexión de 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
• Configurar la autenticación de Microsoft
• Configurar la autenticación de Twitter

Cada tabla tiene una propiedad de acceso que 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 access puede tomar uno de estos tres valores:

• anónimo indica que la aplicación cliente puede leer datos sin autenticación.
• autenticado indica que la aplicación cliente debe enviar un token de autenticación válido con la solicitud.
• deshabilitado indica que esta tabla está deshabilitada actualmente.

Si la propiedad access 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 están disponibles normalmente a través del objeto context.user. Sin embargo, puede recuperarlos mediante el método context.user.getIdentity(). El método getIdentity() devuelve una promesa que se resuelve en un objeto . El objeto está clavedo por el método de autenticación (facebook, google, twitter, microsoftaccounto 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 del sitio.

Deshabilitar el acceso a operaciones de tabla específicas

Además de aparecer en la tabla, la propiedad access se puede usar para controlar operaciones individuales. Hay cuatro operaciones:

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

Por ejemplo, puede que quiera proporcionar una tabla sin autenticar de solo lectura:

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 es proporcionar una vista restringida de los datos. Por ejemplo, puede proporcionar una tabla etiquetada con el identificador de usuario autenticado, de modo que solo pueda leer o actualizar sus propios registros. La siguiente definición de tabla proporciona 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 tienen una propiedad de consulta que puede ajustar mediante una cláusula where. La propiedad query es un objeto QueryJS que se usa para convertir una consulta de OData en algo que el back-end de datos pueda procesar. Para casos de igualdad simples (como el anterior), puede usar un mapa. 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. En su lugar, los marca como eliminados dentro de la base de datos estableciendo la columna eliminada en true. El SDK de Azure Mobile Apps quita automáticamente los registros eliminados temporalmente de los resultados a menos que el SDK de cliente móvil use includeDeleted(). Para configurar una tabla para una 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, es posible que quiera inicializar una tabla con datos. Puede inicializar los datos en el archivo JavaScript de definición de tabla de la siguiente manera:

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 propagación de datos solo se produce cuando se ha usado 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, el esquema se deduce de los datos de inicialización.

Se recomienda llamar explícitamente al método tables.initialize() para crear la tabla cuando el servicio empiece a ejecutarse.

Habilitación de la compatibilidad con Swagger

Azure Mobile Apps incluye compatibilidad integrada con swagger. Para habilitar la compatibilidad con Swagger, primero instale swagger-ui como dependencia:

npm install --save swagger-ui

Después, puede habilitar la compatibilidad con Swagger en el constructor de Azure Mobile Apps:

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

Probablemente solo quiera habilitar la compatibilidad con Swagger en las ediciones de desarrollo. Puede habilitar la compatibilidad con Swagger en el desarrollo mediante la configuración de la aplicación NODE_ENV:

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

El punto de conexión de swagger se encuentra en http://su sitio.azurewebsites.net/swagger. Puede acceder a la interfaz de usuario de Swagger a través del punto de conexión de /swagger/ui. Si decide requerir autenticación en toda la aplicación, Swagger genera un error. Para obtener los mejores resultados, elija permitir solicitudes no autenticadas en la configuración de autenticación y autorización de Azure App Service y, a continuación, controlar la autenticación mediante la propiedad table.access.

También puede agregar la opción Swagger al archivo azureMobile.js si solo desea que Swagger admita el desarrollo localmente.

API personalizadas

Además de data Access API a través del punto de conexión de /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 acceder a todas las mismas instalaciones, incluida la autenticación.

Definición de una API personalizada

Las API personalizadas se definen de la misma manera que la API de tablas:

1. Cree 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.

Esta es la definición de API de prototipo basada en el ejemplo de aplicación básica que usamos 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);

Vamos a tomar un ejemplo de API que devuelve 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 RESTful estándar: GET, POST, PATCH o DELETE. El método es un middleware ExpressJS estándar función que envía la salida necesaria.

Requerir autenticación para el acceso a una API personalizada

El SDK de Azure Mobile Apps implementa la autenticación de la misma manera para el punto de conexión de tables y 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;

El mismo token que se usa para el punto de conexión de tables debe usarse para las API personalizadas que requieren autenticación.

Control de cargas de archivos grandes

El SDK de Azure Mobile Apps usa middleware del analizador de cuerpo para aceptar y descodificar el contenido del cuerpo en el envío. Puede preconfigurar el analizador de cuerpo para aceptar cargas de archivos más grandes:

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. Esta codificación aumenta el tamaño de la carga real (y el tamaño 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 en 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 solución de problemas para Node.js aplicaciones. Para empezar a solucionar problemas del back-end de Azure Mobile Apps Node.js, consulte los artículos siguientes:

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

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