Introdução

No mês de Março, a Microsoft anunciou uma alteração à sua oferta de serviços introduzindo o novo Azure App Service. Este serviço agrega os “antigos” Websites, agora com o nome Web Apps, os Azure Mobile Services, agora Mobile Apps, e introduz novas capacidades como as Logic Apps e as API Apps. É sobre estas últimas que se foca este artigo.
A questão que se coloca é: Qual o motivo para criar uma API App e não uma Web API num Website? Esta questão pode ser facilmente respondida vendo a lista das funcionalidades disponibilizadas, como por exemplo:

• Controlo de acesso por recurso à Azure Active Directory ou serviços OAuth, como Facebook ou Twitter;
• Integração rápida com a Framework Swagger;
• Integração fácil com as Logic Apps;
• Galeria privada de APIs que permite disponibilizar as APIs a outros membros da organização;
• Geração automática de um SDK para a nossa API;

Neste artigo vamos ver como implementar uma API, publicá-la na nossa subscrição e criar um SDK para consumir a mesma.

Descrição

Existem inúmeros serviços, dentro das organizações, que são necessários ao funcionamento das diversas aplicações. Um bom exemplo é o envio de e-mails.

Imaginemos que pretendemos disponibilizar uma API, para que todas as aplicações da nossa organização possam facilmente enviar e-mails, sem a preocupação de conhecer a lógica de utilização do servidor de e-mail.

Antes de começar, temos que garantir que o Microsoft Azure SDK for .NET 2.6, se encontra instalado.

Criar um projeto API App

Vamos começar por ver como criar um projeto para a nossa API App.

1. Abrir o Visual Studio 2013;
2. Criar um novo projeto utilizando a função File > New Project;
3. Escolher a template ASP.NET Web Application;
4. Atribuir um nome ao projeto. Neste exemplo vamos utilizar MailApi;
5. Clicar em OK;
6. Na janela apresentada, selecionar a template Azure API App;
7. Clicar em OK para criar o projeto;

Criar o serviço de envio de e-mail

Vamos ver como expor um método para enviar e-mails na nossa API. Para tal, vamos criar uma classe que representa o modelo dos dados a receber no pedido, e um Controller para expor o método de envio.

1. Na pasta Models da nossa solução, adicionar uma nova classe com o nome MailModel. Botão direito do rato na pasta Models e selecionar a opção Add > Class.
2. No ficheiro MailModel.cs criado, adicionar o seguinte código:

   using System.ComponentModel.DataAnnotations;
   public class MailModel
   {
    [Required]
    [EmailAddress]
    public string To { get; set; }
   
    [Required]
    public string Subject { get; set; }
   
    [Required]
    public string Body { get; set; }
   }

3. Adicionar um Controller ao projeto (na pasta Controllers) com o nome MailController, utilizando a template Web API 2 Controller – Empty;
4. No ficheiro criado MailController.cs adicionar o seguinte método;

   using MailApi.Models;
   [HttpPost]
   public HttpResponseMessage Post([FromBody]MailModel data)
   {
    using (var client = new System.Net.Mail.SmtpClient())
    {
    // create the message
    var mailFrom = new System.Net.Mail.MailAddress("noreply@deathstar.com", "Death Star");
    var mailTo = new System.Net.Mail.MailAddress(data.To);
    var mail = new System.Net.Mail.MailMessage(mailFrom, mailTo);
    
    mail.Subject = data.Subject;
    mail.Body = data.Body;
    mail.IsBodyHtml = true;
    
    // send email
    client.Send(mail);
    }
    return Request.CreateResponse(HttpStatusCode.OK);
   }

Configurar o serviço

Uma vez que neste exemplo vamos enviar o e-mail via SMTP, necessitamos de configurar os dados do servidor de e-mail.

1. Aceder ao ficheiro Web.config da nossa aplicação;
2. Adicionar a seguinte configuração (antes da linha):

   <system.net>
    <mailSettings>
    <smtp from="noreply@deathstar.com">
    <network host="mail.deathstar.com" port="587" userName="noreply@deathstar.com" password="#MayTheForceBeWithThisPassword!" enableSsl="true" />
    </smtp>
    </mailSettings>
    </system.net>

3. Preencher com os dados do nosso servidor.

Publicar a aplicação para o Azure App Service

A publicação pode ser feita para um App Service criado anteriormente no Portal, mas aqui vamos ver como criar o mesmo sem sair do Visual Studio.

Para realizar este passo é necessário ter uma subscrição do Azure. Se não tens, podes criar uma subscrição de testes de um mês em http://azure.microsoft.com/en-us/pricing/free-trial/. Se já tens uma subscrição, segue os seguintes passos:

1. No Solution Explorer, clicar com o botão direito no projeto e clicar em Publish;
2. Na janela de publicação, aceder ao painel Profile e escolher a opção Microsoft Azure API Apps;
3. Clicar em New para criar uma nova API App na subscrição;
4. Na janela de criação da API App introduzir:
   • O nome da API App. Neste caso vamos utilizar MailApiService;
   • Selecionar a subscrição pretendida;
   • Escolher um nome para o App Service;
   • Escolher um nome para o Resource Group;
   • Escolher o nível de acesso Available to Anyone;
   • Escolher a região onde alojar o App Service.
5. Clicar em OK e aguardar uns minutos para até o serviço ser criado. O processo de criação do serviço pode ser acompanhado no painel Azure App Service Activity;
6. Uma vez criado o App Service, voltamos a executar o passo número 1, aceder à janela de publicação, e clicamos na opção Publish;
7. O serviço será publicado.

Consumir a API a partir de um cliente .NET

Agora vamos ver como criar um SDK para a nossa API e utilizá-lo.

1. Adicionar uma Console Application à nossa solução;
2. No Solution Explorer, clicar com o botão direito do rato na Console Application e selecionar a opção Add > Azure API App Client;
3. Na janela apresentada, escolher a opção Download from Microsoft Azure API App e selecionar o MailApiService, criado anteriormente;
4. Clicar em OK e aguardar que o nosso SDK seja gerado;
5. Quando terminar, estamos prontos para invocar a API, como demonstra o exemplo que se segue.

   class Program
    {
    static void Main(string[] args)
    {
    var client = new MailApiService();
    var data = new Models.MailModel { To = "darth.vader@deathstar.com", Subject = "War Report", Body = "The Force awakens" };
   
    var response = client.Mail.Post(data);
   
    Console.WriteLine("Done!");
    Console.ReadKey();
    }
    }

Conclusão

Com este novo serviço disponibilizado pela Microsoft, podemos, de forma fácil e rápida, disponibilizar funcionalidades que anteriormente tinham um grande custo de desenvolvimento. A lógica da galeria privada aliada à facilidade em consumir a API, permite evitar a replicação de funcionalidades, criando um ecossistema de APIs ao dispor de todos.