Integración de REST REST API T-SQL en SQL Server 2025: Optimización de las copias de seguridad de snapshots de T-SQL

Este artículo apareció originalmente en el blog de Anthony Nocentino. Se ha vuelto a publicar con el crédito y consentimiento del autor.

En esta publicación, lo guiaré a través de un guión de T-SQL que crea snapshots consistentes con la aplicación en Pure Storage^®FlashArray^™, todo desde SQL Server, sin herramientas externas. SQL Server 2025 presenta una nueva función potente: el procedimiento sp_invoke_external_rest_endpoint almacenado. Esta mejora hace que sea más fácil que nunca llamar a las API de REST directamente desde T-SQL. Al combinar esta nueva capacidad con la API de Pure Storage, podemos organizar las operaciones de snapshots sin problemas, sin necesidad de herramientas externas ni scripts.

Si ha estado siguiendo mi serie “Uso de la copia de seguridad de snapshots T-SQL”, sabe que esta función ofrece enormes beneficios para entornos de bases de datos grandes. Hoy, analizaremos cómo implementar esto directamente en T-SQL al aprovechar la capacidad de SQL Server para llamar a los puntos finales REST externos, sin necesidad de PowerShell.

ectamente en T-SQL al aprovechar la capacidad de SQL Server para llamar a puntos finales REST externos, no se requiere PowerShell.

Puede tomar todo el guiónaquí.

Habilitación del punto final REST en SQL Server 2025

Primero, asegurémonos de que podamos conectarnos a puntos finales REST externos:

sp_configure 'external rest endpoint enabled', 1;
RECONFIGURE WITH OVERRIDE;

Esto habilita la función de punto final REST de SQL Server, que permite que nuestro SQL Server realice llamadas salientes a la API REST. Esto es fundamental para conectarse a la API de FlashArray para activar snapshots.

Es importante tener en cuenta sp_invoke_external_rest_endpointquerequiere que todos los puntos finales usen HTTPS con cifrado TLS, y el certificado debe ser confiable por el sistema operativo subyacente que aloja la instancia de SQL Server.

Autenticación con FlashArray

A continuación, estableceremos una sesión segura con FlashArray de Pure Storage utilizando el nuevo procedimiento sp_invoke_external_rest_endpointalmacenado de SQL Server 2025. Esta función representa un avance significativo en las capacidades de SQL Server, lo que nos permite realizar llamadas de REST API directamente desde T-SQL sin secuencias de comandos externas.

Para autenticar un FlashArray, primero enviamos untoken API conpermisos suficientes al punto final de inicio de sesión de FlashArray. Tras la autenticación exitosa, FlashArray devuelve un token de autenticación en los encabezados de respuesta, lo que se convierte en nuestra credencial de sesión para todas las operaciones de API posteriores en esta sesión. Este modelo de autenticación basado en tokens proporciona un mecanismo seguro y limitado por tiempo para las interacciones de API mientras mantiene un seguimiento de auditoría claro de las operaciones.

En el siguiente código, ejecutaremos esta solicitud de autenticación y luego extraeremos el token de autorización de la respuesta JSON para crear nuestros encabezados de autorización para las llamadas posteriores a la API REST.

DECLARE @ret INT, @response NVARCHAR(MAX), @AuthToken NVARCHAR(100), @MyHeaders NVARCHAR(100);

EXEC @ret = sp_invoke_external_rest_endpoint
 @url = N'https://flasharray1.purestorage.com/api/2.36/login',
 @headers = N'{"api-token":"PASTE_YOUR_TOKEN_HERE"}',
 @response = @response OUTPUT;

PRINT 'Login Return Code: ' + CAST(@ret AS NVARCHAR(10))
PRINT 'Login Response: ' + @response

Manejo de errores y extracción de tokens

A continuación, verificaremos el éxito del inicio de sesión y extraeremos el token de autenticación. Si el código de devolución de FlashArray no es 0, imprimiremos un mensaje de error y saldremos. Asumiendo el éxito, leeremos eltoken de autorización de la respuesta de inicio de sesión. Tenga en cuenta que la clave de token debe incluir comillas dobles"x-auth-token"para garantizar JSON_VALUEque pueda analizarse correctamente. Una vez extraído, usaremos el token para construir el encabezado de autorización para las llamadas posteriores de REST API a la matriz.

if ( @ret <> 0 )
    BEGIN
        PRINT 'Error in REST call, unable to login to the array.'
        RETURN
    END

SET @AuthToken = JSON_VALUE(@response, '$.response.headers."x-auth-token"'); 
SET @MyHeaders = N'{"x-auth-token":"' + @AuthToken + '", "Content-Type":"application/json"}'

PRINT 'Headers: ' + @MyHeaders

Congelación de la base de datos para snapshots

El paso crucial viene: suspender la I/O de escritura de la base de datos para prepararse para la instantánea. Este comando utiliza la función de copia de seguridad de snapshots T-SQL de SQL Server 2022 para congelar las operaciones de I/O de escritura en la base de datos. La base de datos sigue siendo legible, pero las operaciones de escritura se suspenden hasta que completamos nuestro proceso de snapshot. Esto garantiza que obtengamos una instantánea consistente con la aplicación.

ALTER DATABASE [TestDB1] SET SUSPEND_FOR_SNAPSHOT_BACKUP = ON

Toma de la instantánea de almacenamiento

Con I/O escritura congelada en la base de datos, estamos listos para tomar una instantánea en FlashArray. El siguiente paso es llamar al punto finalprotection-group-snapshotsREST RESTpara iniciar una copia de seguridad instantánea del grupo de protección.

EXEC @ret = sp_invoke_external_rest_endpoint
 @url = N'https://flasharray1.purestorage.com/api/2.36/protection-group-snapshots',
 @headers = @MyHeaders,
 @payload = N'{"source_names":"aen-sql-25-a-pg"}',    
 @response = @response OUTPUT;

PRINT 'Snapshot Return Code: ' + CAST(@ret AS NVARCHAR(10))
PRINT 'Snapshot Response: ' + @response

Aquí, llamamos al punto final de snapshots del grupo de protección de API REST de FlashArray para crear una instantánea de un grupo de protección llamadoaen-sql-25-a-pg. El grupo de protección debe contener todos los volúmenes donde se almacenan los archivos de nuestra base de datos. FlashArray creará una instantánea en un momento determinado de todos los volúmenes de este grupo de protección.

Extraer el nombre de la instantánea y crear la copia de seguridad

En el siguiente paso, extraemos el nombre de la instantánea de la respuesta JSON de FlashArray usandoJSON_VALUE(@response, '$.result.items[0].name'). Este nombre se incluirá en la descripción de medios de copia de seguridad como parte de una copia de seguridad solo de metadatos. Si FlashArray devuelve un código de éxito (código de devolución = 0), procederemos con la copia de seguridad usando el comandoBACKUP DATABASE y la METADATA_ONLYopción. Esto crea un archivo de copia de seguridad liviano que contiene solo los metadatos de la base de datos y una referencia a la snapshot de FlashArray en MEDIADESCRIPTION. Al almacenar el nombre de la snapshot en MEDIADESCRIPTION, es más fácil identificar y ubicar la snapshot de FlashArray correspondiente cuando se realiza una operación de restauración.

Si la operación de snapshot falla, registramos un mensaje de error y dessuspendemos inmediatamente la base de datos para reanudar la I/O escritura normal.

DECLARE @SnapshotName NVARCHAR(100)
SET @SnapshotName = JSON_VALUE(@response, '$.result.items[0].name')

if ( @ret = 0 ) 
    BEGIN
        BACKUP DATABASE [TestDB1] TO DISK='SnapshotBack.bkm' WITH METADATA_ONLY, MEDIADESCRIPTION=@SnapshotName
        PRINT 'Snapshot backup successful. Snapshot Name: ' + @SnapshotName
    END
ELSE 
    BEGIN
        ALTER DATABASE [TestDB1] SET SUSPEND_FOR_SNAPSHOT_BACKUP = OFF
        PRINT 'Error in REST call, snapshot backup failed. Database unsuspended.'
    END

Verificación del registro de errores de SQL Server

Para verificar nuestra operación de copia de seguridad, verificamos el registro de errores de SQL Server.

El registro de errores de SQL Server confirma una copia de seguridad exitosa de la base de datos TestDB1 solo para metadatos. El registro muestra que la base de datos se suspendió, la I/O escritura se congeló y la instantánea se tomó antes de que se reanudara la I/O de manera segura. Dado que esta es una copia de seguridad solo de metadatos, no se procesaron páginas de datos; solo se capturaron y escribieron metadatos en el archivo.bkm especificado. Esto garantiza una instantánea consistente con la aplicación con un impacto mínimo en la disponibilidad de la base de datos.

EXEC xp_readerrorlog 0, 1, NULL, NULL, NULL, NULL, N'desc'

2025-05-09 12:03:25.120 Backup  BACKUP DATABASE successfully processed 0 pages in 0.004 seconds (0.000 MB/sec).
2025-05-09 12:03:25.090 Backup  Database backed up. Database: TestDB1, creation date(time): 2025/04/30(16:05:02), pages dumped: 394061770, first LSN: 80323:19757:39, last LSN: 80323:19774:1, number of dump devices: 1, device information: (FILE=12, TYPE=DISK: {'C:\Program Files\Microsoft SQL Server\MSSQL17.MSSQLSERVER\MSSQL\Backup\SnapshotBack.bkm'}). This is an informational message only. No user action is required.
2025-05-09 12:03:25.080 spid86  Database 'TestDB1' originally suspended for snapshot backup in session 86 successfully resumed in session 86.
2025-05-09 12:03:25.080 spid86  Database 'TestDB1' released suspend locks in session 86.
2025-05-09 12:03:25.080 spid86  I/O was resumed on database TestDB1. No user action is required.
2025-05-09 12:03:25.080 spid86  I/O is frozen on database TestDB1. No user action is required. However, if I/O is not resumed promptly, you could cancel the backup.
2025-05-09 12:03:22.110 spid86  Database 'TestDB1' successfully suspended for snapshot backup in session 86.
2025-05-09 12:03:22.110 spid86  I/O is frozen on database TestDB1. No user action is required. However, if I/O is not resumed promptly, you could cancel the backup.
2025-05-09 12:03:22.070 spid86  Database 'TestDB1' acquired suspend locks in session 86.
2025-05-09 12:03:22.070 spid86  Setting database option suspend_for_snapshot_backup to ON for database 'TestDB1'.

Este es el resultado de las declaraciones impresas que usamos anteriormente. La copia de seguridad de la snapshot se completó correctamente: el sistema se autenticó con FlashArray, suspendió TestDB1 para congelar I/O, creó la snapshot (aen-sql-25-a-pg.17), reanudó I/O y finalizó con una copia de seguridad solo de metadatos, todo confirmado a través de registros de SQL Server y respuestas de API.

Login Return Code: 0
Login Response: {"response":{"status":{"http":{"code":200,"description":""}},"headers":{"Date":"Fri, 09 May 2025 12:03:22 GMT","Content-Length":"37","Content-Type":"application\/json","Server":"nginx","x-auth-token":"75b2b984-a238-44ce-adbd-ff19decab148","strict-transport-security":"max-age=31536000; includeSubDomains;","content-security-policy":"frame-ancestors 'none'","x-frame-options":"DENY","x-content-type-options":"nosniff","x-xss-protection":"1; mode=block","x-request-id":"bdc6bbff70105c00fdeac8b0a1af565c"}},"result":{"items":[{"username":"anocentino"}]}}

Headers: {"x-auth-token":"75b2b984-a238-44ce-adbd-ff19decab148", "Content-Type":"application/json"}

Database 'TestDB1' acquired suspend locks in session 86.
I/O is frozen on database TestDB1. No user action is required. However, if I/O is not resumed promptly, you could cancel the backup.
Database 'TestDB1' successfully suspended for snapshot backup in session 86.

Snapshot Return Code: 0
Snapshot Response: {"response":{"status":{"http":{"code":200,"description":""}},"headers":{"Date":"Fri, 09 May 2025 12:03:22 GMT","Content-Length":"340","Content-Type":"application\/json","Server":"nginx","x-auth-token":"75b2b984-a238-44ce-adbd-ff19decab148","strict-transport-security":"max-age=31536000; includeSubDomains;","content-security-policy":"frame-ancestors 'none'","x-frame-options":"DENY","x-content-type-options":"nosniff","x-xss-protection":"1; mode=block","x-request-id":"e3089939224baca84d6ad69b485855de"}},"result":{"items":[{"name":"aen-sql-25-a-pg.17","id":"32e86de3-a3ee-3ae0-f74c-4bf5a7f74744","space":null,"source":{"name":"aen-sql-25-a-pg","id":"b6660b61-a8de-ae1b-cb65-e3045d13b5ba"},"suffix":"17","destroyed":false,"created":1746792202183,"pod":{"name":null,"id":null},"time_remaining":null,"eradication_config":{"manual_eradication":"enabled"}}]}}

I/O was resumed on database TestDB1. No user action is required.
Database 'TestDB1' released suspend locks in session 86.
Database 'TestDB1' originally suspended for snapshot backup in session 86 successfully resumed in session 86.
Processed 0 pages for database 'TestDB1', file 'test_data_01' on file 12.
Processed 0 pages for database 'TestDB1', file 'test_data_02' on file 12.
Processed 0 pages for database 'TestDB1', file 'test_data_03' on file 12.
Processed 0 pages for database 'TestDB1', file 'test_data_04' on file 12.
Processed 0 pages for database 'TestDB1', file 'test_data_05' on file 12.
Processed 0 pages for database 'TestDB1', file 'test_data_06' on file 12.
Processed 0 pages for database 'TestDB1', file 'test_data_07' on file 12.
Processed 0 pages for database 'TestDB1', file 'test_data_08' on file 12.
BACKUP DATABASE successfully processed 0 pages in 0.004 seconds (0.000 MB/sec).

Snapshot backup successful. Snapshot Name: aen-sql-25-a-pg.17

Resumen de las cosas

Este ejemplo destaca cómo el nuevo sp_invoke_external_rest_endpointprocedimiento de SQL Server 2025transforma la automatización de la copia de seguridad. Anteriormente, la integración con los sistemas de almacenamiento requería PowerShell o herramientas externas. Ahora, podemos realizar llamadas de REST API de forma nativa desde T-SQL, lo que agiliza los flujos de trabajo y reduce la complejidad.

Beneficios clave:

Integración de REST nativa: Por último, podemos realizar llamadas API directamente desde T-SQL sin pasar a PowerShell u otros idiomas de scripting.
Automatización simplificada: Desarrolle todo su flujo de trabajo de copia de seguridad en un solo lugar, sin más contexto que cambie entre diferentes herramientas
Dependencias reducidas: Elimine esas capas intermedias entre SQL Server y sus sistemas de almacenamiento: menos piezas móviles significa menos puntos de falla potenciales.
Seguridad mejorada: Mantenga su autenticación centralizada dentro de SQL Server en lugar de hacerlo en archivos de script externos
Mejor rendimiento: La ejecución de operaciones dentro de SQL Server significa menores costos generales y tiempos de ejecución más rápidos.

Esta función elimina el cambio de contexto y aporta capacidades de automatización modernas al motor de la base de datos. Solo asegúrese de almacenar de forma segura los tokens de API e implementar el manejo de errores adecuado en la producción.

La conclusión es que la integración REST de SQL Server 2025 es una gran victoria para los administradores de bases de datos que administran entornos complejos a gran escala.