T-SQL REST API-integratie in SQL Server 2025: Stroomlijning van T-SQL-snapshotback-ups

Dit artikel verscheen oorspronkelijk op de blog van Anthony Nocentino. Het is opnieuw gepubliceerd met het krediet en de toestemming van de auteur.

In dit bericht zal ik u door een T-SQL-script leiden dat applicatieconsistente snapshots maakt op Pure Storage^® FlashArray^™, allemaal vanuit SQL Server, geen externe tooling. SQL Server 2025 introduceert een krachtige nieuwe functie: de sp_invoke_external_rest_endpoint opgeslagen procedure. Deze verbetering maakt het gemakkelijker dan ooit om REST API’s rechtstreeks vanuit T-SQL te bellen. Door deze nieuwe mogelijkheid te combineren met de Pure Storage API, kunnen we snapshot-operaties naadloos orkestreren – geen externe tools of scripts nodig.

Als u mijn serie “Gebruik van T-SQL Snapshot Backup” hebt gevolgd, weet u dat deze functie enorme voordelen biedt voor grote database-omgevingen. Vandaag zullen we bekijken hoe we dit direct in T-SQL kunnen implementeren door gebruik te maken van het vermogen van SQL Server om externe REST-eindpunten te noemen, geen PowerShell nodig.

Met name in T-SQL door gebruik te maken van SQL Server’s vermogen om externe REST-eindpunten te bellen, is geen PowerShell nodig.

U kunt het hele scripthier pakken.

Het REST-eindpunt in SQL Server 2025 mogelijk maken

Laten we er eerst voor zorgen dat we verbinding kunnen maken met externe REST-eindpunten:

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

Dit maakt de SQL Server REST-eindpuntfunctie mogelijk, waarmee onze SQL Server uitgaande REST API-oproepen kan doen. Dit is van cruciaal belang om verbinding te maken met de API van FlashArray om snapshots te activeren.

Het is belangrijk op te merken datalle eindpunten sp_invoke_external_rest_endpointvereist dat HTTPS wordt gebruikt met TLS-encryptie, en het certificaat moet worden vertrouwd door het onderliggende besturingssysteem dat de SQL Server-instantie host.

Verificatie met de FlashArray

Vervolgens zullen we een veilige sessie opzetten met de Pure Storage FlashArray met behulp van de nieuw sp_invoke_external_rest_endpointopgeslagen procedure van SQL Server 2025. Deze functie vertegenwoordigt een aanzienlijke vooruitgang in de mogelijkheden van SQL Server, waardoor we REST API-oproepen rechtstreeks vanuit T-SQL kunnen plaatsen zonder externe scripting.

Om te verifiëren voor een FlashArray dienen we eerst APItokenin met voldoende machtigingen voor het inlogeindpunt van de FlashArray. Na succesvolle authenticatie geeft de FlashArray anx-auth-tokenin de responsheaders, wat onze sessiereferentie wordt voor alle daaropvolgende API-bewerkingen in deze sessie. Dit op tokens gebaseerde authenticatiemodel biedt een veilig, tijdsgebonden mechanisme voor API-interacties met behoud van een duidelijk auditspoor van activiteiten.

In de code die volgt, voeren we dit authenticatieverzoek uit en halen we vervolgens hetx-auth-token uit het JSON-antwoord om onze autorisatieheaders te bouwen voor daaropvolgende REST API-oproepen.

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

Foutverwerking en tokenextractie

Vervolgens verifiëren we het succes van de login en extraheren we het authenticatietoken. Als de retourcode van de FlashArray iets anders is dan 0, zullen we een foutmelding afdrukken en afsluiten. Uitgaande van succes lezen we hetx-auth-tokenuit de login-respons. Houd er rekening mee dat de tokensleutel dubbele aanhalingstekens"x-auth-token" moet bevatten om ervoor te zorgendat deze correct JSON_VALUEkan worden geparseerd. Eenmaal geëxtraheerd, gebruiken we het token om de autorisatieheader te bouwen voor daaropvolgende REST API-oproepen naar de 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

De database bevriezen voor snapshot

De cruciale stap is: het opschorten van de I/O voor het schrijven van de database om zich voor te bereiden op de snapshot. Deze opdracht maakt gebruik van de T-SQL Snapshot Backup-functie van SQL Server 2022 om schrijf-I/O-bewerkingen in de database te bevriezen. De database blijft leesbaar, maar schrijfbewerkingen worden opgeschort totdat we ons snapshotproces hebben voltooid. Dit zorgt ervoor dat we een applicatieconsistente snapshot krijgen.

ALTER DATABASE [TestDB1] SET SUSPEND_FOR_SNAPSHOT_BACKUP = ON

De opslagsnapshot maken

Met write I/O bevroren op de database zijn we klaar om een snapshot te maken op de FlashArray. De volgende stap is om hetprotection-group-snapshotsREST REST-eindpunt te bellen om een snapshotback-up van de protectiegroep te starten.

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

Hier noemen we het REST APIprotection-group-snapshotsendpoint van FlashArray om een snapshot te maken van een protectiegroep genaamdaen-sql-25-a-pg. De beschermingsgroep moet alle volumes bevatten waarin onze databasebestanden zijn opgeslagen. De FlashArray creëert een point-in-time snapshot van alle volumes in deze beschermingsgroep.

De naam van de snapshot extraheren en de back-up maken

In deze volgende stap halen we de snapshotnaam uit de JSON-respons van FlashArray met behulp vanJSON_VALUE(@response, '$.result.items[0].name'). Deze naam wordt opgenomen in de Back-up Media Description als onderdeel van een alleen-Metadata-back-up. Als de FlashArray een succescode retourneert (retourcode = 0), gaan we verder met de back-up met behulp van deBACKUP DATABASE-opdracht en METADATA_ONLYdeoptie. Dit creëert een lichtgewicht back-upbestand dat alleen de Metadata van de database bevat en een verwijzing naar de FlashArray-snapshot in deMEDIADESCRIPTION. Het opslaan van de naam van de snapshot in de MEDIADESCRIPTION maakt het identificeren en lokaliseren van de bijbehorende FlashArray-snapshot eenvoudiger bij het uitvoeren van een herstelbewerking.

Als de snapshotbewerking mislukt, registreren we een foutmelding en heffen we de database onmiddellijk op om de normale schrijf-I/O te hervatten.

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

Het SQL Server-foutlogboek controleren

Om onze back-upbewerking te verifiëren, controleren we het SQL Server-foutenlogboek.

Het SQL Server-foutenlogboek bevestigt een succesvolle snapshotback-up van de TestDB1-database met alleen Metadata. Het logboek toont dat de database is opgeschort, de schrijf-I/O is bevroren en de snapshot is genomen voordat de I/O veilig werd hervat. Aangezien dit een alleen-Metadata-back-up is, zijn er geen datapagina’s verwerkt; alleen Metadata zijn vastgelegd en naar het gespecificeerde.bkmfile geschreven. Dit zorgt voor een applicatieconsistente snapshot met minimale impact op de beschikbaarheid van databases.

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

Hier is de output van de gedrukte statements die we hierboven hebben gebruikt. De snapshotback-up is voltooid: het systeem dat is geverifieerd met de FlashArray, heeft TestDB1 opgeschort om I/O te bevriezen, heeft de snapshot gemaakt (aen-sql-25-a-pg.17), heeft I/O hervat en is afgewerkt met een alleen-Metadata back-up – allemaal bevestigd via SQL Server-logs en API-reacties.

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

Dingen afronden

Dit voorbeeld laat zien hoe de sp_invoke_external_rest_endpointnieuweprocedure van SQL Server 2025 back-upautomatisering transformeert. Voorheen vereiste integratie met opslagsystemen PowerShell of externe tools. Nu kunnen we REST API-oproepen native vanuit T-SQL plaatsen, waardoor workflows worden gestroomlijnd en de complexiteit wordt verminderd.

Belangrijkste voordelen:

• Native REST-integratie: Tot slot kunnen we API-oproepen rechtstreeks vanuit T-SQL plaatsen zonder naar PowerShell of andere scripttalen te springen
• Vereenvoudigde automatisering: Bouw uw volledige back-upworkflow op één plek – geen contextwisseling meer tussen verschillende tools
• Verminderde afhankelijkheden: Elimineer die middenlagen tussen SQL Server en uw opslagsystemen – minder bewegende onderdelen betekent minder potentiële storingspunten
• Verbeterde beveiliging: Houd uw authenticatie gecentraliseerd binnen SQL Server in plaats van in externe scriptbestanden
• Betere prestaties: Het uitvoeren van operaties binnen SQL Server betekent lagere overhead en snellere uitvoeringstijden

Deze functie elimineert contextswitching en brengt moderne automatiseringsmogelijkheden in de database-engine. Zorg er alleen voor dat u API-tokens veilig opslaat en de juiste foutafhandeling in de productie implementeert.

Het komt erop neer dat de REST-integratie van SQL Server 2025 een enorme overwinning is voor DBA’s die complexe, grootschalige omgevingen beheren.

Blijf kalm en
Herstellen op

Herstel uw data voordat u iemand moet vertellen dat u ze moest herstellen.

Versla Ransomware met snel, schoon herstel van uw data.

Blijf kalm en herstel aan