Creando una API RESTful con documentación sobre Azure App Service.

Introducción 

La plataforma de Azure provee un vasto set de capacidades dentro de un modelo de Plataforma como servicio (PaaS) para alojar aplicaciones web y servicios. La plataforma es capaz de ofrecer algo más que solo alojar para ejecutar la lógica en sus aplicaciones; esta también incluye una serie de robustos mecanismos para gestionar todos los aspectos acerca del ciclo de vida de su aplicación web como servicios web respectivamente. 

Azure App Services incluye un numero de características para gestionar sus aplicaciones web y servicios incluyendo Web Apps, Logic Apps, Mobile Apps y API Apps.  De esta manera hacemos introducción para explicar mediante este articulo con un breve ejemplo el uso de estas características para alojar en este caso específico una web API RESTful de manera muy sencilla y en adición a una documentación robusta y dinámica. 

Estas características claves son de primordial importancia para la creación de aplicaciones web modernas a través de la nube de Azure como (PaaS). 

Cuando usted está en el proceso de diseño de una arquitectura de software basada en una aplicación web, una de las capas que necesitara implementar es una API lo cual permite que las capas de su arquitectura puedan comunicarse con cada una de las demás. Independientemente de la arquitectura de su aplicación, esta es una buena oportunidad para que implemente una API RESTful para que dicha intercomunicación suceda con su respectiva documentación para el uso de su API. 

Luego de leer este articulo usted podrá: 

  • Crear una aplicación API RESTful sobre Azure App service. 
  • Crear una documentación bien estructurada para la API utilizando herramientas de código abierto. 

Crear una aplicación API con Azure App Service es un poco similar a crear una aplicación web normal desplegada como un App service. Usted podrá tener las mismas opciones disponibles para su aplicación API que usted tiene para una aplicación web normal. 

Crear e implementar una aplicación API 

Para crear una aplicación API RESTful en Azure App Service existen muchas formas, las maneras más comunes son ya sea mediante el portal de Azure o directamente desde Visual Studio, en este caso vamos a realizar el ejemplo desde Visual Studio 2019: 

  1. Ejecute Visual Studio 2019 y seleccione en la opción Archivo > Nuevo > Proyecto. 
  1. En la ventana emergente de Nuevo Proyecto, seleccione ASP.NET Web Application (.Net Framework) dentro de la categoría de Cloud y haga clic en Siguiente. 
  1. En la ventana emergente de configuración del Nuevo Proyecto, escriba el nombre del proyecto, en la ubicación física en el disco seleccione el tipo de framework .NET a utilizar y luego haga clic en Crear. 
  1. Seleccione la plantilla de Web API en la ventana emergente de configuración de nuevo proyecto y luego haga clic en Crear. 

De esta manera Visual Studio crea un nuevo proyecto web API con la siguiente estructura de archivos en el árbol de archivos en el explorador de la solución: 

Generar la documentación automática de la API usando Swashbuckle 

Swashbuckle es un framework de código abierto muy popular que consiste en un gran ecosistema de herramientas que funcionan para diseñar, construir, documentar, y consumir su RESTful API, lo que lo vuelve la alternativa ideal para crear la documentación de la API de manera más automatizada, el paquete de NuGet está muy bien documentado así que pueden revisar la documentación para más detalles accediendo al proyecto GitHub accediendo al final del artículo. 

Swashbuckle se proporciona a través de un conjunto de paquetes de NuGet: Swashbuckle y Swashbuckle Core. A continuación, siga estos pasos para agregar Swashbuckle a su proyecto de API: 

  1. Instale el paquete de NuGet, lo cual incluye Swashbuckle.Core como una dependencia al momento de instalar usando el siguiente comando desde la consola de paquetes de Nuget: 
Install-Package Swashbuckle 
  1. El paquete de NuGet también instala un archivo de arranque inicial o bootstrapper (App_Start/SwaggerConfig.cs) lo cual habilita las rutas de Swagger al iniciar la aplicación API usando WebActivatorEx. Usted también puede configurar las opciones de Swashbuckle modificando el método de extensión GlobalConfiguration.Configuration.EnableSwagger en el archivo SwaggerConfig.cs. también puede excluir de su API las acciones que han sido marcadas con el decorativo de obsoletas agregando la siguiente configuración: 
public class SwaggerConfig 
{ 
        public static void Register() 
        { 
            var thisAssembly = typeof(SwaggerConfig).Assembly; 
  
            GlobalConfiguration.Configuration 
              .EnableSwagger(c => 
              { 
                ...  
                ... 
              //Set this flag to omit schema property descriptions    for any type properties decorated with the Obsolete attribute 
                      
                c.IgnoreObsoleteProperties(); 
 
               ... 
               ... 
         }); 
      } 
 } 
  1. Modifique las acciones de los controladores en su proyecto API para incluir el atributo swagger para ayudar al generador a construir los metadatos de swagger. 
  1. Swashbuckle está ahora configurado para generar los metadatos Swagger para los endpoints de su API con una simple interfaz de usuario para explorar la metadata. Por ejemplo, el controlador que se lista puede producir la UI que se muestra bastando solo con escribir Swagger en la barra del navegador web seguido de la url de la aplicación web.  

Publicar la API RESTful en Azure App Service 

Hasta este punto ya tenemos el diseño de una API con lo básico para conectar con las demás capas de su proyecto, también contamos con una documentación que ya se genera de manera automática, aprovechando al máximo toda la metadata y definición de su API a través de las acciones de sus controladores, ya preparado lo anterior mencionado hasta este momento para implementar su aplicación API se necesita completar la publicación desde Visual Studio hacia Azure App Service para desplegar su proyecto API en la nube. 

Siga estos pasos para desplegar su proyecto API desde Visual Studio: 

  1. Haga clic derecho sobre el proyecto en el Visual Studio Solution Explorer y luego hacer clic en Publicar.
  1. En la ventana de dialogo de publicación, seleccione en App Service en la parte izquierda superior, luego Crear Nuevo, posteriormente hacer clic en publicar para ir a la configuración de App Service de Azure.

  1. La ventana cambiara y lo enviara a una configuración más específica donde primeramente debe de escribir el nombre de la aplicación a desplegar en Azure App Services, luego seleccione la suscripción a la cual está asociado en su portal de Azure. 
  1. A continuación, se debe de especificar un grupo de recurso dentro de la nube de Azure al cual se va a asignar la aplicación web API como recurso de Azure App Service. 
  1. En el caso de que no posea ningún recurso o quiera crear un nuevo recurso haga clic en nuevo nombre de grupo de recurso a crear. 
  1. Este grupo de recurso por lo general asigna una capacidad de gasto calculado a través de un plan de hosting escalable con más o menos capacidades como lo son por ejemplo uso de RAM o número de procesadores necesarios para la ejecución del API, lo cual por defecto selecciona S1 (1 core, 1.75 GB RAM), en este caso le vamos a bajar escalabilidad del API para efectos de prueba y seleccionamos un plan de costos gratuito, este por ser compartido y además por ser un ambiente inicial de pruebas, cuando ya se quiera escalar más la aplicación o cambiar a un ambiente de más calidad y/o producción se puede optimizar a un plan adecuado para ejecutar de manera eficiente su proyecto API. 
  1. Una vez configurado todo el entorno del proyecto API en Azure App Service, se crea un perfil de publicación en Visual Studio para que cada vez que quiera ejecutar un despliegue de su API con cambios nuevos simplemente le damos a ejecutar la publicación mediante el botón Publicar. Visual Studio procede a compilar e intentar subir todos los archivos del proyecto API hacia la nube de Azure mediante Azure App service, de esta manera ya puede acceder a su API a través de la internet. 
  1. Cuando la publicación de su proyecto API esté finalizado, este abrirá en una nueva ventana de navegador donde se mostrará la página web inicial de publicación. 
  1. Navegaremos hacia la documentación Swagger a través de la ruta /Swagger para ver los detalles de la documentación de la API, además para probar los métodos REST ya expuestos mediante la API. Por ejemplo, http://<SU-API-APP&gt;.azurewebsites.net/swagger/ 

De esta manera ya podemos contar con una aplicación RESTful con una documentación bien estructurada de manera automatizada debidamente ejecutándose a través de la nube de Azure mediante Azure App Service. 

Código fuente 

https://github.com/hughfernandez/API-RESTfull-Demo-Doc-Swagger

Primer vistazo a Xamarin Essentials

Originalmente llamado Caboodle, Xamarin.Essentials es una libreria simple para acceder a funciones nativas tanto para iOS, Android y UWP

xamarin-essentials

Para hacerlo más fácil, ahora existe Xamarin.Essentials, un paquete único que puede instalar en cualquier aplicación Xamarin para obtener acceso multiplataforma a una amplia gama de API, como acelerómetro, brújula, conectividad de red, mantener la pantalla encendida y más . Puede ver la lista completa de características compatibles en la página de Xamarin Essentials GitHub. Este paquete actualmente tiene 24 conjuntos de API diferentes, con más planeado. Essentials es para todas las aplicaciones de Xamarin, tanto tradicionales como de formularios.

Empezando

Aquí, usaré Xamarin.Forms como punto de partida, simplemente agregue el paquete Xamarin.Essentials NuGet a todos los proyectos (iOS, Android y .NET estándar). Dado que actualmente se encuentra en vista previa, asegúrese de marcar la casilla incluir version preliminar en la ventana Agregar paquetes de Nuget.

2018-06-20_17-37-13

A continuación la lista confirmada de los APIs para su primer release:

Aprende más

Lea más sobre este lanzamiento en las notas de la versión completa y asegúrese de examinar nuestra documentación completa, que ofrece una descripción completa de cómo comenzar y cómo usar cada característica de Xamarin.Essentials.

Para mas información

 

Enjoy 🙂

Consultas elasticas en SQL Azure

No les pasa que tenemos todo listo en nuestro servidor Azure (servicio, servidor de base de datos, bases de datos, Certificado SSL, Dominio, etc…); ¡Todo perfecto para que nuestra aplicación ya salga a tope con todos los hierros y de repente surge una escalabilidad o una implementación adicional y tenemos que crear una base de datos o tomar los datos de otra base de datos para respetar la integridad de los datos y tomalaaaa!… donde queremos hacer algo asi?:

Use BaseDeDatos1

SELECT  *  FROM [BaseDeDatos2].dbo.Tabla1

“Msg 40515, Level 15, State 1, Line 16
Reference to database and/or server name in ‘BaseDeDatos2.dbo.Tabla1’ is not supported in this version of SQL Server.”

No sufras más y sigue este pequeño tutorial para poder realizar consultas entre bases de datos en distintos servidores de Azure o en el mismo servidor per se.

cross-search-tools

Consultas elásticas

La función de consulta elástica le permite ejecutar una consulta de Transact-SQL que abarca varias bases de datos en la base de datos SQL de Azure. Le permite realizar consultas entre bases de datos para acceder a tablas remotas y conectar herramientas de Microsoft y de terceros (Excel, PowerBI, Tableau, etc.) para consultar en niveles de datos con múltiples bases de datos. Con esta función, puede escalar consultas a grandes niveles de datos en la base de datos SQL y visualizar los resultados en informes de inteligencia empresarial (BI).

¿Por qué usar consultas elásticas?

Base de datos SQL Azure

Consulta en todas las bases de datos SQL de Azure en T-SQL. Esto permite la consulta de solo lectura de las bases de datos remotas. Esto proporciona una opción para que los clientes actuales de SQL Server local migren aplicaciones con nombres de tres y cuatro partes o un servidor vinculado a SQL DB.

Disponible en nivel estándar

La consulta elástica es compatible con el nivel de rendimiento estándar además del nivel de rendimiento Premium.

Enviar a bases de datos remotas

Las consultas elásticas ahora pueden enviar parámetros SQL a las bases de datos remotas para su ejecución.

Ejecución de procedimiento almacenado

Ejecute llamadas a procedimientos almacenados remotos o funciones remotas utilizando sp_execute _remote.

Flexibilidad

Las tablas externas con consulta elástica ahora pueden hacer referencia a tablas remotas con un esquema o nombre de tabla diferente.

Escenarios elásticos de consulta

El objetivo es facilitar la consulta de escenarios donde múltiples bases de datos aportan filas en un solo resultado global. La consulta puede ser compuesta por el usuario o la aplicación directamente, o indirectamente a través de herramientas que están conectadas a la base de datos. Esto es especialmente útil cuando se crean informes, se usan herramientas comerciales de BI o de integración de datos, o cualquier aplicación que no se puede cambiar. Con una consulta elástica, puede realizar consultas en varias bases de datos utilizando la experiencia de conectividad conocida de SQL Server en herramientas como Excel, PowerBI, Tableau o Cognos. Una consulta elástica permite un acceso fácil a una colección completa de bases de datos a través de consultas emitidas por SQL Server Management Studio o Visual Studio, y facilita la consulta entre bases de datos desde Entity Framework u otros entornos ORM. La Figura 1 muestra un escenario en el que una aplicación en la nube existente (que utiliza la biblioteca del cliente de base de datos elástica) se basa en un nivel de datos escalado, y una consulta elástica para informes entre bases de datos.

Ya leida la teoria vamos a la practica.

1 – Crear las bases de datos de muestra.

Para empezar, necesitamos crear dos bases de datos, Customers y Orders (Clientes y Ordenes ESP), ya sea en el mismo o en diferentes servidores lógicos.

Ejecute las siguientes consultas en la base de datos Orders para crear la tabla OrderInformation e ingresar los datos de muestra.


CREATE TABLE [dbo].[OrderInformation](
[OrderID] [int] NOT NULL,
[CustomerID] [int] NOT NULL
)
INSERT INTO [dbo].[OrderInformation] ([OrderID], [CustomerID]) VALUES (123, 1)
INSERT INTO [dbo].[OrderInformation] ([OrderID], [CustomerID]) VALUES (149, 2)
INSERT INTO [dbo].[OrderInformation] ([OrderID], [CustomerID]) VALUES (857, 2)
INSERT INTO [dbo].[OrderInformation] ([OrderID], [CustomerID]) VALUES (321, 1)
INSERT INTO [dbo].[OrderInformation] ([OrderID], [CustomerID]) VALUES (564, 8)

Ahora, ejecute la consulta siguiente en la base de datos de Customers para crear la tabla CustomerInformation e ingrese los datos de muestra.


CREATE TABLE [dbo].[CustomerInformation](
[CustomerID] [int] NOT NULL,
[CustomerName] [varchar](50) NULL,
[Company] [varchar](50) NULL
CONSTRAINT [CustID] PRIMARY KEY CLUSTERED ([CustomerID] ASC)
)
INSERT INTO [dbo].[CustomerInformation] ([CustomerID], [CustomerName], [Company]) VALUES (1, 'Jack', 'ABC')
INSERT INTO [dbo].[CustomerInformation] ([CustomerID], [CustomerName], [Company]) VALUES (2, 'Steve', 'XYZ')
INSERT INTO [dbo].[CustomerInformation] ([CustomerID], [CustomerName], [Company]) VALUES (3, 'Lylla', 'MNO')

2 – Crear objetos de base de datos.

Base de datos de clave maestra y credenciales

  1. Abra SQL Server Management Studio o SQL Server Data Tools en Visual Studio.
  2. Conéctese a la base de datos Pedidos y ejecute los siguientes comandos T-SQL:

    CREATE MASTER KEY ENCRYPTION BY PASSWORD = 'password';
    CREATE DATABASE SCOPED CREDENTIAL ElasticDBQueryCred
    WITH IDENTITY = 'username',
    SECRET = 'password';

    El “username” y el “password” deben ser el nombre de usuario y la contraseña utilizados para iniciar sesión en la base de datos de Customers. La autenticación con Azure Active Directory con consultas elásticas no es actualmente compatible.

Fuentes de datos externas

Para crear una fuente de datos externa, ejecute el siguiente comando en la base de datos Orders


CREATE EXTERNAL DATA SOURCE MyElasticDBQueryDataSrc WITH
(TYPE = RDBMS,
LOCATION = 'server_name.database.windows.net',
DATABASE_NAME = 'Customers',
CREDENTIAL = ElasticDBQueryCred,
) ;

Tablas externas

Cree una tabla externa en la base de datos Orders, que coincida con la definición de la tabla CustomerInformation:


CREATE EXTERNAL TABLE [dbo].[CustomerInformation]
( [CustomerID] [int] NOT NULL,
[CustomerName] [varchar](50) NOT NULL,
[Company] [varchar](50) NOT NULL)
WITH
( DATA_SOURCE = MyElasticDBQueryDataSrc)

3 – Ejecute una consulta de muestra T-SQL de base de datos elástica.

Una vez que haya definido su fuente de datos externa y sus tablas externas, ahora puede usar T-SQL para consultar sus tablas externas. Ejecute esta consulta en la base de datos de pedidos:


SELECT OrderInformation.CustomerID, OrderInformation.OrderId, CustomerInformation.CustomerName, CustomerInformation.Company
FROM OrderInformation
INNER JOIN CustomerInformation
ON CustomerInformation.CustomerID = OrderInformation.CustomerID

4 – Costo

Actualmente, la función de consulta de base de datos elástica está incluida en el costo de su base de datos SQL de Azure.

 


De esta manera no tienes excusa para poder enlazar una o más bases de datos en una consulta de TSQL y lo mejor que desde Azure.

Espero les sea de utilidad la información y que la puedan implementar en sus trabajos o en algún caso poco común que les pueda ocurrir.

Nos vemos en un próximo articulo 🙂