Conexión y consulta de Azure SQL Database mediante Python y el controlador mssql-python

Se aplica a:Azure SQL Database

En este inicio rápido se describe cómo conectar una aplicación a una base de datos de Azure SQL Database y realizar consultas mediante Python y el controlador mssql-python. El controlador mssql-python tiene compatibilidad integrada con la autenticación de Microsoft Entra, lo que simplifica las conexiones sin contraseña. Puede consultar más información sobre las conexiones sin contraseña en el centro de recursos sin contraseña.

Requisitos previos

Una suscripción de Azure.
Una base de datos Azure SQL configurada con autenticación Microsoft Entra. Puede crear uno mediante el inicio rápido: Creación de una base de datos única: Azure SQL Database. Como alternativa, puede usar una base de datos SQL en Microsoft Fabric.
Visual Studio Code con la extensión de Python.
Python 3.10 o posterior.
La CLI de Azure para la autenticación sin contraseña (funciona en Windows, macOS y Linux).

Configuración de la base de datos

Las conexiones seguras sin contraseña a Azure SQL Database requieren una cierta configuración de la base de datos. Compruebe la siguiente configuración en el servidor lógico de Azure para conectarse correctamente a Azure SQL Database tanto en el entorno local como en un entorno hospedado:

En el caso de las conexiones de desarrollo local, asegúrese de que el servidor lógico está configurado para permitir que la dirección IP de la máquina local y otros servicios de Azure se conecten:
- Vaya a la página Redes del servidor.
- Active o desactive el botón de radio Redes seleccionadas para mostrar opciones de configuración adicionales.
- Seleccione Agregar la dirección IPv4 de cliente (xx.xx.xx.xx) para agregar una regla de firewall que habilitará las conexiones desde la dirección IPv4 del equipo local. Como alternativa, también puede seleccionar + Agregar una regla de firewall para especificar una dirección IP específica de su elección.
- Asegúrese de que la casilla Permitir que los servicios y recursos de Azure accedan a este servidor esté seleccionada.
  Advertencia
  
  La habilitación de la opción Permitir que los servicios y recursos de Azure accedan a este servidor no es un procedimiento de seguridad recomendado para escenarios de producción. Las aplicaciones reales deben implementar enfoques más seguros, como restricciones de firewall más fuertes o configuraciones de red virtual.
  
  Puede consultar más información sobre las configuraciones de seguridad de la base de datos en los siguientes recursos:
  - Configuración de reglas de firewall de Azure SQL Database.
  - Configuración de una red virtual con puntos de conexión privados.
El servidor también debe tener habilitada la autenticación de Microsoft Entra y tener asignada una cuenta de administrador de Microsoft Entra. Para las conexiones de desarrollo local, la cuenta de administrador de Microsoft Entra debe ser una cuenta que también puede iniciar sesión en Visual Studio o en la CLI de Azure localmente. Puede comprobar si el servidor tiene habilitada la autenticación de Microsoft Entra en la página de Microsoft Entra ID del servidor lógico.
Si usa una cuenta personal de Azure, asegúrese de que ha instalado y configurado Microsoft Entra para Azure SQL Database con el fin de asignar su cuenta como administrador del servidor. Si usa una cuenta corporativa, es probable que Microsoft Entra ID ya esté configurado.

Creación del proyecto

Cree un nuevo proyecto de Python en Visual Studio Code.

Abra Visual Studio Code, cree una carpeta para el proyecto y cambie a ese directorio.
```
mkdir python-sql-azure
cd python-sql-azure
```

Cree un entorno virtual para la aplicación.

Windows
macOS y Linux

py -m venv .venv
.venv\scripts\activate

python3 -m venv .venv
source .venv/bin/activate

Cree un nuevo archivo de Python denominado app.py.

Instalación del controlador mssql-python

Para conectarse a Azure SQL Database mediante Python, instale el controlador mssql-python. Este controlador tiene compatibilidad integrada con la autenticación de Microsoft Entra, lo que elimina la necesidad de controlar tokens manuales. En este inicio rápido, también instalará los paquetes fastapi, uvicorn y pydantic para crear y ejecutar una API.

Nota:

En macOS y Linux, se requieren dependencias del sistema antes de instalar mssql-python. Consulte Instalación del paquete mssql-python para obtener instrucciones específicas de la plataforma.

Cree un archivo llamado requirements.txt con las siguientes líneas:
```
mssql-python
fastapi
uvicorn[standard]
pydantic
python-dotenv
```
Instale los requisitos.
```
pip install -r requirements.txt
```

Configuración de la cadena de conexión local

Para el desarrollo local, cree un .env archivo en la carpeta del proyecto para almacenar la cadena de conexión. Esto mantiene las credenciales fuera de tu código y del control de versiones.

En la carpeta del proyecto, cree un nuevo archivo denominado .env.
Agregue la variable AZURE_SQL_CONNECTIONSTRING con su cadena de conexión. Reemplace los marcadores de posición <database-server-name> y <database-name> por sus propios valores.

El controlador mssql-python tiene compatibilidad integrada con la autenticación de Microsoft Entra. Use el Authentication parámetro para especificar el método de autenticación.

ActiveDirectoryDefault detecta automáticamente las credenciales de varios orígenes sin necesidad de inicio de sesión interactivo. Esta es la opción recomendada para el desarrollo local.

Para obtener la experiencia de desarrollo local más confiable, inicie sesión primero con la CLI de Azure:

az login

A continuación, use este formato de cadena de conexión en el .env archivo:

AZURE_SQL_CONNECTIONSTRING=Server=<database-server-name>.database.windows.net;Database=<database-name>;Authentication=ActiveDirectoryDefault;Encrypt=yes;TrustServerCertificate=no;

ActiveDirectoryDefault evalúa las credenciales en el orden siguiente:

Variables de entorno (para credenciales de entidad de servicio)
Identidad administrada (cuando se ejecuta en Azure)
CLI de Azure (desde az login)
Visual Studio (solo Windows)
Azure PowerShell (desde Connect-AzAccount)

Sugerencia

En el caso de las aplicaciones de producción, use el método de autenticación específico para su escenario para evitar la latencia de detección de credenciales:

Azure App Service/Functions: uso ActiveDirectoryMSI (identidad administrada)
Inicio de sesión de usuario interactivo: Use ActiveDirectoryInteractive
Entidad de servicio: Usar ActiveDirectoryServicePrincipal

En Windows, La autenticación interactiva de Microsoft Entra puede usar la tecnología de autenticación multifactor de Microsoft Entra para configurar una conexión. En este modo, aparece un cuadro de diálogo autenticación de Azure y le permite escribir las credenciales para completar la conexión.

AZURE_SQL_CONNECTIONSTRING=Server=<database-server-name>.database.windows.net;Database=<database-name>;Authentication=ActiveDirectoryInteractive;Encrypt=yes;TrustServerCertificate=no;

Puede autenticarse directamente en una instancia de SQL Server mediante un nombre de usuario y una contraseña.

AZURE_SQL_CONNECTIONSTRING=Server=<database-server-name>.database.windows.net;Database=<database-name>;UID=<user-name>;PWD=<user-password>;Encrypt=yes;TrustServerCertificate=no;

Advertencia

Tenga cuidado al administrar cadenas de conexión que contengan secretos como nombres de usuario, contraseñas o claves de acceso. Estos secretos no se deben almacenar en el control de código fuente ni colocarlos en ubicaciones no seguras a las que puedan ser accedidos por usuarios no autorizados. Agregue .env al archivo .gitignore para evitar la confirmación accidental de secretos.

Para conectarse a una base de datos SQL en Microsoft Fabric, use los mismos métodos de autenticación. El nombre del servidor sigue el formato fabric.

En las máquinas unidas a un dominio de Windows, use ActiveDirectoryIntegrated para la autenticación sin problemas sin pasos adicionales:

AZURE_SQL_CONNECTIONSTRING=Server=<workspace-guid>.database.fabric.microsoft.com,1433;Database=<database-name>;Encrypt=yes;TrustServerCertificate=no;Authentication=ActiveDirectoryIntegrated;

En macOS, Linux o Windows que no sea de dominio, use ActiveDirectoryDefault después de iniciar sesión con la CLI de Azure (az login):

AZURE_SQL_CONNECTIONSTRING=Server=<workspace-guid>.database.fabric.microsoft.com,1433;Database=<database-name>;Encrypt=yes;TrustServerCertificate=no;Authentication=ActiveDirectoryDefault;

Puede encontrar la cadena de conexión de la base de datos SQL de Fabric en la configuración de su base de datos dentro del portal de Fabric.

Puede obtener los detalles para crear la cadena de conexión en Azure Portal:

Vaya a Azure SQL Server, seleccione la página Bases de datos SQL para buscar el nombre de la base de datos y seleccione la base de datos.
En la base de datos, vaya a la página Información general para obtener el nombre del servidor.

Adición de código para conectarse a Azure SQL Database

En la carpeta del proyecto, cree un archivo app.py y agregue el código de ejemplo. Este código crea una API que:

Carga la configuración de un archivo .env mediante python-dotenv.
Recupera una cadena de conexión de Azure SQL Database de una variable de entorno.
Crea una tabla Persons en la base de datos durante el inicio (solo para escenarios de prueba).
Define una función para recuperar todos los registros Person de la base de datos.
Define una función para recuperar un registro Person de la base de datos.
Define una función para agregar nuevos registros Person a la base de datos.

from os import getenv
from typing import Union
from dotenv import load_dotenv
from fastapi import FastAPI
from pydantic import BaseModel
from mssql_python import connect

load_dotenv()

class Person(BaseModel):
    first_name: str
    last_name: Union[str, None] = None

connection_string = getenv("AZURE_SQL_CONNECTIONSTRING")

app = FastAPI()

@app.get("/")
def root():
    print("Root of Person API")
    try:
        conn = get_conn()
        cursor = conn.cursor()

        # Table should be created ahead of time in production app.
        cursor.execute("""
            IF NOT EXISTS (SELECT * FROM sys.tables WHERE name = 'Persons')
            CREATE TABLE Persons (
                ID int NOT NULL PRIMARY KEY IDENTITY,
                FirstName varchar(255),
                LastName varchar(255)
            );
        """)

        conn.commit()
        conn.close()
    except Exception as e:
        # Table might already exist
        print(e)
    return "Person API"

@app.get("/all")
def get_persons():
    rows = []
    with get_conn() as conn:
        cursor = conn.cursor()
        cursor.execute("SELECT * FROM Persons")

        for row in cursor.fetchall():
            print(row.FirstName, row.LastName)
            rows.append(f"{row.ID}, {row.FirstName}, {row.LastName}")
    return rows

@app.get("/person/{person_id}")
def get_person(person_id: int):
    with get_conn() as conn:
        cursor = conn.cursor()
        cursor.execute("SELECT * FROM Persons WHERE ID = ?", (person_id,))

        row = cursor.fetchone()
        return f"{row.ID}, {row.FirstName}, {row.LastName}"

@app.post("/person")
def create_person(item: Person):
    with get_conn() as conn:
        cursor = conn.cursor()
        cursor.execute("INSERT INTO Persons (FirstName, LastName) VALUES (?, ?)",
                       (item.first_name, item.last_name))
        conn.commit()

    return item

def get_conn():
    """Connect using mssql-python with built-in Microsoft Entra authentication."""
    conn = connect(connection_string)
    conn.setautocommit(True)
    return conn

Advertencia

El código de ejemplo muestra instrucciones SQL sin procesar, que no se deben usar en el código de producción. En su lugar, use un paquete de asignador relacional de objetos (ORM) como SqlAlchemy que genera una capa de objetos más segura para acceder a la base de datos.

Ejecución y prueba local de la aplicación

La aplicación está lista para probarse localmente.

Ejecute el archivo app.py en Visual Studio Code.
```
uvicorn app:app --reload
```
En la página de la interfaz de usuario de Swagger de la aplicación http://127.0.0.1:8000/docs, expanda el método POST y seleccione Probar.

También puede probar /redoc para ver otra versión de la documentación generada para la API.
Modifique el código JSON de ejemplo para incluir los valores de nombre y el apellido. Seleccione Ejecutar para agregar un nuevo registro a la base de datos. La API devuelve una respuesta exitosa.
Expanda el GET método en la página de la interfaz de usuario de Swagger y seleccione Pruébelo. Elija Ejecutar y se devolverá la persona que acaba de crear.

Implementación en Azure App Service

La aplicación está lista para implementarse en Azure.

Cree un archivo start.sh para que gunicorn en Azure App Service pueda ejecutar uvicorn. El archivo start.sh tiene una línea:
```
gunicorn -w 4 -k uvicorn.workers.UvicornWorker app:app
```
Utiliza az webapp up para implementar el código en App Service. (Puede usar la opción -dryrun para ver lo que hace el comando sin crear el recurso).
```
az webapp up \
    --resource-group <resource-group-name> \
    --name <web-app-name>         
```

Usa el comando az webapp config set para configurar App Service a fin de usar el archivo start.sh.

az webapp config set \
    --resource-group <resource-group-name> \
    --name <web-app-name> \
    --startup-file start.sh

Use el comando az webapp identity assign para habilitar una identidad administrada asignada por el sistema para la instancia de App Service.
```
az webapp identity assign \
    --resource-group <resource-group-name> \
    --name <web-app-name>
```
En este inicio rápido, se usa una identidad administrada asignada por el sistema para fines de demostración. Una identidad administrada asignada por el usuario es más eficaz en una mayor variedad de escenarios. Para más información, consulte Procedimientos recomendados para identidades administradas. Para obtener un ejemplo de uso de una identidad administrada asignada por el usuario con mssql-python, consulte Migración de una aplicación de Python para usar conexiones sin contraseña con Azure SQL Database.

Conexión de App Service a Azure SQL Database

En la sección Configurar la base de datos, ha configurado las redes y la autenticación de Microsoft Entra para el servidor de bases de datos de Azure SQL. En esta sección, realizará la configuración de la base de datos y configurará App Service con una cadena de conexión para acceder al servidor de bases de datos.

Para ejecutar estos comandos, puede usar cualquier herramienta o IDE que pueda conectarse a Azure SQL Database, incluido SQL Server Management Studio (SSMS) y Visual Studio Code con la extensión MSSQL. También puede usar Azure Portal como se describe en Inicio rápido: Uso del editor de consultas de Azure Portal para consultar Azure SQL Database.

Agregue un usuario a la base de datos de Azure SQL con comandos SQL para crear un usuario y un rol para el acceso sin contraseña.
```
CREATE USER [<web-app-name>] FROM EXTERNAL PROVIDER
ALTER ROLE db_datareader ADD MEMBER [<web-app-name>]
ALTER ROLE db_datawriter ADD MEMBER [<web-app-name>]
```
Para obtener más información, vea Usuarios de base de datos independiente: hacer que la base de datos sea portátil. Para ver un ejemplo que muestra el mismo principio pero aplicado a la máquina virtual de Azure, consulte Tutorial: Uso de una identidad administrada asignada por el sistema de una máquina virtual Windows para acceder a Azure SQL. Para más información sobre los roles asignados, consulte Roles fijos de base de datos.

Si deshabilita y luego habilita la identidad administrada asignada por el sistema de App Service, quite el usuario y vuelva a crearlo. Ejecute DROP USER [<web-app-name>] y vuelva a ejecutar los comandos CREATE y ALTER. Para ver a los usuarios, use SELECT * FROM sys.database_principals.
Use el comando az webapp config appsettings set para agregar una configuración de aplicación para la cadena de conexión.
```
az webapp config appsettings set \
    --resource-group <resource-group-name> \
    --name <web-app-name> \
    --settings AZURE_SQL_CONNECTIONSTRING="<connection-string>"
```
Para la aplicación implementada, la cadena de conexión debe ser similar a la siguiente:
```
Server=<database-server-name>.database.windows.net;Database=<database-name>;Authentication=ActiveDirectoryMSI;Encrypt=yes;TrustServerCertificate=no;
```
Reemplace <database-server-name> y <database-name> por sus propios valores.

La cadena de conexión sin contraseña no contiene un nombre de usuario ni una contraseña. En su lugar, cuando la aplicación se ejecuta en Azure, el controlador mssql-python usa el ActiveDirectoryMSI modo de autenticación para autenticarse automáticamente mediante la identidad administrada de App Service.

Prueba de la aplicación implementada

Vaya a la dirección URL de la aplicación para probar que funciona la conexión a Azure SQL Database. Puede encontrar la dirección URL de la aplicación en la página de información general de App Service.

https://<web-app-name>.azurewebsites.net

Anexe /docs a la dirección URL para ver la interfaz de usuario de Swagger y probar los métodos de API.

¡Enhorabuena! La aplicación ahora está conectada a Azure SQL Database en entornos locales y hospedados.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-02-11