Engenho &amp; Engenhocas

Para ler

Azure API Gateway

Para ler

Um sistema Azure que fornece APIs a aplicações externas deve usar uma Gateway para essas APIs, a Azure API Gateway. A API Gateway permite organizar e publicar as APIs do sistema, públicas ou protegidas, disponibilizando-as a programadores, parceiros, clientes e mesmo clientes internos se for caso disso. A API Gateway tem a infra-estrutura e monitorização necessárias à disponibilização de uma API mediante pagamento.

A Gateway deve ser pensada como proxy ou nível de indirecção entre os clientes e as operações de todas as APIs.

A Gateway tem um portal que pode ser usado para publicar, gerir e monitorizar as APIs do sistema, e um outro portal para os clientes se autenticarem, criarem as suas chaves de acesso, reportar incidentes ou problemas e ler a documentação das APIs.

Pré-requisitos

Pressupõe-se a criação de Azure Function do tipo HTTP Trigger com o nível de autorização configurado com o valor Function.
No exemplo, GetName.

public static class GetName
    {
        [FunctionName("GetName")]
        public static async Task<HttpResponseMessage> Run([HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)]HttpRequestMessage req, TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");

            // parse query parameter
            string name = req.GetQueryNameValuePairs()
                .FirstOrDefault(q => string.Compare(q.Key, "name", true) == 0)
                .Value;

            // Get request body
            dynamic data = await req.Content.ReadAsAsync<object>();

            // Set name to query string or body data
            name = name ?? data?.name;

            return name == null
                ? req.CreateResponse(HttpStatusCode.BadRequest, "Please pass a name on the query string or in the request body")
                : req.CreateResponse(HttpStatusCode.OK, "Hello " + name + ", you are great!");
        }
    }

Pressupõe-se a criação de uma instância de API Management do Azure. Para exemplo, testingapisclopes.

Criação da definição OpenAPI (Swagger)

Depois de testar a função, seleccionar a opção Integrate da nova função e indicar os verbos HTTP permitidos.
Na Function App desta nova função, seleccionar Platform Features e API Definition. É apresentada a página para definição da API (Swagger) idêntica à seguinte. Na API Definition, seleccionar o valor Function.

Seleccionar Generate API definition template > Save.

O Azure varre a Function App à procura das funções do tipo HTTP Trigger e usa a informação do functions.json para gerar a definição OpenAPI.
Uma vez gerada a template da definição, completa-se com os metadados das operações e das estruturas de dados e grava-se.

Testar a OpenAPI

Na opção Manage da nova função, copiar a chave definida por omissão (default key) para as chaves do host (Host Keys).
Voltar à página de Definição da API (Function App Name > Platform features > API definition) e no painel da direita seleccionar change authentication, colar a chave definida por omissão e seleccionar authenticate.
Testar a operação através da acção Try this operation e verificar o output.

Importação da API para o API Management

Como a Function App está protegida por uma chave, há que criar uma entrada do tipo Named Value e aplicar a política set-query-parameter policy para que a chave seja adicionada automaticamente quando a Function App é invocada a partir do APIM. A Gestão de APIs distingue as APIs pelo respectivo sufixo. Por exemplo, functionappapi.

Testar a nova API APIM no portal do Azure

Seleccionar a API recém criada, escolher o separador Test e seleccionar o método a testar. GetName, por exemplo. A página apresenta os campos para os parâmetros de consulta, como por exemplo name. A página também apresenta os campos para os cabeçalhos. Um dos campos de cabeçalho é "Ocp-Apim-Subscription-Key", para a chave de subscrição do produto que está associado esta API. Quem cria a instância APIM é administrador por omissão, pelo que a chave é automaticamente preenchida.
Uma vez conferidos os campos, seleccionar Send.
O Back-end responde com 200 OK e o corpo da resposta.

Testar a nova API APIM no portal do Programador

Seleccionar a API a testar e o método a testar. A página também apresenta os campos para os cabeçalhos. Um dos campos de cabeçalho é "Ocp-Apim-Subscription-Key", para a chave de subscrição do produto que está associado esta API. Quem cria a instância APIM é administrador por omissão, pelo que a chave é automaticamente preenchida.
Depois de conferidos os campos, seleccionar Try It.
Uma vez invocada a operação, o portal do programador apresenta o status da resposta, os cabeçalhos da resposta e o corpo ou conteúdo da resposta.

Exemplo de pedido HTTP

GET https://testingapisclopes.azure-api.net/functionappapi/api/GetName?name=48 HTTP/1.1
Host: testingapisclopes.azure-api.net
Ocp-Apim-Subscription-Key: fc1767dcf0b448ce9c9d6d3cfcea5739

Referências: Import an API from a Function App now available in the APIs blade, Create an OpenAPI definition for a function, Importar e publicar a sua primeira API

Redis Caching

Para ler

Redis é um motor de base de dados em memória com armazenamento baseado em tabelas de hash (key-value).

O cliente .NET StackExchange.Redis é amplamente usado pelas suas características votadas à alta performance e foi desenvolvido pela equipa da Stack Exchange. Documentação completa do cliente StackExchange.Redis aqui.

Instalação dos clientes da cache

Instalação pela consola NuGet

PM> Install-Package StackExchange.Redis

ou para projectos strong-named

PM> Install-Package StackExchange.Redis.StrongName

Ligação à cache

Incluir a bilbioteca StackExchange.Redis

using StackExchange.Redis;

A ligação à Cache do Redis é gerida pela classe ConnectionMultiplexer. Esta classe deve ser partilhada e reutilizada em toda a aplicação cliente e não precisa de ser criada para cada operação.

ConnectionMultiplexer connection = ConnectionMultiplexer.Connect(<connectionstring>);

Exemplo de connection string Azure

<azure redis cache id>.redis.cache.windows.net:6380,password=<pwd>,ssl=True,abortConnect=False

Se não se pretender utilizar o protocolo SSL, definir ssl=false ou omitir o parâmetro ssl.
O abortConnect está definido como falso, o que significa que a chamada terá êxito mesmo se não for estabelecida uma ligação à Cache do Redis do Azure. Uma funcionalidade-chave do ConnectionMultiplexer consiste no restauro automático da conectividade à cache assim que o problema de rede ou outros problemas tiverem sido resolvidos.

Uma abordagem para partilhar uma instância ConnectionMultiplexer consiste em ter uma propriedade estática que devolva uma instância ligada, tal como no exemplo seguinte. Esta abordagem fornece uma forma segura para as threads de modo a inicializar apenas uma única instância ConnectionMultiplexer ligada.

private static Lazy<ConnectionMultiplexer> lazyConnection = new Lazy<ConnectionMultiplexer>(() =>
        {
            return ConnectionMultiplexer.Connect(ConfigurationManager.ConnectionStrings["RedisCache"].ConnectionString);
        });

        public static ConnectionMultiplexer Connection
        {
            get
            {
                return lazyConnection.Value;
            }
        }

Documentação detalhada da configuração do cliente StackExchange.Redis aqui

Para ser colocado em cache, o objecto .NET tem de ser serializado.

Uma forma simples de serializar objectos passa por utilizar os métodos de serialização JsonConvert da framework Newtonsoft.Json.NET e serializar de e para JSON.
Documentação da framework Json.NET aqui.

Instalação pela consola NuGet

PM> Install-Package Newtonsoft.Json

Incluir a bilbioteca Newtonsoft.Json

using Newtonsoft.Json;

Uma alternativa é usar uma extensão como o StackExchange.Redis.Extender que trata da serialização de e para JSON do StackExchange.Redis. Projecto disponível aqui.

Exemplo de Utilização

Adcionar ao App.config

<connectionStrings>
    <add name="RedisCache" connectionString="<azure redis cache id>.redis.cache.windows.net:6380,password=<pwd>,ssl=True,abortConnect=False"/>
  </connectionStrings>

Obtenção das credenciais

System.Configuration.ConfigurationManager.ConnectionStrings["RedisCache"].ConnectionString);

POCO

 public class Author
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public virtual ICollection<Course> Courses { get; set; }
    }

    public class Course
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Description { get; set; }
        public int Level { get; set; }
        public float FullPrice { get; set; }
        public int AuthorId { get; set; }
        public bool IsBeginnerCourse
        {
            get { return Level == 1; }
        }
        public virtual Author Author { get; set; }
    }

Método AddAuthor

 static Author AddAuthor()
        {

            return new Author
            {
                Id = 1,
                Name = "Silvia Pinhao Lopes",
                Courses = new List<Course>
  {
   new Course
   {
    AuthorId = 1,
    Description = "First Course",
    FullPrice = 12,
    Id = 1,
    Level = 1,
    Name = "1st Course"
   }
  }
            };
        }

Invocação

static void Main(string[] args)
        {
            IDatabase cache = Connection.GetDatabase();
            IEnumerable authors;

            var cAuthorKey = "authors";

            RedisValue lstAuthors = cache.StringGet(cAuthorKey);

            if (!lstAuthors.HasValue)
            {
                authors = new List<Author> { AddAuthor() };

                cache.StringSet(cAuthorKey, value: JsonConvert.SerializeObject(authors, Formatting.Indented), expiry: TimeSpan.FromMinutes(2));
            }
            else
            {
                Console.WriteLine("Cache hit");
                authors = JsonConvert.DeserializeObject<IEnumerable<Author>>(lstAuthors);
            }

            foreach (var author in authors)
            {
                Console.WriteLine(author.Name);
            }

            Console.Read();

        }

Referências: Como Utilizar a Cache de Redis do Azure, Azure: Redis Cache

Para instalação local do servidor Redis ver artigo Distributed Caching using Redis Server with .NET/C# Client

.NET Developer on Azure

Para ler

Depurar Azure Functions com VS 2017 Cloud Explorer

Para ler

Depurar Azure Functions com Visual Studio Code

Para ler

Este exercício aplica-se a função despoltada por pedido HTTP (HTTP Triggered Function).

Uma função deste tipo pode ser testada usando a extensão REST Client do Visual Studio Code desenvolvida por Huachao Mao e disponível aqui. Esta extensão permite efectuar pedidos HTTP tanto locais como remotos usando o botão direito do rato.

Passos deste exercício:
Instalar o Visual Studio Code

Instalar a extensão REST Client

Criar um novo ficheiro com o nome test-function-locally.http

Adicionar o seguinte código para pedido HTTP a uma função como nome HttpTrigger:

get http://localhost:7071/api/HttpTrigger

get http://localhost:7071/api/HttpTrigger?name=Tyto

Seleccionar a linha de código a testar e com o botão direito do rato seleccionar Send Request.

O painel da direita apresenta a resposta HTTP do servidor, tanto o cabeçalho como o corpo da mensagem.

Relacionado: Desenvolvimento local de Azure Functions

Referência: Create an Azure Functions HTTP trigger with an Azure Cosmos DB input binding

Desenvolvimento local de Azure Functions

Para ler