Como usar o plug-in Apache Cordova para Aplicativos Móveis do Azure
Observação
Este produto foi retirado. Para obter uma substituição para projetos que usam o .NET 8 ou posterior, consulte a biblioteca Community Toolkit Datasync.
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ê é 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 pré-criado do Apache Cordova. Neste guia, nos concentramos no plug-in Apache Cordova do lado do cliente.
Plataformas suportadas
Este SDK suporta Apache Cordova v6.0.0 e posterior em dispositivos iOS, Android e Windows. O suporte da plataforma é o seguinte:
- API Android 19+.
- iOS versões 8.0 e posteriores.
Advertência
Este artigo aborda informações para a versão da biblioteca v4.2.0, que foi desativada. Não serão feitas mais atualizações nesta biblioteca, incluindo atualizações para problemas de segurança. Considere mudar para um cliente .NET, como .NET MAUI para suporte contínuo.
Configuração e pré-requisitos
Este guia pressupõe que você tenha criado um back-end com uma tabela. Os exemplos usam a tabela TodoItem a partir dos inícios rápidos. Para adicionar o plug-in de 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 deles.
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 ao app.component.ts para criar o objeto cliente:
declare var WindowsAzure: any;
var client = new WindowsAzure.MobileServiceClient("https://yoursite.azurewebsites.net");
Agora você pode criar e executar o projeto no navegador:
ionic platform add browser
ionic run browser
O plug-in Cordova do Azure Mobile Apps suporta 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 pelo URL do 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 de ter uma referência de tabela, você pode trabalhar ainda mais com sua tabela:
Consultar uma referência de tabela
Depois de ter uma referência de tabela, você pode usá-la para consultar dados no servidor. As consultas são feitas em uma linguagem "semelhante ao 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 irá iterar sobre as 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, 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 através de dados
Utilize os métodos take() e skip(). Por exemplo, se desejar 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 results. O campo totalCount é preenchido com o número total de registros que seriam retornados se nenhuma paginação fosse usada.
Em seguida, você pode usar a variável pages e alguns botões da 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 apropriada e chame 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 que você desative o esquema dinâmico antes de mover seu aplicativo para a produção.
Modificar dados
Semelhante ao método .insert(), você deve criar um objeto Update e, em seguida, chamá.update(). O objeto update 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 o 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 de operações específicas apenas a 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 do Cordova devem estar disponíveis:
Observação
Alterações de segurança recentes no iOS e Android podem tornar a autenticação de fluxo de servidor indisponível. Nesses casos, você deve usar um fluxo de cliente.
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 de cliente permite uma integração mais profunda com recursos específicos do dispositivo, como logon único, pois depende de SDKs específicos do dispositivo do provedor.
Autenticar com um provedor (Fluxo de 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 seu aplicativo.
Depois de registrar seu provedor de identidade, chame o método .login() com o nome do seu provedor. Por exemplo, para iniciar sessão com o 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 provedor são 'aad', 'facebook', 'google', 'microsoftaccount' e 'twitter'.
Observação
Devido a preocupações de segurança, alguns provedores de autenticação podem não funcionar com um fluxo de servidor. Você deve usar um método de fluxo de cliente nesses casos.
Nesse caso, o Serviço de Aplicativo do Azure gerencia o fluxo de autenticação 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 login, quando concluída, retorna um objeto JSON que expõe o 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 de Cliente)
Seu aplicativo também pode entrar em contato de forma independente com o provedor de identidade e, em seguida, fornecer o token retornado ao seu Serviço de Aplicativo para autenticação. Esse fluxo de cliente permite que você forneça uma experiência de logon único 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 respetivo SDK do provedor seja armazenado na variável de token. Os detalhes exigidos por cada fornecedor são ligeiramente diferentes. Consulte o de documentação de Autenticação e Autorização do Serviço de Aplicativo 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 seu 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 a partir 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 um recurso de loopback para lidar com fluxos de interface do usuário OAuth. Os fluxos da interface do usuário OAuth no localhost causam problemas, já que 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 OAuth incluem:
- O emulador Ripple.
- Recarga ao vivo com Ionic.
- Executando o back-end móvel localmente
- Executar o back-end móvel em um Serviço de Aplicativo do Azure diferente daquele que fornece autenticação.
Siga estas instruções para adicionar as configurações locais à configuração:
Faça logon no portal do Azure
Selecione Todos os recursos ou Serviços de Aplicativo clique no nome do seu Aplicativo Móvel.
Clique Ferramentas
Clique em explorador de recursos no menu OBSERVAR e, em seguida, clique em Ir. Abre-se uma nova janela ou separador.
Expanda o de configuração , authsettings nós para o seu site na navegação à esquerda.
Clique Editar
Procure o elemento "allowedExternalRedirectUrls". Pode ser definido como null ou uma matriz de valores. Altere o valor para o seguinte valor:
"allowedExternalRedirectUrls": [ "http://localhost:3000", "https://localhost:3000" ],Substitua os URLs pelos URLs do seu serviço. Os exemplos incluem
http://localhost:3000(para o serviço de exemplo Node.js) ouhttp://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 de leitura/gravação no canto superior direito da tela.
Clique no botão verde PUT.
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 estas URLs de loopback às configurações de CORS do seu Serviço de Aplicativo:
- Faça logon no portal do Azure
- Selecione Todos os recursos ou Serviços de Aplicativo clique no nome do seu Aplicativo Móvel.
- A folha Configurações é aberta automaticamente. Caso contrário, clique em Todas as configurações.
- Clique CORS no menu API.
- Introduza o URL que pretende adicionar na caixa fornecida e prima Enter.
- Insira mais URLs conforme necessário.
- Clique Salvar para salvar as configurações.
Demora aproximadamente 10 a 15 segundos para que as novas configurações entrem em vigor.