Como Utilizar a biblioteca de cliente JavaScript para Aplicações Móveis do Azure

Artigo
06/25/2019

Descrição Geral

Este guia ensina-o a realizar cenários comuns com o SDK JavaScript mais recente para Aplicações Móveis do Azure. Se não estiver familiarizado com as Aplicações Móveis do Azure, comece por concluir o Guia de Introdução às Aplicações Móveis do Azure para criar um back-end e criar uma tabela. Neste guia, focamo-nos na utilização do back-end móvel em aplicações Web HTML/JavaScript.

Plataformas suportadas

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

O pacote é distribuído como um Módulo JavaScript Universal, pelo que suporta formatos globais, AMD e CommonJS.

Configuração e pré-requisitos

Este guia pressupõe que criou um back-end com uma tabela. Este guia pressupõe que a tabela tem o mesmo esquema que as tabelas nesses tutoriais.

A instalação do SDK JavaScript das Aplicações Móveis do Azure pode ser feita através do npm comando:

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

A biblioteca também pode ser utilizada como um módulo ES2015, em 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';

Também pode utilizar uma versão pré-criada do SDK ao transferir diretamente a partir da nossa CDN:

<script src="https://zumo.blob.core.windows.net/sdk/azure-mobile-apps-client.min.js"></script>

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 Tabela
Inserir Dados
Modificar dados
Eliminar Dados

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

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.

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 utilizadores

Serviço de Aplicações do Azure suporta a autenticação e autorização de utilizadores de aplicações através de vários fornecedores de identidade externos: Facebook, Google, Conta Microsoft e Twitter. Pode definir permissões em tabelas para restringir o acesso a operações específicas apenas para utilizadores autenticados. Também pode utilizar a identidade dos utilizadores autenticados para implementar regras de autorização em scripts de servidor. Para obter mais informações, veja o tutorial Introdução à autenticação .

São suportados dois fluxos de autenticação: um fluxo de servidor e um fluxo de cliente. O fluxo de servidor fornece a experiência de autenticação mais simples, uma vez que depende da interface de autenticação Web do fornecedor. O fluxo de cliente permite uma integração mais profunda com capacidades específicas do dispositivo, como o início de sessão único, uma vez que depende de 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 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

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 início de sessão do fornecedor selecionado e gera um token de autenticação Serviço de Aplicações após o início de sessão com êxito 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.

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 a sua Serviço de Aplicações móvel para URLs de redirecionamento externos.

Vários tipos de aplicações JavaScript utilizam uma capacidade de loopback para processar fluxos de IU do OAuth. Estas funcionalidades incluem:

Executar o seu serviço localmente
Utilizar o Live Reload com o Ionic Framework
Redirecionar para Serviço de Aplicações para autenticação.

A execução local pode causar problemas porque, por predefinição, Serviço de Aplicações autenticação só está configurada para permitir o acesso a partir do back-end da Aplicação Móvel. Utilize os seguintes passos para alterar as definições de Serviço de Aplicações para ativar a autenticação ao executar o servidor localmente:

Inicie sessão no Portal do Azure
Navegue para o back-end da Aplicação Móvel.
Selecione Explorador de recursos no menu FERRAMENTAS DE DESENVOLVIMENTO .
Clique em Ir para abrir o explorador de recursos do back-end da Aplicação Móvel num novo separador ou janela.
Expanda o nó config>authsettings da sua aplicação.
Clique no botão Editar para ativar a edição do recurso.
Localize o elemento allowedExternalRedirectUrls , que deve ser nulo. Adicione os URLs numa matriz:
```
  "allowedExternalRedirectUrls": [
      "https://localhost:3000",
      "https://localhost:3000"
  ],
```
Substitua os URLs na matriz pelos URLs do seu serviço, que neste exemplo se https://localhost:3000 destinam ao serviço de exemplo de Node.js local. Também pode utilizar https://localhost:4400 para o serviço Ripple ou outro URL, consoante a forma como a sua aplicação está configurada.
Na parte superior da página, clique em Leitura/Escrita e, em seguida, clique em PUT para guardar as atualizações.

Também tem de adicionar os mesmos URLs de loopback às definições da lista de permissões CORS:

Navegue de volta para o portal do Azure.
Navegue para o back-end da Aplicação Móvel.
Clique em CORS no menu API .
Introduza cada URL na caixa de texto Origens Permitidas vazia. É criada uma nova caixa de texto.
Clique em GUARDAR

Após as atualizações de back-end, poderá utilizar os novos URLs de loopback na sua aplicação.