Integrazione delle API REST T-SQL in SQL Server 2025: Semplificazione dei backup delle snapshot T-SQL

Questo articolo è apparso originariamente sul blog di Anthony Nocentino. È stato ripubblicato con il credito e il consenso dell’autore.

In questo post ti illustrerò uno script T-SQL che crea snapshot coerenti con le applicazioni su Pure Storage^® FlashArray^™, il tutto all’interno di SQL Server, senza strumenti esterni. SQL Server 2025 introduce una nuova potente funzionalità: la procedura sp_invoke_external_rest_endpoint memorizzata. Questo miglioramento rende più facile che mai chiamare le API REST direttamente da T-SQL. Combinando questa nuova funzionalità con l’API Pure Storage, possiamo orchestrare le operazioni delle snapshot in modo trasparente, senza la necessità di strumenti o script esterni.

Se hai seguito la mia serie “Uso del backup delle snapshot T-SQL”, sai che questa funzionalità offre enormi vantaggi per gli ambienti di database di grandi dimensioni. Oggi vedremo come implementarlo direttamente in T-SQL sfruttando la capacità di SQL Server di chiamare endpoint REST esterni, senza richiedere PowerShell.

In T-SQL, sfruttando la capacità di SQL Server di chiamare endpoint REST esterni, non è necessario PowerShell.

Puoi trovare l’intero scriptqui.

Abilitazione dell’endpoint REST in SQL Server 2025

Per prima cosa, ci assicuriamo di poterci connettere agli endpoint REST esterni:

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

Ciò abilita la funzionalità dell’endpoint REST di SQL Server, che consente al nostro SQL Server di effettuare chiamate REST API in uscita. Questo è fondamentale per connettersi all’API di FlashArray e attivare le snapshot.

È importante notare cherichiede che tutti gli endpoint sp_invoke_external_rest_endpointutilizzino HTTPS con crittografia TLS e che il certificato deve essere attendibile dal sistema operativo sottostante che ospita l’istanza SQL Server.

Autenticazione con FlashArray

Successivamente, stabiliremo una sessione sicura con Pure Storage FlashArray utilizzando la procedura di sp_invoke_external_rest_endpointnewstored di SQL Server 2025. Questa funzionalità rappresenta un progresso significativo nelle funzionalità di SQL Server, consentendoci di effettuare chiamate API REST direttamente da T-SQL senza script esterni.

Per l’autenticazione a un FlashArray, inviamo prima un token API con autorizzazioni sufficienti all’endpoint di accesso di FlashArray. Una volta completata correttamente l’autenticazione, FlashArray restituisce anx-auth-tokennelle intestazioni di risposta, che diventano le nostre credenziali di sessione per tutte le operazioni API successive in questa sessione. Questo modello di autenticazione basato su token fornisce un meccanismo sicuro e limitato nel tempo per le interazioni API, mantenendo al tempo stesso un chiaro audit trail delle operazioni.

Nel codice che segue, eseguiremo questa richiesta di autenticazione ed estrarremo il tokenx-authdalla risposta JSON per creare le nostre intestazioni di autorizzazione per le chiamate API REST successive.

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

Gestione degli errori ed estrazione dei token

Successivamente, verificheremo il successo dell’accesso ed estrarremo il token di autenticazione. Se il codice di reso di FlashArray è diverso da 0, verrà visualizzato un messaggio di errore e verrà visualizzato il messaggio di uscita. Ipotizzando il successo, leggeremo il tokenx-authdalla risposta di accesso. Tenere presente che la chiave token deve includere virgolette doppie "x-auth-token" per JSON_VALUEassicurarsidi analizzarla correttamente. Una volta estratto, utilizzeremo il token per costruire l’intestazione di autorizzazione per le successive chiamate API REST all’array.

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

Congelamento del database per le snapshot

Il passaggio cruciale è la sospensione dell’I/O di scrittura del database per prepararsi all’istantanea. Questo comando utilizza la funzionalità di backup snapshot T-SQL di SQL Server 2022 per bloccare le operazioni di I/O di scrittura sul database. Il database rimane leggibile, ma le operazioni di scrittura vengono sospese fino al completamento del processo di snapshot. In questo modo otteniamo una snapshot coerente con le applicazioni.

ALTER DATABASE [TestDB1] SET SUSPEND_FOR_SNAPSHOT_BACKUP = ON

Scattare le snapshot dello storage

Con l’I/O di scrittura bloccato nel database, siamo pronti per scattare una snapshot su FlashArray. Il passo successivo è chiamare l’endpointprotection-group-snapshotsREST RESTper avviare un backup delle snapshot del gruppo di protezione.

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

Qui chiamiamo REST REST APIprotection-group-snapshotsendpoint di FlashArray per creare una snapshot di un gruppo di protezione denominatoaen-sql-25-a-pg. Il gruppo di protezione deve contenere tutti i volumi in cui sono archiviati i file di database. FlashArray creerà una snapshot point-in-time di tutti i volumi in questo gruppo di protezione.

Estrazione del nome dell’istantanea e creazione del backup

Nel prossimo passaggio, estrarremo il nome dello snapshot dalla risposta JSON di FlashArray utilizzandoJSON_VALUE(@response, "$.result.items[0].name"). Questo nome sarà incluso nella descrizione dei supporti di backup come parte di un backup di soli metadati. Se FlashArray restituisce un codice di successo (codice di ritorno = 0), procederemo con il backup utilizzando il comandoBACKUP DATABASE e l’METADATA_ONLYopzione. Questo crea un file di backup leggero che contiene solo i metadati del database e un riferimento allo snapshot FlashArray inMEDIADESCRIPTION. La memorizzazione del nome dello snapshot in MEDIADESCRIPTION facilita l’identificazione e il posizionamento dello snapshot FlashArray corrispondente quando si esegue un’operazione di restore.

Se l’operazione di snapshot non riesce, registriamo un messaggio di errore e annulliamo immediatamente la sospensione del database per riprendere il normale I/O di scrittura.

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

Controllo del registro degli errori di SQL Server

Per verificare il funzionamento del backup, controlliamo il registro degli errori di SQL Server.

Il registro degli errori di SQL Server conferma un backup snapshot di soli metadati del database TestDB1. Il registro mostra che il database è stato sospeso, l’I/O di scrittura è stato bloccato e la snapshot è stata scattata prima che l’I/O fosse ripristinato in modo sicuro. Poiché si tratta di un backup di soli metadati, non sono state elaborate pagine di dati; solo i metadati sono stati acquisiti e scritti nel file bkm specificato. Ciò garantisce una snapshot coerente con le applicazioni con un impatto minimo sulla disponibilità dei database.

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'.

Ecco l’output delle dichiarazioni di stampa che abbiamo utilizzato in precedenza. Il backup delle snapshot è stato completato correttamente: il sistema è stato autenticato con FlashArray, ha sospeso TestDB1 per bloccare l’I/O, ha creato la snapshot (aen-sql-25-a-pg.17), ha ripreso l’I/O e ha terminato con un backup di soli metadati, il tutto confermato tramite i log di SQL Server e le risposte 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

Riepilogo delle cose

Questo esempio illustra come la nuova sp_invoke_external_rest_endpointprocedura di SQL Server 2025 trasforma l’automazione del backup. In precedenza, l’integrazione con i sistemi di storage richiedeva PowerShell o strumenti esterni. Ora possiamo effettuare chiamate API REST in modo nativo da T-SQL, semplificando i workflow e riducendo la complessità.

Vantaggi principali:

• Integrazione REST nativa: Infine, possiamo effettuare chiamate API direttamente da T-SQL senza passare a PowerShell o ad altri linguaggi di scripting
• Automazione semplificata: Crea l’intero flusso di lavoro di backup in un unico posto, senza passare più dal contesto a strumenti diversi
• Dipendenze ridotte: Elimina i livelli intermedi tra SQL Server e i sistemi di storage: meno parti mobili significa meno potenziali punti di guasto
• Sicurezza migliorata: Mantieni l’autenticazione centralizzata all’interno di SQL Server invece che in file di script esterni
• Performance migliori: L’esecuzione delle operazioni all’interno di SQL Server comporta costi generali di gestione inferiori e tempi di esecuzione più rapidi

Questa funzionalità elimina il passaggio dal contesto all’altro e introduce funzionalità di automazione moderna nel motore di database. Assicurati di archiviare in modo sicuro i token API e di implementare una corretta gestione degli errori in produzione.

In sintesi, l’integrazione REST di SQL Server 2025 è una grande vittoria per i DBA che gestiscono ambienti complessi e su larga scala.

Mantieni la calma e
Ripristina il

Recupera i tuoi dati prima di dover dire a chiunque che hai dovuto ripristinarli.

Sconfiggi il Ransomware con un ripristino rapido e pulito dei tuoi dati.

Mantieni la calma e ripristina