Como usar a biblioteca de cliente JavaScript para os Aplicativos Móveis do Azure
Visão geral
Este guia ensina a executar cenários comuns usando o mais recente SDK do JavaScript para os Aplicativos Móveis do Azure. Se não estiver familiarizado com os Aplicativos Móveis do Azure, primeiro conclua o Início Rápido dos Aplicativos Móveis do Azure para criar um back-end e uma tabela. Neste guia, vamos nos concentrar no uso do back-end móvel em aplicativos Web em HTML/JavaScript.
Plataformas com Suporte
Limitamos o suporte de navegador às versões atuais e mais recentes dos principais navegadores: Google Chrome, Microsoft Edge, Microsoft Internet Explorer e Mozilla Firefox. Esperamos que o SDK funcione com todos os navegadores relativamente modernos.
O pacote é distribuído como um Módulo de JavaScript Universal e, portanto, ele dá suporte aos formatos AMD, CommonJS e globais.
Configuração e pré-requisitos
Este guia pressupõe que você tenha criado um back-end com uma tabela. Este guia pressupõe que a tabela tem o mesmo esquema das tabelas desses tutoriais.
A instalação do SDK do JavaScript para Aplicativos Móveis do Azure pode ser feita por meio do comando npm :
npm install azure-mobile-apps-client --save
A biblioteca também pode ser usada como um módulo ES2015, em ambientes de CommonJS como Browserify e Webpack e como uma biblioteca AMD. Por exemplo:
// For ECMAScript 5.1 CommonJS
var WindowsAzure = require('azure-mobile-apps-client');
// For ES2015 modules
import * as WindowsAzure from 'azure-mobile-apps-client';
Você também pode usar uma versão pré-criada do SDK baixando diretamente do nosso CDN:
<script src="https://zumo.blob.core.windows.net/sdk/azure-mobile-apps-client.min.js"></script>
Criar uma conexão de cliente
Crie uma conexão de cliente por meio da criação de um objeto WindowsAzure.MobileServiceClient . Substitua appUrl pela URL de seu 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 sua tabela
var table = client.getTable(tableName);
Depois que tiver uma referência de tabela, será possível trabalhar ainda mais com sua tabela:
Como consultar uma referência de tabela
Depois que você tiver uma referência de tabela, será possível usá-la para consultar dados no servidor. As consultas são feitas em uma linguagem "parecida com 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 sucesso, pois isso causará a iteração de informações incluídas nos resultados quando outras funções de consulta (como .includeTotalCount()) forem usadas.
Para obter mais informações sobre a sintaxe Query, confira a [documentação do objeto Query].
Filtragem de dados no servidor
É possível usar uma cláusula where na referência de 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 é uma funcionalidade equivalente ao exemplo anterior:
function filterByUserId(currentUserId) {
return this.userId === currentUserId && this.complete === false;
}
table
.where(filterByUserId, user.userId)
.read()
.then(success, failure);
Paginando pelos 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 retornariam se nenhuma paginação fosse usada.
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. Implemente cache para agilizar o acesso a registros que já foram carregados.
Como: 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, confira a [documentação do objeto Query].
Como inserir dados
Crie um objeto JavaScript com a data adequada e chame table.insert() de maneira assíncrona:
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. Atualize seu próprio cache com essas informações para atualizações posteriores.
O SDK de Node.js Server dos Aplicativos Móveis do Azure dá suporte ao esquema dinâmico para fins de desenvolvimento. O esquema Dinâmico permite que você adicione colunas à tabela, especificando-as em uma operação de inserção ou atualização. Recomendamos que você desative o esquema antes de mover seu aplicativo para produção.
Como modificar dados
Assim como o método .insert(), você deve criar um objeto de atualização e, em seguida, chamar .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().
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 dados
Chame o método .del() para excluir um registro. 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);
Como autenticar usuários
O Serviço de Aplicativo do Azure oferece 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 apenas para usuários autenticados. Você também pode usar a identidade de usuários autenticados para implementar regras de autorização em scripts do servidor. Para obter mais informações, consulte o tutorial Introdução à autenticação .
Dois fluxos de autenticação são suportados: um server flow e um 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. O fluxo de cliente permite uma integração mais profunda com funcionalidades específicas do dispositivo, como logon único, uma vez que depende de SDKs específicos do provedor.
Como autenticar com um provedor (fluxo de servidor)
Para que os Aplicativos Móveis gerenciem o processo de autenticação em seu aplicativo, é necessário registrá-los no provedor de identidade. Em seguida, no Serviço de Aplicativo do Azure, você precisa configurar a ID e o segredo do aplicativo fornecidos por seu provedor. Para obter mais informações, consulte o tutorial Adicionar autenticação ao seu 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 código a seguir:
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'.
Observação
Atualmente, a Autenticação do Google não funciona por meio de Fluxo de Servidor. Para autenticar com o Google, você deve usar um método de fluxo de cliente.
Nesse caso, o Serviço de Aplicativo do Azure gerencia o fluxo de autenticação OAuth 2.0. 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. 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é que expire.
Como autenticar com um provedor (fluxo de cliente)
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. 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.
Exemplo básico de autenticação social
Este exemplo usa o SDK de cliente do Facebook para a 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);
});
Esse exemplo pressupõe que o token fornecido pelo respectivo SDK do provedor é armazenado na variável 'token'.
Como obter informações sobre o usuário autenticado
As informações de autenticação podem ser obtidas no ponto de extremidade /.auth/me usando uma chamada HTTP com qualquer biblioteca do AJAX. Certifique-se de definir o cabeçalho X-ZUMO-AUTH ao token de autenticação. O token de autenticação está 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
});
O Fetch está disponível como um pacote npm ou para download do navegador do CDNJS. Você também pode usar jQuery ou outra API AJAX para buscar as informações. Os dados são recebidos como um objeto JSON.
Como configurar sua Serviço de Aplicativo Móvel para URLs de redirecionamento externo.
Vários tipos de aplicativo JavaScript usam uma funcionalidade de loopback para manipular fluxos de interface do usuário do OAuth. Esses recursos incluem:
- Executar o serviço localmente
- Usar o Live Reload com o Ionic Framework
- Redirecionar para o Serviço de Aplicativo para autenticação.
A execução local pode causar problemas porque, por padrão, a autenticação de Serviço de Aplicativo só está configurada para permitir o acesso do back-end do Aplicativo Móvel. Use as seguintes etapas para alterar as configurações de Serviço de Aplicativo de modo a habilitar a autenticação ao executar o servidor localmente:
Faça logon no Portal do Azure
Navegue até o back-end do Aplicativo Móvel.
Escolha Gerenciador de recursos no menu FERRAMENTAS DE DESENVOLVIMENTO.
Clique em Ir para abrir o gerenciador de recursos para o back-end do Aplicativo Móvel em uma nova janela ou guia.
Expanda o nó de configuração>authsettings para seu aplicativo.
Clique no botão Editar para habilitar a edição do recurso.
Encontre o elemento allowedExternalRedirectUrls , que deve ser nulo. Adicione as URLs em uma matriz:
"allowedExternalRedirectUrls": [ "https://localhost:3000", "https://localhost:3000" ],Substitua as URLs na matriz pelas URLs do serviço, que neste exemplo é
https://localhost:3000para o serviço local de exemplo do Node.js. Você também pode usarhttps://localhost:4400para o serviço Ripple ou alguma outra URL, dependendo de como seu aplicativo é configurado.Na parte superior da página, clique em Leitura/Gravação e clique em PUT para salvar as atualizações.
Você também precisa adicionar as mesmas URLs de loopback às configurações da lista de permitidos do CORS:
- Navegue até o Portal do Azure.
- Navegue até o back-end do Aplicativo Móvel.
- Clique em CORS no menu API.
- Insira cada URL na caixa de texto Origens Permitidas vazia. Uma nova caixa de texto é criada.
- Clique em SALVAR
Após a atualização do back-end, você poderá usar as novas URLs de loopback em seu aplicativo.