Procedimiento para usar el complemento Apache Cordova para Azure Mobile Apps

En esta guía se muestran algunos escenarios comunes del uso del último complemento de Apache Cordova para Azure Mobile Apps. Si no está familiarizado con Azure Mobile Apps, realice primero el tutorial Guía de inicio rápido de Azure Mobile Apps para crear un back-end, crear una tabla y descargar un proyecto de Apache Cordova previamente compilado. En esta guía nos centramos en el complemento de Apache Cordova del lado cliente.

Plataformas compatibles

Este SDK es compatible con la versión 6.0.0 y posterior de Apache Cordova en dispositivos iOS, Android y Windows. Las plataformas compatibles con las siguientes:

• Android API 19+.
• Versiones 8.0 y posteriores de iOS.

Configuración y requisitos previos

En esta guía se asume que ha creado un back-end con una tabla. En los ejemplos se usa la tabla TodoItem de los inicios rápidos. Para agregar el complemento de Azure Mobile Apps al proyecto, use el siguiente comando:

cordova plugin add cordova-plugin-ms-azure-mobile-apps

Para más información sobre la creación de su primera aplicación de Apache Cordova, consulte su documentación.

Configuración de una aplicación de Ionic v2

Para configurar correctamente un proyecto de Ionic v2, primero cree una aplicación básica y agregue el complemento de Cordova:

ionic start projectName --v2
cd projectName
ionic plugin add cordova-plugin-ms-azure-mobile-apps

Agregue las siguientes líneas a app.component.ts para crear el objeto de cliente:

declare var WindowsAzure: any;
var client = new WindowsAzure.MobileServiceClient("https://yoursite.azurewebsites.net");

Ahora puede compilar y ejecutar el proyecto en el explorador:

ionic platform add browser
ionic run browser

El complemento de Cordova de Azure Mobile Apps es compatible con Ionic v1 y v2. Las aplicaciones de Ionic v2 son las únicas que requieren la declaración adicional del objeto WindowsAzure.

Creación de conexiones de cliente

Cree una conexión de cliente mediante la generación de un objeto WindowsAzure.MobileServiceClient . Sustituya appUrl por la dirección URL de la aplicación móvil.

var client = WindowsAzure.MobileServiceClient(appUrl);

Trabajar con tablas

Para acceder a los datos o actualizarlos, cree una referencia a la tabla de back-end. Reemplace tableName por el nombre de la tabla.

var table = client.getTable(tableName);

Una vez que disponga de una referencia de tabla, podrá realizar más operaciones con su tabla:

• Consulta de tablas
  • Filtrado de datos
  • Paginación mediante datos
  • Ordenación de datos
• Inserción de datos
• Modificación de datos
• Eliminación de datos

Consulta de una referencia de tabla

Una vez que tiene una referencia de tabla, puede utilizarla para consultar datos en el servidor. Las consultas se realizan en un lenguaje "similar a LINQ". Para devolver todos los datos de la tabla, utilice el código siguiente:

/**
 * Process the results that are received by a call to table.read()
 *
 * @param {Object} results the results as a pseudo-array
 * @param {int} results.length the length of the results array
 * @param {Object} results[] the individual results
 */
function success(results) {
   var numItemsRead = results.length;

   for (var i = 0 ; i < results.length ; i++) {
       var row = results[i];
       // Each row is an object - the properties are the columns
   }
}

function failure(error) {
    throw new Error('Error loading data: ', error);
}

table
    .read()
    .then(success, failure);

Se llama a la función success con los resultados. No use for (var i in results) en la función success, dado que se efectuaría una iteración en la información incluida en los resultados al utilizar otras funciones de consulta (como .includeTotalCount()).

Para más información sobre la sintaxis de Query, consulte la documentación del objeto Query.

Filtrado de datos en el servidor

Puede usar una cláusula where en la referencia de tabla:

table
    .where({ userId: user.userId, complete: false })
    .read()
    .then(success, failure);

También puede utilizar una función que filtre el objeto. En este caso, la variable this se asigna al objeto actual que se está filtrando. El siguiente código es funcionalmente equivalente al ejemplo anterior:

function filterByUserId(currentUserId) {
    return this.userId === currentUserId && this.complete === false;
}

table
    .where(filterByUserId, user.userId)
    .read()
    .then(success, failure);

Paginación mediante datos

Utilice los métodos take() y skip(). Por ejemplo, si desea dividir la tabla en registros de 100 filas:

var totalCount = 0, pages = 0;

// Step 1 - get the total number of records
table.includeTotalCount().take(0).read(function (results) {
    totalCount = results.totalCount;
    pages = Math.floor(totalCount/100) + 1;
    loadPage(0);
}, failure);

function loadPage(pageNum) {
    let skip = pageNum * 100;
    table.skip(skip).take(100).read(function (results) {
        for (var i = 0 ; i < results.length ; i++) {
            var row = results[i];
            // Process each row
        }
    }
}

El método .includeTotalCount() se utiliza para agregar un campo totalCount al objeto de resultados. El campo totalCount se rellena con el número total de registros que se devolverían si no se utilizara ninguna paginación.

A continuación, puede usar la variable de páginas y algunos botones de la interfaz de usuario para proporcionar una lista de páginas; utilice loadPage() para cargar los nuevos registros de cada página. Implemente el almacenamiento en caché para acelerar el acceso a los registros que ya se han cargado.

Devolución de los datos ordenados

Utilice los métodos de consulta .orderBy() o .orderByDescending():

table
    .orderBy('name')
    .read()
    .then(success, failure);

Para más información sobre el objeto Query, consulte la [documentación del objeto Query].

Insertar datos

Cree un objeto de JavaScript con la fecha adecuada y llame a table.insert() de manera asincrónica:

var newItem = {
    name: 'My Name',
    signupDate: new Date()
};

table
    .insert(newItem)
    .done(function (insertedItem) {
        var id = insertedItem.id;
    }, failure);

Tras la inserción correcta, el elemento insertado se devuelve con los campos adicionales que son necesarios para las operaciones de sincronización. Actualice su propia caché con esta información para actualizaciones posteriores.

El SDK del servidor de Node.js para Azure Mobile Apps admite el esquema dinámico con fines de desarrollo. El esquema dinámico permite agregar columnas a la tabla al especificarlas en una operación de inserción o actualización. Se recomienda desactivar el esquema dinámico antes de pasar la aplicación a producción.

Modificar datos

De forma similar al método .insert(), debe crear un objeto Update y luego llamar a .update(). El objeto Update debe contener el identificador del registro que se va a actualizar, que se obtiene al leer el registro o al llamar a .insert().

var updateItem = {
    id: '7163bc7a-70b2-4dde-98e9-8818969611bd',
    name: 'My New Name'
};

table
    .update(updateItem)
    .done(function (updatedItem) {
        // You can now update your cached copy
    }, failure);

Eliminar datos

Para eliminar un registro, llame al método .del(). Pase el identificador de una referencia de objeto:

table
    .del({ id: '7163bc7a-70b2-4dde-98e9-8818969611bd' })
    .done(function () {
        // Record is now deleted - update your cache
    }, failure);

Autenticar usuarios

Azure App Service es compatible con la autenticación y autorización de los usuarios de aplicaciones mediante diversos proveedores de identidades externos: Facebook, Google, Cuenta Microsoft y Twitter. Puede establecer permisos en tablas para restringir el acceso a operaciones específicas solo a usuarios autenticados. También puede usar la identidad de usuarios autenticados para implementar reglas de autorización en scripts del servidor. Para obtener más información, consulte el tutorial Introducción a la autenticación .

Al utilizar la autenticación en una aplicación de Apache Cordova, los siguientes complementos de Cordova deben estar disponibles:

• cordova-plugin-device
• cordova-plugin-inappbrowser

Se admiten dos flujos de autenticación: un flujo de servidor y un flujo de cliente. El flujo de servidor ofrece la experiencia de autenticación más simple, ya que se basa en la interfaz de autenticación web del proveedor. El flujo de cliente permite una mayor integración con capacidades específicas del dispositivo, como el inicio de sesión único, ya que se basa en SDK específicos del dispositivo y específicos del proveedor.

Autenticación con un proveedor (flujo de servidor)

Para que Mobile Apps administre el proceso de autenticación en su aplicación, debe registrar esta última en el proveedor de identidades. A continuación, en Azure App Service, tendrá que configurar el identificador y el secreto de la aplicación proporcionados por el proveedor. Para obtener más información, consulte el tutorial Incorporación de la autenticación a su aplicación.

Una vez que haya registrado el proveedor de identidades, simplemente llame al método .login() con el valor del proveedor. Por ejemplo, para iniciar sesión con Facebook, use el siguiente código:

client.login("facebook").done(function (results) {
     alert("You are now signed in as: " + results.userId);
}, function (err) {
     alert("Error: " + err);
});

Los valores válidos para el proveedor son "aad", "facebook", "google", "microsoftaccount" y "twitter".

En este caso, Azure App Service administra el flujo de autenticación de OAuth 2.0. Muestra la página de inicio de sesión del proveedor seleccionado y genera un token de autenticación de App Service después de iniciar sesión correctamente con el proveedor de identidades. La función login, cuando se completa, devuelve un objeto JSON que expone el identificador de usuario y el token de autenticación de App Service en los campos userId y authenticationToken, respectivamente. El token puede almacenarse en caché y volver a usarse hasta que expire.

Autenticación con un proveedor (flujo de cliente)

La aplicación también puede ponerse en contacto de manera independiente con el proveedor de identidades y proporcionar el token devuelto a App Service para la autenticación. Este flujo de cliente permite proporcionar una experiencia de inicio de sesión único a los usuarios o recuperar datos de usuario adicionales del proveedor de identidades.

Ejemplo básico de autenticación social

Este ejemplo usa el SDK de cliente de Facebook para la autenticación:

client.login("facebook", {"access_token": token})
.done(function (results) {
     alert("You are now signed in as: " + results.userId);
}, function (err) {
     alert("Error: " + err);
});

En este ejemplo se asume que el token proporcionado por el SDK del proveedor correspondiente se almacena en la variable token. Los detalles que requiere cada proveedor son ligeramente diferentes. Consulte la documentación de la autenticación y autorización de Azure App Service para determinar la forma exacta de la carga.

Obtención de información sobre el usuario autenticado

La información de autenticación se puede recuperar desde el punto de conexión /.auth/me mediante una llamada HTTP con cualquier biblioteca de HTTP/REST. Asegúrese de establecer el encabezado X-ZUMO-AUTH en el token de autenticación. El token de autenticación se almacena en client.currentUser.mobileServiceAuthenticationToken. Por ejemplo, para usar la API de captura:

var url = client.applicationUrl + '/.auth/me';
var headers = new Headers();
headers.append('X-ZUMO-AUTH', client.currentUser.mobileServiceAuthenticationToken);
fetch(url, { headers: headers })
    .then(function (data) {
        return data.json()
    }).then(function (user) {
        // The user object contains the claims for the authenticated user
    });

La captura está disponible como un paquete npm o para descarga desde el explorador desde CDNJS. Los datos se recibieron como un objeto JSON.

Cómo configurar su servicio de aplicaciones móviles para URL de redireccionamiento externas

Varios tipos de aplicaciones de Apache Cordova utilizan una función de bucle invertido para controlar los flujos de la interfaz de usuario de OAuth. Los flujos de interfaz de usuario de OAuth conllevan problemas, ya que el servicio de autenticación solo sabe cómo utilizar el servicio de manera predeterminada. Ejemplos de flujos de interfaz de usuario de OAuth problemáticos:

• El emulador Ripple
• La característica Live Reload con Ionic
• Ejecución del back-end móvil localmente
• Ejecución del back-end móvil en una instancia de Azure App Service diferente a la que proporciona la autenticación.

Siga estas instrucciones para agregar los ajustes locales a la configuración:

1. Inicie sesión en el Azure Portal

2. Seleccione Todos los recursos o App Services y haga clic en el nombre de la aplicación móvil.

3. Haga clic en Herramientas

4. Haga clic en la opción Explorador de recursos del menú OBSERVAR y, después, en Ir. Se abrirá una nueva ventana o pestaña.

5. Expanda los nodos config y authsettings de su sitio en el panel de navegación izquierdo.

6. Haga clic en Editar

7. Busque el elemento "allowedExternalRedirectUrls". Se puede establecer en Null o una matriz de valores. Cambie el valor al siguiente:

   "allowedExternalRedirectUrls": [
       "http://localhost:3000",
       "https://localhost:3000"
   ],
   

   Sustituya las URL por las de su servicio. Algunos ejemplos son "http://localhost:3000" (para el servicio de ejemplo de Node.js) o "http://localhost:4400" (para el servicio de Ripple). Sin embargo, estas URL no son más que ejemplos. Es decir, su situación puede ser distinta, incluso si debe configurar los servicios mencionados en los ejemplos.

8. Haga clic en el botón Lectura/escritura situado en la esquina superior derecha de la pantalla.

9. Haga clic en el botón verde PUT .

La configuración se guardará en este momento. No cierre la ventana del explorador hasta que la configuración haya terminado de guardarse. Agregue también estas URL de bucle invertido a la configuración de CORS:

1. Inicie sesión en el Azure Portal
2. Seleccione Todos los recursos o App Services y haga clic en el nombre de la aplicación móvil.
3. Se abrirá automáticamente la hoja Configuración. En caso contrario, haga clic en Toda la configuración.
4. Haga clic en la opción CORS del menú API.
5. Escriba la dirección URL que quiera agregar en el cuadro proporcionado y presione Intro.
6. Especifique más direcciones URL si fuera necesario.
7. Haga clic en Guardar para guardar la configuración.

Los nuevos ajustes tardarán aproximadamente entre 10 y 15 segundos en surtir efecto.