Como utilizar a biblioteca de clientes Apache Cordova para aplicações móveis Azure
Descrição Geral
Este guia ensina-o a realizar cenários comuns utilizando o mais recente Apache Cordova Plugin para aplicações móveis Azure. Se é novo em Azure Mobile Apps, primeiro complete o Azure Mobile Apps Quick Start para criar um backend, criar uma mesa e descarregar um projeto Apache Cordova pré-construído. Neste guia, focamo-nos no Apache Cordova Plugin do lado do cliente.
Plataformas suportadas
Este SDK suporta Apache Cordova v6.0.0 e mais tarde em dispositivos iOS, Android e Windows. O suporte da plataforma é o seguinte:
- Android API 19-24 (KitKat através de Nougat).
- versões iOS 8.0 e posterior.
- Windows Phone 8.1.
- Plataforma Universal do Windows.
Configuração e pré-requisitos
Este guia assume que criou um backend com uma mesa. Este guia assume que a mesa tem o mesmo esquema que as mesas nesses tutoriais. Este guia também assume que adicionou o Apache Cordova Plugin ao seu código. Caso não o tenha feito, poderá adicionar o plugin Apache Cordova ao seu projeto na linha de comando:
cordova plugin add cordova-plugin-ms-azure-mobile-apps
Para obter mais informações sobre a criação da sua primeira aplicação Apache Cordova, consulte a sua documentação.
Criação de uma aplicação V2 Ionic
Para configurar adequadamente um projeto V2 Ionic, primeiro crie uma aplicação básica e adicione o plugin Cordova:
ionic start projectName --v2
cd projectName
ionic plugin add cordova-plugin-ms-azure-mobile-apps
Adicione as seguintes linhas para app.component.ts criar o objeto cliente:
declare var WindowsAzure: any;
var client = new WindowsAzure.MobileServiceClient("https://yoursite.azurewebsites.net");
Agora pode construir e executar o projeto no navegador:
ionic platform add browser
ionic run browser
O plugin Azure Mobile Apps Cordova suporta aplicações Ionic v1 e v2. Apenas as aplicações Ionic v2 requerem a declaração adicional para o WindowsAzure objeto.
Criar uma ligação de cliente
Criar uma ligação de cliente através da criação de um objeto WindowsAzure.MobileServiceClient. Substitua appUrl pelo URL da sua Aplicação Móvel.
var client = WindowsAzure.MobileServiceClient(appUrl);
Trabalhar com tabelas
Para atualizar ou aceder a dados, crie uma referência para a tabela de back-end. Substitua tableName pelo nome da sua tabela
var table = client.getTable(tableName);
Assim que tiver uma referência da tabela, pode trabalhar mais com a mesma:
Como: consultar uma referência de tabela
Assim que tiver uma referência de tabela, pode utilizá-la para consultar os dados no servidor. As consultas são efetuadas num idioma "tipo LINQ". Para devolver todos os dados da tabela, utilize 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 êxito é chamada com os resultados. Não utilize for (var i in results) na função de sucesso, uma vez que irá iterar sobre informações que estão incluídas nos resultados quando são utilizadas outras funções de consulta (como .includeTotalCount()).
Para obter mais informações sobre a Sintaxe da consulta, consulte a [Documentação de objeto de consulta].
Filtrar dados no servidor
Pode utilizar uma cláusula where na referência de tabela:
table
.where({ userId: user.userId, complete: false })
.read()
.then(success, failure);
Também pode utilizar uma função que filtra o objeto. Neste caso, a variável this é atribuída ao objeto atual a ser filtrado. O código seguinte é funcionalmente equivalente ao exemplo anterior:
function filterByUserId(currentUserId) {
return this.userId === currentUserId && this.complete === false;
}
table
.where(filterByUserId, user.userId)
.read()
.then(success, failure);
Paging através de dados
Utilize os métodos take() e skip(). Por exemplo, se pretender dividir a tabela em registos 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() é utilizado para adicionar um campo totalCount para o objeto de resultados. O campo totalCount é preenchido com o número total de registos que seria devolvido se a paginação não fosse utilizada.
Em seguida, pode utilizar a variável de páginas e alguns botões da IU para fornecer uma lista de páginas; utilize loadPage() para carregar os registos novos para cada página. Implemente a colocação em cache para acelerar o acesso aos registos que já foram carregados.
Como: devolver dados ordenados
Utilize os métodos de consulta .orderBy() ou .orderByDescending():
table
.orderBy('name')
.read()
.then(success, failure);
Para obter mais informações sobre o Objeto da consulta, consulte a [Documentação de objeto de consulta].
Como: inserir dados
Crie um objeto de JavaScript com a data adequada e chame table.insert() assincronamente:
var newItem = {
name: 'My Name',
signupDate: new Date()
};
table
.insert(newItem)
.done(function (insertedItem) {
var id = insertedItem.id;
}, failure);
Ao inserir com êxito, o item inserido é devolvido com os campos adicionais que são necessários para operações de sincronização. Atualize a sua própria cache com estas informações para atualizações posteriores.
O SDK do Servidor Node.js das Aplicações Móveis do Azure suporta um esquema dinâmica para fins de desenvolvimento. O Esquema Dinâmico permite-lhe adicionar colunas à tabela, especificando-as numa operação de inserção ou atualização. Recomendamos que desative o esquema dinâmico antes de mover a sua aplicação para produção.
Como: modificar dados
De forma semelhante ao método .insert(), deve criar um Objeto de atualização e, em seguida, chamar .update(). O objeto de atualização tem de conter o ID do registo a ser atualizado - o ID é obtido ao ler o registo ou quando 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: eliminar dados
Para eliminar um registo, chame o método .del(). Introduza o ID numa referência de objeto:
table
.del({ id: '7163bc7a-70b2-4dde-98e9-8818969611bd' })
.done(function () {
// Record is now deleted - update your cache
}, failure);
Como: Autenticar os utilizadores
Serviço de Aplicações do Azure suporta a autenticação e a autorização de utilizadores de aplicações utilizando vários fornecedores de identidade externas: Facebook, Google, Microsoft Account e Twitter. Pode definir permissões em tabelas para restringir o acesso a operações específicas apenas a utilizadores autenticados. Também pode utilizar a identidade dos utilizadores autenticados para implementar regras de autorização em scripts de servidores. Para mais informações, consulte a Introdução com tutoria de autenticação.
Ao utilizar a autenticação numa aplicação Apache Cordova, devem estar disponíveis os seguintes plugins Cordova:
Dois fluxos de autenticação são suportados: um fluxo de servidor e um fluxo de cliente. O fluxo do servidor proporciona a experiência de autenticação mais simples, uma vez que se baseia na interface de autenticação web do fornecedor. O fluxo do cliente permite uma integração mais profunda com capacidades específicas do dispositivo, tais como um único sign-on, uma vez que se baseia em SDKs específicos do fornecedor.
Como: autenticar com um fornecedor (Fluxo de Servidor)
Para que as Aplicações Móveis giram o processo de autenticação na sua aplicação, tem de registar a aplicação com o seu fornecedor de identidade. Em seguida, no seu Serviço de Aplicações do Azure, tem de configurar o ID da aplicação e o segredo fornecidos pelo seu fornecedor. Para obter mais informações, consulte o tutorial Add authentication to your app (Adicionar autenticação à sua aplicação).
Depois de registar o seu fornecedor de identidade, chame o método .login() com o nome do fornecedor. Por exemplo, para iniciar sind insuição no Facebook utilize 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 fornecedor são "aad", "facebook", "google", "microsoftaccount" e "twitter".
Nota
A Autenticação da Google não funciona atualmente através do Fluxo de Servidor. Para se autenticar com o Google, tem de utilizar um método de fluxo de cliente.
Neste caso, o Serviço de Aplicações do Azure gere o fluxo de autenticação OAuth 2.0. Apresenta a página de inscrição do fornecedor selecionado e gera um token de autenticação Serviço de Aplicações após o sucesso da sposição com o fornecedor de identidade. A função de início de sessão, quando concluída, devolve um objeto JSON que expõe o ID de utilizador e o token de autenticação do Serviço de Aplicações nos campos userId e authenticationToken, respetivamente. Este token pode ser colocado em cache e reutilizado até expirar.
Como: autenticar com um fornecedor (Fluxo de Cliente)
A sua aplicação também pode contactar o fornecedor de identidade independentemente e, em seguida, fornecer o token devolvido ao seu Serviço de Aplicações para autenticação. Este fluxo de cliente permite-lhe fornecer uma experiência de início de sessão único para os utilizadores ou para obter dados de utilizador adicionais do fornecedor de identidade.
Exemplo básico de Autenticação nas Redes Sociais
Este exemplo utiliza o SDK 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 assume que o token fornecido pelo SDK do fornecedor respetivo é armazenado na variável do token.
Como: obter informações sobre o utilizador autenticado
As informações de autenticação podem ser obtidas a partir do ponto final /.auth/me, ao utilizar uma chamada HTTP com qualquer biblioteca de AJAX. Certifique-se de que definiu o cabeçalho X-ZUMO-AUTH para o token de autenticação. O token de autenticação é armazenado no client.currentUser.mobileServiceAuthenticationToken. Por exemplo, para utilizar a API de obtenção:
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
});
A obtenção está disponível como um pacote de npm ou para transferência de browser a partir do CDNJS. Pode também utilizar jQuery ou outra API de AJAX para obter as informações. Os dados são recebidos como um objeto JSON.
Como: Configurar o seu Serviço de Aplicações móvel para URLs de redirecionamento externo.
Vários tipos de aplicações Apache Cordova usam uma capacidade de backback para lidar com fluxos OAuth UI. Os fluxos de UI da OAuth na localidade causam problemas, uma vez que o serviço de autenticação só sabe como utilizar o seu serviço por padrão. Exemplos de fluxos problemáticos de UI da OAuth incluem:
- O emulador de ondulação.
- Recarga ao vivo com iónico.
- Executando o backend móvel localmente
- Executar o backend móvel num Serviço de Aplicações do Azure diferente daquele que fornece autenticação.
Siga estas instruções para adicionar as suas definições locais à configuração:
Inicie sessão no Portal do Azure
Selecione todos os recursos ou Serviços de Aplicações e, em seguida, clique no nome da sua Aplicação Móvel.
Clique em Ferramentas
Clique no explorador de recursos no menu OBSERVE e, em seguida, clique em Go. Uma nova janela ou separador abre.
Expanda os nós config, authsettings para o seu site na navegação à esquerda.
Clique em Editar
Procure o elemento "AllowedExternalRedirectUrls". Pode ser definido como nulo ou uma matriz de valores. Alterar o valor para o seguinte valor:
"allowedExternalRedirectUrls": [ "https://localhost:3000", "https://localhost:3000" ],Substitua os URLs pelos URLs do seu serviço. Exemplos incluem
https://localhost:3000(para o serviço de amostra Node.js) ouhttps://localhost:4400(para o serviço Ripple). No entanto, estes URLs são exemplos - a sua situação, incluindo para os serviços mencionados nos exemplos, pode ser diferente.Clique no botão Ler/Escrever no canto superior direito do ecrã.
Clique no botão PUT verde.
As definições são guardadas neste momento. Não feche a janela do navegador até que as definições tenham terminado de poupar. Adicione também estes URLs loopback às definições CORS para o seu Serviço de Aplicações:
- Inicie sessão no Portal do Azure
- Selecione todos os recursos ou Serviços de Aplicações e, em seguida, clique no nome da sua Aplicação Móvel.
- A lâmina Definições abre-se automaticamente. Se não, clique em Todos os Definições.
- Clique em CORS no menu API.
- Introduza o URL que pretende adicionar na caixa fornecida e prima Enter.
- Introduza URLs adicionais conforme necessário.
- Clique em Guardar para guardar as definições.
Leva aproximadamente 10-15 segundos para que as novas definições produzam efeitos.
Como: Registar-se para notificações push
Instale o plug-push-plug-plug-push para lidar com notificações push. Este plugin pode ser facilmente adicionado utilizando o cordova plugin add comando na linha de comando, ou através do instalador de plugins Git dentro de Visual Studio. O seguinte código na sua aplicação Apache Cordova regista o seu dispositivo para notificações push:
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
});
Utilize o Centro de Notificação SDK para enviar notificações push do servidor. Nunca envie notificações push diretamente dos clientes. Ao fazê-lo, poderá ser usado para desencadear um ataque de negação de serviço contra os Centros de Notificação ou o PNS. O PNS pode proibir o seu tráfego como resultado de tais ataques.
Mais informações
Pode encontrar detalhes detalhados da API na nossa documentação da API.