Uso de una biblioteca de cliente de Apache Cordova para Azure Mobile AppsHow to use Apache Cordova client library for Azure Mobile Apps

En esta guía se muestran algunos escenarios comunes del uso del último complemento de Apache Cordova para Azure Mobile Apps.This guide teaches you to perform common scenarios using the latest Apache Cordova Plugin for 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.If you are new to Azure Mobile Apps, first complete Azure Mobile Apps Quick Start to create a backend, create a table, and download a pre-built Apache Cordova project. En esta guía nos centramos en el complemento de Apache Cordova del lado cliente.In this guide, we focus on the client-side Apache Cordova Plugin.

Plataformas compatiblesSupported platforms

Este SDK es compatible con la versión 6.0.0 y posterior de Apache Cordova en dispositivos iOS, Android y Windows.This SDK supports Apache Cordova v6.0.0 and later on iOS, Android, and Windows devices. Las plataformas compatibles con las siguientes:The platform support is as follows:

  • Niveles de API de Android del 19 al 24 (de KitKat a Nougat)Android API 19-24 (KitKat through Nougat).
  • Versiones 8.0 y posteriores de iOS.iOS versions 8.0 and later.
  • Windows Phone 8.1Windows Phone 8.1.
  • Plataforma universal de WindowsUniversal Windows Platform.

Configuración y requisitos previosSetup and prerequisites

En esta guía se asume que ha creado un back-end con una tabla.This guide assumes that you have created a backend with a table. En esta guía se asume que la tabla tiene el mismo esquema que las tablas de dichos tutoriales.This guide assumes that the table has the same schema as the tables in those tutorials. En esta guía también se supone que ha agregado el complemento de Apache Cordova al código.This guide also assumes that you have added the Apache Cordova Plugin to your code. Si no lo ha hecho, puede agregar el complemento Apache Cordova al proyecto en la línea de comandos:If you have not done so, you may add the Apache Cordova plugin to your project on the command line:

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.For more information on creating your first Apache Cordova app, see their documentation.

Configuración de una aplicación de Ionic v2Setting up an Ionic v2 app

Para configurar correctamente un proyecto de Ionic v2, primero cree una aplicación básica y agregue el complemento de Cordova:To properly configure an Ionic v2 project, first create a basic app and add the Cordova plugin:

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:Add the following lines to app.component.ts to create the client object:

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

Ahora puede compilar y ejecutar el proyecto en el explorador:You can now build and run the project in the browser:

ionic platform add browser
ionic run browser

El complemento de Cordova de Azure Mobile Apps es compatible con Ionic v1 y v2.The Azure Mobile Apps Cordova plugin supports both Ionic v1 and v2 apps. Solo las aplicaciones de Ionic v2 requieren la declaración adicional para el objeto WindowsAzure.Only the Ionic v2 apps require the additional declaration for the WindowsAzure object.

Creación de conexiones de clienteCreate a client connection

Cree una conexión de cliente mediante la generación de un objeto WindowsAzure.MobileServiceClient .Create a client connection by creating a WindowsAzure.MobileServiceClient object. Sustituya appUrl por la dirección URL de la aplicación móvil.Replace appUrl with the URL to your Mobile App.

var client = WindowsAzure.MobileServiceClient(appUrl);

Trabajo con tablasWork with tables

Para acceder a los datos o actualizarlos, cree una referencia a la tabla de back-end.To access or update data, create a reference to the backend table. Reemplace tableName por el nombre de la tabla.Replace tableName with the name of your table

var table = client.getTable(tableName);

Una vez que disponga de una referencia de tabla, podrá realizar más operaciones con su tabla:Once you have a table reference, you can work further with your table:

Instrucciones: Consulta de una referencia de tablaHow to: Query a table reference

Una vez que tiene una referencia de tabla, puede utilizarla para consultar datos en el servidor.Once you have a table reference, you can use it to query for data on the server. Las consultas se realizan en un lenguaje "similar a LINQ".Queries are made in a "LINQ-like" language. Para devolver todos los datos de la tabla, utilice el código siguiente:To return all data from the table, use the following code:

/**
 * 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.The success function is called with the results. 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()).Do not use for (var i in results) in the success function as that will iterate over information that is included in the results when other query functions (such as .includeTotalCount()) are used.

Para más información sobre la sintaxis de Query, consulte la [documentación del objeto Query].For more information on the Query syntax, see the [Query object documentation].

Filtrado de datos en el servidorFiltering data on the server

Puede usar una cláusula where en la referencia de tabla:You can use a where clause on the table reference:

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

También puede utilizar una función que filtre el objeto.You can also use a function that filters the object. En este caso, la variable this se asigna al objeto actual que se está filtrando.In this case, the this variable is assigned to the current object being filtered. El siguiente código es funcionalmente equivalente al ejemplo anterior:The following code is functionally equivalent to the prior example:

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

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

Paginación mediante datosPaging through data

Utilice los métodos take() y skip().Utilize the take() and skip() methods. Por ejemplo, si desea dividir la tabla en registros de 100 filas:For example, if you wish to split the table into 100-row records:

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.The .includeTotalCount() method is used to add a totalCount field to the results object. El campo totalCount se rellena con el número total de registros que se devolverían si no se utilizara ninguna paginación.The totalCount field is filled with the total number of records that would be returned if no paging is used.

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.You can then use the pages variable and some UI buttons to provide a page list; use loadPage() to load the new records for each page. Implemente el almacenamiento en caché para acelerar el acceso a los registros que ya se han cargado.Implement caching to speed access to records that have already been loaded.

Instrucciones: Devolución de los datos ordenadosHow to: Return sorted data

Utilice los métodos de consulta .orderBy() o .orderByDescending():Use the .orderBy() or .orderByDescending() query methods:

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

Para más información sobre el objeto Query, consulte la [documentación del objeto Query].For more information on the Query object, see the [Query object documentation].

Instrucciones: Insertar datosHow to: Insert data

Cree un objeto de JavaScript con la fecha adecuada y llame a table.insert() de manera asincrónica:Create a JavaScript object with the appropriate date and call table.insert() asynchronously:

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.On successful insertion, the inserted item is returned with the additional fields that are required for sync operations. Actualice su propia caché con esta información para actualizaciones posteriores.Update your own cache with this information for later updates.

El SDK del servidor de Node.js para Azure Mobile Apps admite el esquema dinámico con fines de desarrollo.The Azure Mobile Apps Node.js Server SDK supports dynamic schema for development purposes. El esquema dinámico permite agregar columnas a la tabla al especificarlas en una operación de inserción o actualización.Dynamic Schema allows you to add columns to the table by specifying them in an insert or update operation. Se recomienda desactivar el esquema dinámico antes de pasar la aplicación a producción.We recommend that you turn off dynamic schema before moving your application to production.

Instrucciones: Modificación de los datosHow to: Modify data

De forma similar al método .insert(), debe crear un objeto Update y luego llamar a .update().Similar to the .insert() method, you should create an Update object and then call .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().The update object must contain the ID of the record to be updated - the ID is obtained when reading the record or when calling .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);

Instrucciones: Eliminar datosHow to: Delete data

Para eliminar un registro, llame al método .del().To delete a record, call the .del() method. Pase el identificador de una referencia de objeto:Pass the ID in an object reference:

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

Instrucciones: Autenticación de usuariosHow to: Authenticate users

Azure App Service admite la autenticación y autorización de usuarios de la aplicación que usan diversos proveedores de identidades externos: Facebook, Google, cuenta Microsoft y Twitter.Azure App Service supports authenticating and authorizing app users using various external identity providers: Facebook, Google, Microsoft Account, and Twitter. Puede establecer permisos en tablas para restringir el acceso a operaciones específicas solo a usuarios autenticados.You can set permissions on tables to restrict access for specific operations to only authenticated users. También puede usar la identidad de usuarios autenticados para implementar reglas de autorización en scripts del servidor.You can also use the identity of authenticated users to implement authorization rules in server scripts. Para obtener más información, consulte el tutorial Introducción a la autenticación .For more information, see the Get started with authentication tutorial.

Al utilizar la autenticación en una aplicación de Apache Cordova, los siguientes complementos de Cordova deben estar disponibles:When using authentication in an Apache Cordova app, the following Cordova plugins must be available:

Se admiten dos flujos de autenticación: un flujo de servidor y un flujo de cliente.Two authentication flows are supported: a server flow and a client flow. 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.The server flow provides the simplest authentication experience, as it relies on the provider's web authentication interface. 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.The client flow allows for deeper integration with device-specific capabilities such as single-sign-on as it relies on provider-specific device-specific SDKs.

Instrucciones: Autenticación con un proveedor (flujo de servidor)How to: Authenticate with a provider (Server Flow)

Para que Mobile Apps administre el proceso de autenticación en su aplicación, debe registrar esta última en el proveedor de identidades.To have Mobile Apps manage the authentication process in your app, you must register your app with your identity provider. A continuación, en Azure App Service, tendrá que configurar el identificador y el secreto de la aplicación proporcionados por el proveedor.Then in your Azure App Service, you need to configure the application ID and secret provided by your provider. Para obtener más información, consulte el tutorial Incorporación de la autenticación a su aplicación.For more information, see the tutorial Add authentication to your app.

Una vez que haya registrado el proveedor de identidades, simplemente llame al método .login() con el valor del proveedor.Once you have registered your identity provider, call the .login() method with the name of your provider. Por ejemplo, para iniciar sesión con Facebook, use el siguiente código:For example, to sign in with Facebook use the following code:

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".The valid values for the provider are 'aad', 'facebook', 'google', 'microsoftaccount', and 'twitter'.

Nota

Autenticación de Google no funciona actualmente a través del flujo de servidor.Google Authentication does not currently work via Server Flow. Para realizar la autenticación con Google, debe usar un método de flujo de cliente.To authenticate with Google, you must use a client-flow method.

En este caso, Azure App Service administra el flujo de autenticación de OAuth 2.0.In this case, Azure App Service manages the OAuth 2.0 authentication flow. 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.It displays the sign-in page of the selected provider and generates an App Service authentication token after successful sign-in with the identity provider. 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.The login function, when complete, returns a JSON object that exposes both the user ID and App Service authentication token in the userId and authenticationToken fields, respectively. El token puede almacenarse en caché y volver a usarse hasta que expire.This token can be cached and reused until it expires.

Instrucciones: Autenticación con un proveedor (flujo de cliente)How to: Authenticate with a provider (Client Flow)

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.Your app can also independently contact the identity provider and then provide the returned token to your App Service for authentication. Este flujo de cliente le permite proporcionar una experiencia de inicio de sesión único para los usuarios o recuperar datos de usuario adicionales del proveedor de identidades.This client flow enables you to provide a single sign-in experience for users or to retrieve additional user data from the identity provider.

Ejemplo básico de autenticación socialSocial Authentication basic example

Este ejemplo usa el SDK de cliente de Facebook para la autenticación:This example uses Facebook client SDK for authentication:

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.This example assumes that the token provided by the respective provider SDK is stored in the token variable.

Instrucciones: Obtención de información sobre el usuario autenticadoHow to: Obtain information about the authenticated user

Se puede recuperar la información de autenticación desde el punto de conexión /.auth/me mediante una llamada HTTP con cualquier biblioteca de AJAX.The authentication information can be retrieved from the /.auth/me endpoint using an HTTP call with any AJAX library. Asegúrese de establecer el encabezado X-ZUMO-AUTH en el token de autenticación.Ensure you set the X-ZUMO-AUTH header to your authentication token. El token de autenticación se almacena en client.currentUser.mobileServiceAuthenticationToken.The authentication token is stored in client.currentUser.mobileServiceAuthenticationToken. Por ejemplo, para usar la API de captura:For example, to use the fetch API:

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.Fetch is available as an npm package or for browser download from CDNJS. También podría utilizar jQuery u otra API de AJAX para capturar la información.You could also use jQuery or another AJAX API to fetch the information. Los datos se recibieron como un objeto JSON.Data is received as a JSON object.

Instrucciones: Cómo configurar su servicio de aplicaciones móviles para URL de redireccionamiento externasHow to: Configure your Mobile App Service for external redirect URLs.

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.Several types of Apache Cordova applications use a loopback capability to handle OAuth UI flows. 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.OAuth UI flows on localhost cause problems since the authentication service only knows how to utilize your service by default. Ejemplos de flujos de interfaz de usuario de OAuth problemáticos:Examples of problematic OAuth UI flows include:

  • El emulador RippleThe Ripple emulator.
  • La característica Live Reload con IonicLive Reload with Ionic.
  • Ejecución del back-end móvil localmenteRunning the mobile backend locally
  • Ejecución del back-end móvil en una instancia de Azure App Service diferente a la que proporciona la autenticación.Running the mobile backend in a different Azure App Service than the one providing authentication.

Siga estas instrucciones para agregar los ajustes locales a la configuración:Follow these instructions to add your local settings to the configuration:

  1. Inicie sesión en el Azure PortalLog in to the Azure portal

  2. Seleccione Todos los recursos o App Services y haga clic en el nombre de la aplicación móvil.Select All resources or App Services then click the name of your Mobile App.

  3. Haga clic en HerramientasClick Tools

  4. Haga clic en la opción Explorador de recursos del menú OBSERVAR y, después, en Ir.Click Resource explorer in the OBSERVE menu, then click Go. Se abrirá una nueva ventana o pestaña.A new window or tab opens.

  5. Expanda los nodos config y authsettings de su sitio en el panel de navegación izquierdo.Expand the config, authsettings nodes for your site in the left-hand navigation.

  6. Haga clic en EditarClick Edit

  7. Busque el elemento "allowedExternalRedirectUrls".Look for the "allowedExternalRedirectUrls" element. Se puede establecer en Null o una matriz de valores.It may be set to null or an array of values. Cambie el valor al siguiente:Change the value to the following value:

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

    Sustituya las URL por las de su servicio.Replace the URLs with the URLs of your service. Algunos ejemplos son http://localhost:3000 (para el servicio de ejemplo de Node.js), o http://localhost:4400 (para el servicio de Ripple).Examples include http://localhost:3000 (for the Node.js sample service), or http://localhost:4400 (for the Ripple service). 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.However, these URLs are examples - your situation, including for the services mentioned in the examples, may be different.

  8. Haga clic en el botón Lectura/escritura situado en la esquina superior derecha de la pantalla.Click the Read/Write button in the top-right corner of the screen.

  9. Haga clic en el botón verde PUT .Click the green PUT button.

La configuración se guardará en este momento.The settings are saved at this point. No cierre la ventana del explorador hasta que la configuración haya terminado de guardarse.Do not close the browser window until the settings have finished saving. Agregue también estas URL de bucle invertido a la configuración de CORS:Also add these loopback URLs to the CORS settings for your App Service:

  1. Inicie sesión en el Azure PortalLog in to the Azure portal
  2. Seleccione Todos los recursos o App Services y haga clic en el nombre de la aplicación móvil.Select All resources or App Services then click the name of your Mobile App.
  3. Se abrirá automáticamente la hoja Configuración.The Settings blade opens automatically. En caso contrario, haga clic en Toda la configuración.If it doesn't, click All Settings.
  4. Haga clic en la opción CORS del menú API.Click CORS under the API menu.
  5. Escriba la dirección URL que quiera agregar en el cuadro proporcionado y presione Intro.Enter the URL that you wish to add in the box provided and press Enter.
  6. Escriba las direcciones URL adicionales que necesite.Enter additional URLs as needed.
  7. Haga clic en Guardar para guardar la configuración.Click Save to save the settings.

Los nuevos ajustes tardarán aproximadamente entre 10 y 15 segundos en surtir efecto.It takes approximately 10-15 seconds for the new settings to take effect.

Instrucciones: Registro de notificaciones pushHow to: Register for push notifications

Instale phonegap-plugin-push para administrar las notificaciones push.Install the phonegap-plugin-push to handle push notifications. Este complemento se puede agregar fácilmente mediante el comando cordova plugin add en la línea de comandos o por medio del instalador de complementos Git dentro de Visual Studio.This plugin can be easily added using the cordova plugin add command on the command line, or via the Git plugin installer within Visual Studio. El siguiente código de la aplicación de Apache Cordova registrará el dispositivo para notificaciones push:The following code in your Apache Cordova app registers your device for push notifications:

var pushOptions = {
    android: {
        senderId: '<from-gcm-console>'
    },
    ios: {
        alert: true,
        badge: true,
        sound: true
    },
    windows: {
    }
};
pushHandler = PushNotification.init(pushOptions);

pushHandler.on('registration', function (data) {
    registrationId = data.registrationId;
    // For cross-platform, you can use the device plugin to determine the device
    // Best is to use device.platform
    var name = 'gcm'; // For android - default
    if (device.platform.toLowerCase() === 'ios')
        name = 'apns';
    if (device.platform.toLowerCase().substring(0, 3) === 'win')
        name = 'wns';
    client.push.register(name, registrationId);
});

pushHandler.on('notification', function (data) {
    // data is an object and is whatever is sent by the PNS - check the format
    // for your particular PNS
});

pushHandler.on('error', function (error) {
    // Handle errors
});

Use el SDK de Notification Hubs para enviar notificaciones push desde el servidor.Use the Notification Hubs SDK to send push notifications from the server. No envíe nunca notificaciones push directamente desde la aplicación,Never send push notifications directly from clients. ya que podría usarse para desencadenar un ataque de denegación de servicio en Notification Hubs o el PNS.Doing so could be used to trigger a denial of service attack against Notification Hubs or the PNS. El PNS puede prohibir el tráfico como resultado de estos ataques.The PNS could ban your traffic as a result of such attacks.

Más informaciónMore information

Puede encontrar información detallada sobre las API en nuestra documentación de la API.You can find detailed API details in our API documentation.