Como usar o plug-in 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ê é 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 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.
Aviso
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 o .NET MAUI, para obter 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 TodoItem tabela desde os 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 para app.component.ts 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 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:
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 Query, consulte a documentação do objeto Query.
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);
Paginar 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.
Retornar dados classificados
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].
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);
Na inserção bem-sucedida, o item inserido é retornado com campos extras 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.
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);
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);
Autenticar utilizadores
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:
Nota
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 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 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 fornecedor são "aad", "facebook", "google", "microsoftaccount" e "twitter".
Nota
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.
Neste caso, o Serviço de Aplicações do Azure gere 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 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.
Autenticar com um provedor (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. 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 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. Os detalhes exigidos por cada fornecedor são ligeiramente diferentes. Consulte a documentação de Autenticação e Autorização do Serviço de Aplicativo do Azure para determinar a forma exata da carga útil.
Obter informações sobre o usuário autenticado
As informações de autenticação podem ser recuperadas do /.auth/me ponto de extremidade usando uma chamada HTTP com qualquer biblioteca HTTP/REST. 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. 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:
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 em Explorador de recursos no menu OBSERVAR e, em seguida, clique em Ir. Abre-se uma nova janela ou separador.
Expanda os nós config, authsettings do seu site na navegação à esquerda.
Clique em 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 Ler/Escrever no canto superior direito do ecrã.
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:
- 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 folha Configurações é aberta automaticamente. Caso contrário, clique em Todas as configurações.
- Clique em CORS no menu API.
- Introduza o URL que pretende adicionar na caixa fornecida e prima Enter.
- Insira mais URLs conforme necessário.
- Clique em Guardar para guardar as definições.
Demora aproximadamente 10 a 15 segundos para que as novas configurações entrem em vigor.
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários