Como usar o plug-in do Apache Cordova para Aplicativos Móveis do Azure

Este guia ensina você a executar cenários comuns usando o plug-in Apache Cordova mais recente para aplicativos móveis do Azure. Se você for novo nos Aplicativos Móveis do Azure, primeiro conclua de Início Rápido dos Aplicativos Móveis do Azure para criar um back-end, criar uma tabela e baixar um projeto do Apache Cordova pré-criado. Neste guia, nos concentramos no Plug-in do Apache Cordova do lado do cliente.

Plataformas com suporte

Esse SDK dá suporte ao Apache Cordova v6.0.0 e posterior em dispositivos iOS, Android e Windows. O suporte à plataforma é o seguinte:

• API do Android 19+.
• IOS versões 8.0 e posteriores.

Configuração e pré-requisitos

Este guia pressupõe que você criou um back-end com uma tabela. Os exemplos usam a tabela TodoItem dos inícios rápidos. Para adicionar o plug-in dos Aplicativos Móveis do Azure ao seu projeto, use o seguinte comando:

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

Para obter mais informações sobre como criar seu primeiro aplicativo Apache Cordova, consulte a documentação.

Configurando um aplicativo Ionic v2

Para configurar corretamente um projeto Ionic v2, primeiro crie um aplicativo básico e adicione o plug-in Cordova:

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 cliente:

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

Agora você pode compilar e executar o projeto no navegador:

ionic platform add browser
ionic run browser

O plug-in cordova dos Aplicativos Móveis do Azure dá suporte a aplicativos Ionic v1 e v2. Somente os aplicativos Ionic v2 exigem a declaração extra para o objeto WindowsAzure.

Criar uma conexão de cliente

Crie uma conexão de cliente criando um objeto WindowsAzure.MobileServiceClient. Substitua appUrl pela URL do aplicativo móvel.

var client = WindowsAzure.MobileServiceClient(appUrl);

Trabalhar com tabelas

Para acessar ou atualizar dados, crie uma referência à tabela de back-end. Substitua tableName pelo nome da tabela

var table = client.getTable(tableName);

Depois de ter uma referência de tabela, você poderá trabalhar ainda mais com sua tabela:

• consultar uma tabela
  • filtragem de dados
  • paginação por meio de de dados
  • classificação de dados
• inserir de dados
• modificando de dados
• excluindo de dados

Consultar uma referência de tabela

Depois de ter uma referência de tabela, você poderá usá-la para consultar dados no servidor. As consultas são feitas em uma linguagem "semelhante a LINQ". Para retornar todos os dados da tabela, use o seguinte código:

/**
 * 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. Não use for (var i in results) na função de êxito, pois isso iterará sobre informações incluídas nos resultados quando outras funções de consulta (como .includeTotalCount()) forem usadas.

Para obter mais informações sobre a sintaxe de consulta, consulte a documentação do objeto Query.

Filtrando dados no servidor

Você pode usar uma cláusula where na referência da tabela:

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

Você também pode usar uma função que filtra o objeto. Nesse caso, a variável this é atribuída ao objeto atual que está sendo filtrado. O código a seguir é funcionalmente equivalente ao exemplo anterior:

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

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

Paginação por meio de dados

Utilize os métodos take() e skip(). Por exemplo, se você quiser dividir a tabela em registros de 100 linhas:

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. O campo totalCount é preenchido com o número total de registros que seriam retornados se nenhuma paginação for usada.

Em seguida, você pode usar a variável de páginas e alguns botões de interface do usuário para fornecer uma lista de páginas; use loadPage() para carregar os novos registros para cada página. Implemente o cache para acelerar o acesso aos registros que já foram carregados.

Retornar dados classificados

Use os métodos de consulta .orderBy() ou .orderByDescending():

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

Para obter mais informações sobre o objeto Query, consulte a [documentação do objeto Query].

Inserir dados

Crie um objeto JavaScript com a data e a chamada apropriadas table.insert() de forma assíncrona:

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

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

Na inserção bem-sucedida, o item inserido é retornado com campos extras necessários para operações de sincronização. Atualize seu próprio cache com essas informações para atualizações posteriores.

O SDK do Servidor Node.js aplicativos móveis do Azure dá suporte ao esquema dinâmico para fins de desenvolvimento. O Esquema Dinâmico permite adicionar colunas à tabela especificando-as em uma operação de inserção ou atualização. Recomendamos desativar o esquema dinâmico antes de mover seu aplicativo para produção.

Modificar dados

Semelhante ao método .insert(), você deve criar um objeto Update e, em seguida, chamar .update(). O objeto de atualização deve conter a ID do registro a ser atualizado – a ID é obtida ao ler o registro ou ao chamar .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);

Excluir dados

Para excluir um registro, chame o método .del(). Passe a ID em uma referência de objeto:

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

Autenticar usuários

O Serviço de Aplicativo do Azure dá suporte à autenticação e autorização de usuários de aplicativos usando vários provedores de identidade externos: Facebook, Google, Conta da Microsoft e Twitter. Você pode definir permissões em tabelas para restringir o acesso a operações específicas somente para usuários autenticados. Você também pode usar a identidade de usuários autenticados para implementar regras de autorização em scripts de servidor. Para obter mais informações, consulte o tutorial Introdução à autenticação.

Ao usar a autenticação em um aplicativo Apache Cordova, os seguintes plug-ins cordova devem estar disponíveis:

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

Há suporte para dois fluxos de autenticação: um fluxo de servidor e um fluxo de cliente. O fluxo do servidor fornece a experiência de autenticação mais simples, pois depende da interface de autenticação da Web do provedor. O fluxo do cliente permite uma integração mais profunda com recursos específicos do dispositivo, como logon único, pois depende de SDKs específicos do dispositivo específicos do provedor.

Autenticar com um provedor (Fluxo do Servidor)

Para que os Aplicativos Móveis gerenciem o processo de autenticação em seu aplicativo, você deve registrar seu aplicativo com seu provedor de identidade. Em seguida, no Serviço de Aplicativo do Azure, você precisa configurar a ID do aplicativo e o segredo fornecidos pelo seu provedor. Para obter mais informações, consulte o tutorial Adicionar autenticação ao aplicativo.

Depois de registrar seu provedor de identidade, chame o método .login() com o nome do seu provedor. Por exemplo, para entrar com o Facebook, use o seguinte código:

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 'aad', 'facebook', 'google', 'microsoftaccount' e 'twitter'.

Nesse caso, o Serviço de Aplicativo do Azure gerencia o fluxo de autenticação do OAuth 2.0. Ele exibe a página de entrada do provedor selecionado e gera um token de autenticação do Serviço de Aplicativo após a entrada bem-sucedida com o provedor de identidade. 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. Esse token pode ser armazenado em cache e reutilizado até expirar.

Autenticar com um provedor (Fluxo do Cliente)

Seu aplicativo também pode entrar em contato independentemente com o provedor de identidade e, em seguida, fornecer o token retornado ao Serviço de Aplicativo para autenticação. Esse fluxo de cliente permite que você forneça uma única experiência de entrada para os usuários ou recupere dados extras do usuário do provedor de identidade.

Exemplo básico de Autenticação Social

Este exemplo usa o SDK do cliente do Facebook para autenticação:

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

Este exemplo pressupõe que o token fornecido pelo respectivo SDK do provedor seja armazenado na variável de token. Os detalhes exigidos por cada provedor são ligeiramente diferentes. Consulte a documentação autenticação e autorização do Serviço de Aplicativo do Azure para determinar a forma exata do conteúdo.

Obter informações sobre o usuário autenticado

As informações de autenticação podem ser recuperadas do ponto de extremidade /.auth/me usando uma chamada HTTP com qualquer biblioteca HTTP/REST. Certifique-se de definir o cabeçalho X-ZUMO-AUTH para o token de autenticação. O token de autenticação é armazenado em client.currentUser.mobileServiceAuthenticationToken. Por exemplo, para usar a API de busca:

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
    });

Fetch está disponível como um pacote npm ou para download do navegador de cdnjs. Os dados são recebidos como um objeto JSON.

Configure seu Serviço de Aplicativo Móvel para URLs de redirecionamento externo.

Vários tipos de aplicativos Apache Cordova usam uma funcionalidade de loopback para lidar com fluxos de interface do usuário do OAuth. Os fluxos de interface do usuário do OAuth no localhost causam problemas, pois o serviço de autenticação só sabe como utilizar seu serviço por padrão. Exemplos de fluxos problemáticos da interface do usuário do OAuth incluem:

• O emulador de Ondulação.
• Recarregar ao vivo com Ionic.
• Executando o back-end móvel localmente
• Executando o back-end móvel em um Serviço de Aplicativo do Azure diferente daquela que fornece autenticação.

Siga estas instruções para adicionar suas configurações locais à configuração:

1. Faça logon no portal do Azure

2. Selecione Todos os recursos ou Serviços de Aplicativo em seguida, clique no nome do aplicativo móvel.

3. Clique em ferramentas de

4. Clique do Gerenciador de Recursos no menu OBSERVE e clique em Ir. Uma nova janela ou guia é aberta.

5. Expanda o de configuração, authsettings nós para seu site na navegação à esquerda.

6. Clique em Editar

7. Procure o elemento "allowedExternalRedirectUrls". Ele pode ser definido como nulo ou uma matriz de valores. Altere o valor para o seguinte valor:

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

   Substitua as URLs pelas URLs do serviço. Exemplos incluem http://localhost:3000 (para o serviço de exemplo Node.js) ou http://localhost:4400 (para o serviço Ripple). No entanto, essas URLs são exemplos – sua situação, inclusive para os serviços mencionados nos exemplos, pode ser diferente.

8. Clique no botão de Leitura/Gravação no canto superior direito da tela.

9. Clique no botão PUT do verde.

As configurações são salvas neste momento. Não feche a janela do navegador até que as configurações tenham terminado de salvar. Adicione também essas URLs de loopback às configurações do CORS para o Serviço de Aplicativo:

1. Faça logon no portal do Azure
2. Selecione Todos os recursos ou Serviços de Aplicativo em seguida, clique no nome do aplicativo móvel.
3. A folha Configurações é aberta automaticamente. Caso contrário, clique em Todas as Configurações.
4. Clique em CORS no menu de API.
5. Insira a URL que você deseja adicionar na caixa fornecida e pressione Enter.
6. Insira mais URLs conforme necessário.
7. Clique em Salvar para salvar as configurações.

Leva aproximadamente de 10 a 15 segundos para que as novas configurações entrem em vigor.