Intégration de l’API REST T-SQL dans SQL Server 2025 : Rationalisation des sauvegardes de snapshots T-SQL

Cet article a initialement été publié sur le blog d’Anthony Nocentino. Elle a été republiée avec le crédit et le consentement de l’auteur.

Dans cet article, je vais vous présenter un script T-SQL qui crée des snapshots cohérents avec les applications sur Pure Storage^® FlashArray^™, le tout depuis SQL Server, sans outils externes. SQL Server 2025 introduit une nouvelle fonctionnalité puissante : la procédure sp_invoke_external_rest_endpoint stockée. Grâce à cette amélioration, il est plus facile que jamais d’appeler des API REST directement depuis T-SQL. En combinant cette nouvelle fonctionnalité avec l’API Pure Storage, nous pouvons orchestrer les opérations de snapshot en toute transparence, sans outils ou scripts externes.

Si vous avez suivi ma série « Utilisation de la sauvegarde par snapshot T-SQL », vous savez que cette fonctionnalité offre des avantages considérables pour les environnements de bases de données volumineux. Aujourd’hui, nous verrons comment mettre en œuvre cela directement dans T-SQL en tirant parti de la capacité de SQL Server à appeler des points de terminaison REST externes, sans avoir besoin de PowerShell.

Dans T-SQL, en tirant parti de la capacité de SQL Server à appeler des points de terminaison REST externes, il n’est pas nécessaire d’utiliser PowerShell.

Vous pouvez accéder à l’intégralité du scriptici.

Activation du point de terminaison REST dans SQL Server 2025

Tout d’abord, assurons-nous de pouvoir nous connecter à des terminaux REST externes :

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

Cela permet à la fonctionnalité de point de terminaison REST de SQL Server, qui permet à SQL Server d’effectuer des appels sortants sur l’API REST. Cela est essentiel pour se connecter à l’API de la baie FlashArray afin de déclencher des snapshots.

Il est important de noter que tous les terminaux sp_invoke_external_rest_endpointdoivent utiliser HTTPS avec chiffrement TLS, et que le certificat doit être approuvé par le système d’exploitation sous-jacent hébergeant l’instance SQL Server.

Authentification avec la baie FlashArray

Ensuite, nous établirons une session sécurisée avec la baie FlashArray de Pure Storage à l’aide de la procédure sp_invoke_external_rest_endpointnewstored de SQL Server 2025. Cette fonctionnalité représente une avancée significative dans les capacités de SQL Server, ce qui nous permet de passer des appels d’API REST directement depuis T-SQL sans script externe.

Pour s’authentifier sur une baie FlashArray, nous soumettons d’abord un jetonAPI avecles autorisations suffisantes pour le terminal de connexion de la baie FlashArray. Une fois l’authentification réussie, la baie FlashArray renvoie anx-auth-tokendans les en-têtes de réponse, qui deviennent nos identifiants de session pour toutes les opérations d’API ultérieures de cette session. Ce modèle d’authentification par jeton offre un mécanisme sécurisé et limité dans le temps pour les interactions API, tout en conservant une piste d’audit claire des opérations.

Dans le code qui suit, nous exécuterons cette demande d’authentification, puis extrayons lex-auth-tokende la réponse JSON pour créer nos en-têtes d’autorisation pour les appels d’API REST suivants.

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

Gestion des erreurs et extraction des jetons

Ensuite, nous vérifierons la réussite de la connexion et extrayons le jeton d’authentification. Si le code de retour de la baie FlashArray n’est pas 0, nous imprimerons un message d’erreur et quitterons. En supposant un succès, nous lirons lex-auth-tokende la réponse de connexion. Notez que la clé de jeton doit inclure des guillemets doubles « x-auth-token » pour garantir JSON_VALUEune analyse correcte. Une fois extrait, nous utiliserons le jeton pour construire l’en-tête d’autorisation pour les appels d’API REST ultérieurs sur la baie.

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

Geler la base de données pour snapshot

L’étape cruciale est la suspension des I/O d’écriture de la base de données pour préparer le snapshot. Cette commande utilise la fonction de sauvegarde par snapshot T-SQL de SQL Server 2022 pour geler les opérations d’I/O d’écriture sur la base de données. La base de données reste lisible, mais les opérations d’écriture sont suspendues jusqu’à ce que nous terminions notre processus de snapshot. Nous obtenons ainsi un snapshot cohérent avec les applications.

ALTER DATABASE [TestDB1] SET SUSPEND_FOR_SNAPSHOT_BACKUP = ON

Prise de l’instantané du stockage

Avec I/O en écriture bloquées sur la base de données, nous sommes prêts à prendre un snapshot sur la baie FlashArray. L’étape suivante consiste à appeler leendpointprotection-group-snapshotsREST RESTpour lancer une sauvegarde instantanée du groupe de protection.

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

Ici, nous appelons l’API RESTprotection-group-snapshotsendpoint de la baie FlashArray pour créer un snapshot d’un groupe de protection nomméaen-sql-25-a-pg. Le groupe de protection doit contenir tous les volumes où sont stockés nos fichiers de base de données. La baie FlashArray crée un snapshot ponctuel de tous les volumes de ce groupe de protection.

Extraction du nom du snapshot et création de la sauvegarde

À l’étape suivante, nous extrayons le nom du snapshot de la réponse JSON de la baie FlashArray à l’aide deJSON_VALUE(@response, '$.result.items[0].name'). Ce nom sera inclus dans la description du support de sauvegarde dans le cadre d’une sauvegarde avec métadonnées uniquement. Si la baie FlashArray renvoie un code de réussite (code de retour = 0), nous procédons à la sauvegarde à l’aide de la commandeBACKUP DATABASE et de l’METADATA_ONLYoption. Cela crée un fichier de sauvegarde léger contenant uniquement les métadonnées de la base de données et une référence à l’instantané FlashArray dans laMEDIADESCRIPTION. Le stockage du nom du snapshot dans le MEDIADESCRIPTION facilite l’identification et la localisation du snapshot FlashArray correspondant lors de l’exécution d’une opération de restauration.

Si l’opération de snapshot échoue, nous enregistrons un message d’erreur et débloquons immédiatement la base de données pour reprendre les I/O d’écriture normales.

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

Vérification du journal d’erreurs SQL Server

Pour vérifier notre fonctionnement de sauvegarde, nous vérifions le journal d’erreurs SQL Server.

Le journal d’erreurs SQL Server confirme que la sauvegarde par snapshot de la base de données TestDB1 a réussi uniquement avec les métadonnées. Le journal indique que la base de données a été suspendue, que les I/O en écriture ont été gelées et que l’instantané a été pris avant que les I/O ne reprennent en toute sécurité. Puisqu’il s’agit d’une sauvegarde avec métadonnées uniquement, aucune page de données n’a été traitée ; seules les métadonnées ont été capturées et écrites dans le fichier.bkm spécifié. Cela garantit un snapshot cohérent avec les applications, avec un impact minimal sur la disponibilité de la base de données.

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

Voici le résultat des déclarations imprimées que nous avons utilisées ci-dessus. La sauvegarde des snapshots s’est terminée avec succès : le système s’est authentifié avec la baie FlashArray, a suspendu TestDB1 pour geler les I/O, a créé le snapshot (aen-sql-25-a-pg.17), a repris les I/O et a fini par une sauvegarde uniquement basée sur les métadonnées, le tout confirmé par les journaux SQL Server et les réponses 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

Conclusion

Cet exemple montre comment la nouvelle sp_invoke_external_rest_endpointprocédure de SQL Server 2025 transforme l’automatisation des sauvegardes. Auparavant, l’intégration aux systèmes de stockage nécessitait PowerShell ou des outils externes. Désormais, nous pouvons passer des appels d’API REST en natif à partir de T-SQL, ce qui simplifie les flux de travail et réduit la complexité.

Principaux avantages :

• Intégration REST native : Enfin, nous pouvons passer des appels API directement depuis T-SQL sans passer directement à PowerShell ou à d’autres langages de script
• Automatisation simplifiée : Construisez l’ensemble de votre flux de sauvegarde en un seul endroit : plus besoin de passer d’un outil à un autre
• Dépendances réduites : Éliminez les couches intermédiaires entre SQL Server et vos systèmes de stockage : moins de pièces mobiles, moins de points de défaillance potentiels
• Sécurité renforcée : Maintenez votre authentification centralisée dans SQL Server plutôt que dans des fichiers de script externes
• Meilleures performances : L’exécution des opérations dans SQL Server permet de réduire les frais généraux et d’accélérer les temps d’exécution

Cette fonctionnalité élimine la commutation de contexte et intègre des capacités d’automatisation modernes dans le moteur de base de données. Assurez-vous simplement de stocker en toute sécurité les jetons d’API et de mettre en œuvre une gestion appropriée des erreurs en production.

En fin de compte, l’intégration REST de SQL Server 2025 est un atout majeur pour les DBA qui gèrent des environnements complexes et à grande échelle.

Restez calme et
Restauration activée

Récupérez vos données avant d’avoir à dire à quelqu’un que vous deviez les récupérer.

Éliminez les Ransomware une reprise rapide et propre de vos données.

Assurez votre calme et votre reprise