Como usar a biblioteca de cliente do Apache Cordova para os Aplicativos Móveis do AzureHow to use Apache Cordova client library for Azure Mobile Apps

Observação

Visual Studio App Center está investindo em novos e integrados serviços essenciais para o desenvolvimento de aplicativos móveis.Visual Studio App Center is investing in new and integrated services central to mobile app development. Os desenvolvedores podem usar construir, teste e distribuir services para configurar o pipeline de integração contínua e entrega.Developers can use Build, Test and Distribute services to set up Continuous Integration and Delivery pipeline. Depois que o aplicativo é implantado, os desenvolvedores podem monitorar o status e o uso do seu aplicativo usando o Analytics e diagnóstico serviços e entre em contato com usuários usando o enviar por Push serviço.Once the app is deployed, developers can monitor the status and usage of their app using the Analytics and Diagnostics services, and engage with users using the Push service. Os desenvolvedores também podem aproveitar Auth autenticar seus usuários e dados serviço para manter e sincronizar dados do aplicativo na nuvem.Developers can also leverage Auth to authenticate their users and Data service to persist and sync app data in the cloud. Fazer check-out App Center hoje mesmo.Check out App Center today.

Visão geralOverview

Este guia ensina a executar cenários comuns usando o mais recente Plug-in do Apache Cordova para os Aplicativos Móveis do Azure.This guide teaches you to perform common scenarios using the latest Apache Cordova Plugin for Azure Mobile Apps. Se você for novo nos Aplicativos Móveis do Azure, primeiro conclua o Início Rápido dos Aplicativos Móveis do Azure para criar um back-end, criar uma tabela e baixar um projeto Apache Cordova pré-criado.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. Neste guia, abordaremos o Plug-in do Apache Cordova do lado do cliente.In this guide, we focus on the client-side Apache Cordova Plugin.

Plataformas com suporteSupported platforms

Esse SDK dá suporte à versão 6.0.0 do Apache Cordova e posterior nos dispositivos iOS, Android e Windows.This SDK supports Apache Cordova v6.0.0 and later on iOS, Android, and Windows devices. O suporte de plataforma é o seguinte:The platform support is as follows:

  • API do Android 19 a 24 (KitKat usando Nougat).Android API 19-24 (KitKat through Nougat).
  • iOS versão 8.0 e posterior.iOS versions 8.0 and later.
  • Windows Phone 8.1.Windows Phone 8.1.
  • Plataforma Universal do Windows.Universal Windows Platform.

Configuração e pré-requisitosSetup and prerequisites

Este guia pressupõe que você tenha criado um back-end com uma tabela.This guide assumes that you have created a backend with a table. Este guia pressupõe que a tabela tem o mesmo esquema das tabelas desses tutoriais.This guide assumes that the table has the same schema as the tables in those tutorials. Este guia também pressupõe que você adicionou o Plug-in do Apache Cordova ao seu código.This guide also assumes that you have added the Apache Cordova Plugin to your code. Se você não tiver feito isso, poderá adicionar o plug-in do Apache Cordova ao seu projeto na linha de comando: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 saber mais sobre como criar seu primeiro aplicativo do Apache Cordova, consulte a documentação.For more information on creating your first Apache Cordova app, see their documentation.

Configurar um aplicativo Ionic v2Setting up an Ionic v2 app

Para configurar corretamente um projeto Ionic v2, primeiro crie um aplicativo básico e adicione o plug-in 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

Adicione as seguintes linhas a app.component.ts para criar o 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");

Agora, você pode criar e executar o projeto no navegador:You can now build and run the project in the browser:

ionic platform add browser
ionic run browser

O plug-in Cordova para Aplicativos Móveis do Azure dá suporte a aplicativos Ionic v1 e v2.The Azure Mobile Apps Cordova plugin supports both Ionic v1 and v2 apps. Somente os aplicativos Ionic v2 exigem a declaração adicional para o objeto WindowsAzure.Only the Ionic v2 apps require the additional declaration for the WindowsAzure object.

Criar uma conexão de clienteCreate a client connection

Crie uma conexão de cliente por meio da criação de um objeto WindowsAzure.MobileServiceClient .Create a client connection by creating a WindowsAzure.MobileServiceClient object. Substitua appUrl pela URL de seu Aplicativo Móvel.Replace appUrl with the URL to your Mobile App.

var client = WindowsAzure.MobileServiceClient(appUrl);

Trabalhar com tabelasWork with tables

Para acessar ou atualizar dados, crie uma referência à tabela de back-end.To access or update data, create a reference to the backend table. Substitua tableName pelo nome de sua tabelaReplace tableName with the name of your table

var table = client.getTable(tableName);

Depois que tiver uma referência de tabela, será possível trabalhar ainda mais com sua tabela:Once you have a table reference, you can work further with your table:

Como: Consultar uma referência de tabelaHow to: Query a table reference

Depois que você tiver uma referência de tabela, será possível usá-la para consultar dados no servidor.Once you have a table reference, you can use it to query for data on the server. As consultas são feitas em uma linguagem "parecida com LINQ".Queries are made in a "LINQ-like" language. Para retornar todos os dados da tabela, use o seguinte código: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);

A função de sucesso é chamada com os resultados.The success function is called with the results. Não use for (var i in results) na função de sucesso, pois isso causará a iteração de informações incluídas nos resultados quando outras funções de consulta (como .includeTotalCount()) forem usadas.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 obter mais informações sobre a sintaxe Query, confira a [documentação do objeto Query].For more information on the Query syntax, see the [Query object documentation].

Filtragem de dados no servidorFiltering data on the server

É possível usar uma cláusula where na referência de tabela:You can use a where clause on the table reference:

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

Você também pode usar uma função que filtra o objeto.You can also use a function that filters the object. Nesse caso, a variável this é atribuída ao objeto atual que está sendo filtrado.In this case, the this variable is assigned to the current object being filtered. O código a seguir é uma funcionalidade equivalente ao exemplo 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);

Paginando pelos dadosPaging through data

Utilize os métodos take() e skip().Utilize the take() and skip() methods. Por exemplo, se você quiser dividir a tabela em registros de 100 linhas: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
        }
    }
}

O método .includeTotalCount() é usado para adicionar um campo totalCount ao objeto de resultados.The .includeTotalCount() method is used to add a totalCount field to the results object. O campo totalCount é preenchido com o número total de registros que retornariam se nenhuma paginação fosse usada.The totalCount field is filled with the total number of records that would be returned if no paging is used.

Depois, você pode usar a variável de páginas e alguns botões da interface de usuário para fornecer uma lista de páginas; use loadPage() para carregar os novos 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 cache para agilizar o acesso a registros que já foram carregados.Implement caching to speed access to records that have already been loaded.

Como: Retornar dados classificadosHow to: Return sorted data

Use os métodos de consulta .orderBy() ou .orderByDescending():Use the .orderBy() or .orderByDescending() query methods:

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

Para obter mais informações sobre o objeto Query, confira a [documentação do objeto Query].For more information on the Query object, see the [Query object documentation].

Como: Inserir dadosHow to: Insert data

Crie um objeto JavaScript com a data adequada e chame table.insert() de maneira assíncrona: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);

Após a inserção bem-sucedida, o item inserido retorna com os campos adicionais necessários para as operações de sincronização.On successful insertion, the inserted item is returned with the additional fields that are required for sync operations. Atualize seu próprio cache com essas informações para atualizações posteriores.Update your own cache with this information for later updates.

O SDK de Node.js Server dos Aplicativos Móveis do Azure dá suporte ao esquema dinâmico para fins de desenvolvimento.The Azure Mobile Apps Node.js Server SDK supports dynamic schema for development purposes. O esquema Dinâmico permite que você adicione colunas à tabela, especificando-as em uma operação de inserção ou atualização.Dynamic Schema allows you to add columns to the table by specifying them in an insert or update operation. Recomendamos que você desative o esquema antes de mover seu aplicativo para produção.We recommend that you turn off dynamic schema before moving your application to production.

Como: Modificar dadosHow to: Modify data

Assim como o método .insert(), você deve criar um objeto de atualização e, em seguida, chamar .update().Similar to the .insert() method, you should create an Update object and then call .update(). O objeto de atualização deve conter a ID do registro a ser atualizada. Essa ID é obtida ao ler o registro ou ao chamar .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);

Como: Excluir dadosHow to: Delete data

Chame o método .del() para excluir um registro.To delete a record, call the .del() method. Passe a ID em uma referência 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);

Como: Autenticar usuáriosHow to: Authenticate users

O Serviço de Aplicativo do Azure dão suporte para autenticação e autorização de usuários de aplicativos usando variados provedores de identidade externos: Facebook, Google, conta da Microsoft e Twitter.Azure App Service supports authenticating and authorizing app users using various external identity providers: Facebook, Google, Microsoft Account, and Twitter. Você pode definir permissões em tabelas para restringir o acesso a operações específicas apenas para usuários autenticados.You can set permissions on tables to restrict access for specific operations to only authenticated users. Você também pode usar a identidade de usuários autenticados para implementar regras de autorização em scripts do servidor.You can also use the identity of authenticated users to implement authorization rules in server scripts. Para obter mais informações, consulte o tutorial Introdução à autenticação .For more information, see the Get started with authentication tutorial.

Ao usar a autenticação em um aplicativo Apache Cordova, os seguintes plugins Cordova devem estar disponíveis:When using authentication in an Apache Cordova app, the following Cordova plugins must be available:

Dois fluxos de autenticação são suportados: um server flow e um client flow.Two authentication flows are supported: a server flow and a client flow. O fluxo de servidor fornece a experiência de autenticação mais simples, pois depende da interface de autenticação da web do provedor.The server flow provides the simplest authentication experience, as it relies on the provider's web authentication interface. O fluxo de cliente permite uma integração mais profunda com recursos específicos do dispositivo, como logon único, uma vez que depende de provedores específicos e SDKs específicos do dispositivo.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.

Como: Autenticar com um provedor (fluxo de servidor)How to: Authenticate with a provider (Server Flow)

Para que os Aplicativos Móveis gerenciem o processo de autenticação em seu aplicativo, é necessário registrá-los no provedor de identidade.To have Mobile Apps manage the authentication process in your app, you must register your app with your identity provider. Em seguida, no Serviço de Aplicativo do Azure, você precisa configurar a ID e o segredo do aplicativo fornecidos por seu provedor.Then in your Azure App Service, you need to configure the application ID and secret provided by your provider. Para obter mais informações, consulte o tutorial Adicionar autenticação ao seu aplicativo.For more information, see the tutorial Add authentication to your app.

Depois de registrar seu provedor de identidade, chame o método .login() com o nome do seu provedor.Once you have registered your identity provider, call the .login() method with the name of your provider. Por exemplo, para entrar com o Facebook, use o código a seguir: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);
});

Os valores válidos para o provedor são 'add', 'facebook', 'google', 'microsoftaccount' e 'twitter'.The valid values for the provider are 'aad', 'facebook', 'google', 'microsoftaccount', and 'twitter'.

Observação

Atualmente, a Autenticação do Google não funciona por meio de Fluxo de Servidor.Google Authentication does not currently work via Server Flow. Para autenticar com o Google, você deve usar um método de fluxo de cliente.To authenticate with Google, you must use a client-flow method.

Nesse caso, o Serviço de Aplicativo do Azure gerencia o fluxo de autenticação OAuth 2.0.In this case, Azure App Service manages the OAuth 2.0 authentication flow. Ele exibe a página de logon do provedor selecionado e gera um token de autenticação do Serviço de Aplicativo após o logon bem-sucedido com o provedor de identidade.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. A função de logon, quando concluída, retorna um objeto JSON que expõe a ID do usuário e o token de autenticação do Serviço de Aplicativo nos campos userId e 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. Esse token pode ser armazenado em cache e reutilizado até que expire.This token can be cached and reused until it expires.

Como: Autenticar com um provedor (fluxo de servidor)How to: Authenticate with a provider (Client Flow)

Seu aplicativo também pode entrar em contato de forma independente com o provedor de identidade e fornecer o token retornado ao Serviço de Aplicativo para autenticação.Your app can also independently contact the identity provider and then provide the returned token to your App Service for authentication. Esse fluxo de cliente permite que você forneça uma experiência de logon único aos usuários ou recupere dados adicionais do usuário do provedor de identidade.This client flow enables you to provide a single sign-in experience for users or to retrieve additional user data from the identity provider.

Exemplo básico de autenticação socialSocial Authentication basic example

Este exemplo usa o SDK de cliente do Facebook para a autenticação: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);
});

Esse exemplo pressupõe que o token fornecido pelo respectivo SDK do provedor é armazenado na variável 'token'.This example assumes that the token provided by the respective provider SDK is stored in the token variable.

Como: Obter informações sobre o usuário autenticadoHow to: Obtain information about the authenticated user

As informações de autenticação podem ser obtidas no ponto de extremidade /.auth/me usando uma chamada HTTP com qualquer biblioteca do AJAX.The authentication information can be retrieved from the /.auth/me endpoint using an HTTP call with any AJAX library. Certifique-se de definir o cabeçalho X-ZUMO-AUTH ao token de autenticação.Ensure you set the X-ZUMO-AUTH header to your authentication token. O token de autenticação está armazenado em client.currentUser.mobileServiceAuthenticationToken.The authentication token is stored in client.currentUser.mobileServiceAuthenticationToken. Por exemplo, para usar a API de busca: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
    });

O Fetch está disponível como um pacote npm ou para download do navegador do CDNJS.Fetch is available as an npm package or for browser download from CDNJS. Você também pode usar jQuery ou outra API AJAX para buscar as informações.You could also use jQuery or another AJAX API to fetch the information. Os dados são recebidos como um objeto JSON.Data is received as a JSON object.

Como: Configurar o Serviço de Aplicativo Móvel para URLs de redirecionamento externo.How to: Configure your Mobile App Service for external redirect URLs.

Vários tipos de aplicativos do Apache Cordova usam uma funcionalidade de loopback para manipular fluxos de Interface do usuário do OAuth.Several types of Apache Cordova applications use a loopback capability to handle OAuth UI flows. Fluxos de interface do usuário OAuth causam problemas, pois o serviço de autenticação só sabe utilizar seu serviço por padrão.OAuth UI flows on localhost cause problems since the authentication service only knows how to utilize your service by default. Exemplos de fluxos de interface do usuário OAuth problemáticos incluem:Examples of problematic OAuth UI flows include:

  • O emulador Ripple.The Ripple emulator.
  • Recarregamento dinâmico com Ionic.Live Reload with Ionic.
  • Executando o back-end móvel localmenteRunning the mobile backend locally
  • A execução do back-end móvel em um Serviço de Aplicativo do Azure diferente que forneceu a autenticação.Running the mobile backend in a different Azure App Service than the one providing authentication.

Siga estas instruções para adicionar as definições locais à configuração:Follow these instructions to add your local settings to the configuration:

  1. Faça logon no Portal do AzureLog in to the Azure portal

  2. Selecione Todos os recursos ou Serviços de Aplicativos e clique no nome do Aplicativo Móvel.Select All resources or App Services then click the name of your Mobile App.

  3. Clique em FerramentasClick Tools

  4. Clique em Gerenciador de Recursos no menu OBSERVAR e clique em Ir.Click Resource explorer in the OBSERVE menu, then click Go. Uma nova janela ou guia é aberta.A new window or tab opens.

  5. Expanda os nós config, authsettings do seu site no painel de navegação esquerdo.Expand the config, authsettings nodes for your site in the left-hand navigation.

  6. Clique em EditarClick Edit

  7. Procure o elemento "allowedExternalRedirectUrls".Look for the "allowedExternalRedirectUrls" element. Ele pode ser definido como nulo ou uma matriz de valores.It may be set to null or an array of values. Altere o valor para o seguinte:Change the value to the following value:

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

    Substitua as URLs pelas URLs do seu serviço.Replace the URLs with the URLs of your service. Os exemplos incluem http://localhost:3000 (para o serviço de exemplo do Node. js), ou http://localhost:4400 (para o serviço Ripple).Examples include http://localhost:3000 (for the Node.js sample service), or http://localhost:4400 (for the Ripple service). No entanto, essas URLs são exemplos – sua situação, incluindo para os serviços mencionados nos exemplos, pode ser diferente.However, these URLs are examples - your situation, including for the services mentioned in the examples, may be different.

  8. Clique no botão Leitura/Gravação no canto superior direito da tela.Click the Read/Write button in the top-right corner of the screen.

  9. Clique no botão verde PUT .Click the green PUT button.

As configurações são salvas neste momento.The settings are saved at this point. Não feche a janela do navegador até que as configurações sejam salvas.Do not close the browser window until the settings have finished saving. Além disso, adicione essas URLs de loopback às configurações de CORS para o Serviço de Aplicativo:Also add these loopback URLs to the CORS settings for your App Service:

  1. Faça logon no Portal do AzureLog in to the Azure portal
  2. Selecione Todos os recursos ou Serviços de Aplicativos e clique no nome do Aplicativo Móvel.Select All resources or App Services then click the name of your Mobile App.
  3. A folha Configurações abre automaticamente.The Settings blade opens automatically. Se não for, clique em Todas as Configurações.If it doesn't, click All Settings.
  4. Clique em CORS no menu de API.Click CORS under the API menu.
  5. Digite a URL que você deseja adicionar na caixa fornecida e pressione Enter.Enter the URL that you wish to add in the box provided and press Enter.
  6. Insira URLs adicionais conforme necessário.Enter additional URLs as needed.
  7. Clique em Salvar para salvar as configurações.Click Save to save the settings.

É necessário cerca de 10 a 15 segundos para que as novas configurações tenham efeito.It takes approximately 10-15 seconds for the new settings to take effect.

Como: Registrar notificações por pushHow to: Register for push notifications

Instale o phonegap-plugin-push para manipular notificações por push.Install the phonegap-plugin-push to handle push notifications. Esse plug-in pode ser facilmente adicionado usando o comando cordova plugin add na linha de comando ou por meio do instalador de plug-ins do Git no 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. O código a seguir em seu aplicativo Apache Cordova registra seu dispositivo para notificações por 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 o SDK dos Hubs de Notificação para enviar notificações por push do servidor.Use the Notification Hubs SDK to send push notifications from the server. Nunca envie notificações por push diretamente dos clientes.Never send push notifications directly from clients. Isso pode ser usado para disparar um ataque de negação de serviço contra os Hubs de Notificação ou o PNS.Doing so could be used to trigger a denial of service attack against Notification Hubs or the PNS. O PNS pode proibir o tráfego como resultado desses ataques.The PNS could ban your traffic as a result of such attacks.

Mais informaçõesMore information

Você pode encontrar detalhes de API detalhadas em nossa Documentação da API.You can find detailed API details in our API documentation.