Como usar a biblioteca de cliente JavaScript para Aplicativos Móveis do Azure

2019-06-25

Visão geral

Este guia ensina a executar cenários comuns usando o SDK JavaScript 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 e criar uma tabela. Neste guia, nos concentramos no uso do back-end móvel em aplicativos Web HTML/JavaScript.

Plataformas suportadas

Limitamos o suporte do navegador às versões atual e última dos principais navegadores: Google Chrome, Microsoft Edge, Microsoft Internet Explorer e Mozilla Firefox. Esperamos que o SDK funcione com qualquer navegador relativamente moderno.

O pacote é distribuído como um Módulo JavaScript Universal, por isso suporta os formatos global, AMD e CommonJS.

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 tenha o mesmo esquema que as tabelas nesses tutoriais.

A instalação do SDK JavaScript dos Aplicativos Móveis do Azure pode ser feita por meio do npm comando:

npm install azure-mobile-apps-client --save

A biblioteca também pode ser usada como um módulo ES2015, dentro de ambientes 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 de nossa 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 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 tabela
Inserção de dados
Modificando dados
Exclusão de dados

Como: 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 utilize for (var i in results) na função de sucesso, pois isso fará iteração sobre informações que fazem parte dos resultados quando outras funções de consulta (como .includeTotalCount()) forem utilizadas.

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.

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, consulte a [documentação do objeto Query].

Como: 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 os campos adicionais 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.

Como: Modificar dados

Semelhante ao método .insert(), você deve criar um objeto Update e, em seguida, chamar .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);

Como: 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);

Como: 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.

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 provedor.

Como 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

Atualmente, a Autenticação do Google não funciona por meio do Fluxo de Servidores. 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 início de sessão do provedor selecionado e gera um token de autenticação do Serviço de Aplicações após um início de sessão bem-sucedido 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.

Como fazer: Autenticar-se com um provedor (fluxo do 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 adicionais do usuário do provedor de identidade.

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.

Como: Obter informações sobre o usuário autenticado

As informações de autenticação podem ser recuperadas do /.auth/me endpoint usando uma chamada HTTP com uma qualquer biblioteca AJAX. 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. Você também pode usar o jQuery ou outra API AJAX para buscar as informações. Os dados são recebidos como um objeto JSON.

Como configurar o Serviço de Aplicações Móveis para URLs de redirecionamento externo.

Vários tipos de aplicativos JavaScript usam um recurso de loopback para lidar com fluxos de interface do usuário OAuth. Estas capacidades incluem:

Executando seu serviço localmente
Usando o Live Reload com o Ionic Framework
Redirecionamento para o Serviço de Aplicativo para autenticação.

A execução local pode causar problemas porque, por padrão, a autenticação do Serviço de Aplicativo só é configurada para permitir o acesso a partir do back-end do Aplicativo Móvel. Use as seguintes etapas para alterar as configurações do Serviço de Aplicativo para habilitar a autenticação ao executar o servidor localmente:

Inicie sessão no Portal do Azure
Navegue até o back-end do aplicativo móvel.
Selecione Explorador de recursos no menu FERRAMENTAS DE DESENVOLVIMENTO .
Clique em Ir para abrir o explorador de recursos para o back-end da sua Aplicação Móvel num novo separador ou janela.
Expanda o nó config>authsettings para a sua aplicação.
Clique no botão Editar para ativar a edição do recurso.
Localize o elemento allowedExternalRedirectUrls , que deve ser null. Adicione seus URLs em uma matriz:
```
  "allowedExternalRedirectUrls": [
      "https://localhost:3000",
      "https://localhost:3000"
  ],
```
Substitua as URLs na matriz pelas URLs do seu serviço, que neste exemplo é https://localhost:3000 para o serviço de exemplo Node.js local. Você também pode usar https://localhost:4400 para o serviço Ripple ou alguma outra URL, dependendo de como seu aplicativo está configurado.
Na parte superior da página, clique em Leitura/Gravação e, em seguida, clique em PUT para salvar as suas atualizações.

Você também precisa adicionar as mesmas URLs de loopback às configurações da lista de permissões do CORS:

Navegue de volta para 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 vazia Origens permitidas. Uma nova caixa de texto é criada.
Clique em SALVAR

Após as atualizações de back-end, você poderá usar as novas URLs de loopback em seu aplicativo.

Partilhar via