Integração da API T-SQL REST no SQL Server 2025: Simplificação dos backups de snapshots do T-SQL

Este artigo foi publicado originalmente no blog de Anthony Nocentino. Ela foi republicada com o crédito e o consentimento do autor.

Nesta publicação, apresentarei um script T-SQL que cria snapshots uniformes com aplicativos no Pure Storage^® FlashArray^. . Tudo isso dentro do SQL Server, sem ferramentas externas. O SQL Server 2025 apresenta um novo recurso avançado: o procedimento sp_invoke_external_rest_endpoint armazenado. Esse aprimoramento torna mais fácil do que nunca chamar APIs REST diretamente do T-SQL. Ao combinar esse novo recurso com a API da Pure Storage, podemos orquestrar operações de snapshot sem problemas, sem necessidade de ferramentas ou scripts externos.

Se você está seguindo minha série “Usando backup de snapshot T-SQL”, sabe que esse recurso oferece enormes benefícios para ambientes de banco de dados grandes. Hoje, veremos como implementar isso diretamente no T-SQL aproveitando a capacidade do SQL Server de chamar endpoints REST externos, sem necessidade de PowerShell.

corretamente no T-SQL aproveitando a capacidade do SQL Server de chamar endpoints REST externos, não é necessário PowerShell.

Você pode pegar todo o scriptaqui.

Habilitação do ponto de extremidade REST no SQL Server 2025

Primeiro, vamos nos certificar de que podemos nos conectar a endpoints REST externos:

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

Isso permite que o recurso de ponto terminal REST do SQL Server, que permite que nosso SQL Server faça chamadas de API REST de saída. Isso é essencial para conectar-se à API do FlashArray e acionar snapshots.

É importante observar sp_invoke_external_rest_endpointquerequer que todos os endpoints usem HTTPS com criptografia TLS, e o certificado deve ser confiável pelo sistema operacional subjacente que hospeda a instância do SQL Server.

Autenticação com o FlashArray

Em seguida, estabeleceremos uma sessão segura com o FlashArray da Pure Storage usando o procedimento recém-sp_invoke_external_rest_endpointarmazenado do SQL Server 2025. Esse recurso representa um avanço significativo nos recursos do SQL Server, permitindo fazer chamadas de API REST diretamente do T-SQL sem scripts externos.

Para fazer a autenticação em um FlashArray, primeiro enviamos umtoAPI permissões suficientes para o endpoint de login do FlashArray. Após a autenticação bem-sucedida, o FlashArray retorna anx-auth-tokennos cabeçalhos de resposta, que se torna nossa credencial de sessão para todas as operações de API subsequentes nesta sessão. Esse modelo de autenticação baseada em token fornece um mecanismo seguro e limitado por tempo para interações de API enquanto mantém uma trilha de auditoria clara das operações.

No código a seguir, executaremos essa solicitação de autenticação e extrairemos otoken x-auth da resposta JSON para criar nossos cabeçalhos de autorização para chamadas de API REST subsequentes.

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

Tratamento de erros e extração de token

Em seguida, verificaremos o sucesso do login e extrairemos o token de autenticação. Se o código de retorno do FlashArray for diferente de 0, imprimiremos uma mensagem de erro e sairemos. Supondo sucesso, leremos otoken x-authda resposta de login. Observe que a chave de token deve incluir aspas duplas "x-auth-token"para JSON_VALUEgarantirque possa analisá-la corretamente. Depois de extraído, usaremos o token para criar o cabeçalho de autorização para chamadas REST API subsequentes para o 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 do banco de dados para snapshots

A etapa crucial vem: suspender a I/O de gravação do banco de dados para se preparar para o snapshot. Esse comando usa o recurso de backup de snapshot T-SQL do SQL Server 2022 para congelar operações I/O de gravação no banco de dados. O banco de dados permanece legível, mas as operações de gravação são suspensas até concluirmos nosso processo de snapshot. Isso garante um snapshot uniforme com aplicativos.

ALTER DATABASE [TestDB1] SET SUSPEND_FOR_SNAPSHOT_BACKUP = ON

Como tirar o snapshot do armazenamento

Com I/O de gravação congelada no banco de dados, estamos prontos para fazer um snapshot do FlashArray. A próxima etapa é chamar oponto final REST deproteção-grupo-snapshots para iniciar um backup de snapshot do grupo de proteção.

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

Aqui, estamos chamando o ponto final deinstantâneos de grupo de proteção da API REST do FlashArray para criar um snapshot de um grupo de proteção chamadoaen-sql-25-a-pg. O grupo de proteção precisa conter todos os volumes onde nossos arquivos de banco de dados estão armazenados. O FlashArray criará um snapshot pontual de todos os volumes nesse grupo de proteção.

Como extrair o nome do snapshot e criar o backup

Na próxima etapa, extraímos o nome do snapshot da resposta JSON do FlashArray usandoJSON_VALUE(@response, “$.result.items[0].name”). Esse nome será incluído na descrição da mídia de backup como parte de um backup somente de metadados. Se o FlashArray retornar um código de sucesso (código de retorno = 0), prosseguiremos com o backup usando ocomando e METADATA_ONLYaopção BANCO DE DADOS DE BACKUP. Isso cria um arquivo de backup leve que contém apenas os metadados do banco de dados e uma referência ao snapshot do FlashArray naMEDIADESCRIPTION. Armazenar o nome do snapshot na MEDIADESCRIPTION facilita a identificação e localização do snapshot correspondente do FlashArray ao executar uma operação de restauração.

Se a operação do snapshot falhar, registramos uma mensagem de erro e imediatamente cancelamos a suspensão do banco de dados para retomar a I/O de gravação 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

Verificação do log de erros do SQL Server

Para verificar nossa operação de backup, verificamos o log de erros do SQL Server.

O log de erros do SQL Server confirma um backup bem-sucedido de snapshot somente de metadados do banco de dados TestDB1. O log mostra que o banco de dados foi suspenso, I/O de gravação foi congelada e o snapshot foi tirado antes I/O fosse retomada com segurança. Como este é um backup somente de metadados, nenhuma página de dados foi processada; apenas metadados foram capturados e gravados no arquivo specified.bkmfile. Isso garante um snapshot consistente com aplicativos com impacto mínimo na disponibilidade do banco de dados.

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

Aqui está o resultado das declarações impressas que usamos acima. O backup do snapshot foi concluído com sucesso: o sistema foi autenticado com o FlashArray, suspendeu o TestDB1 para congelar I/O, criou o snapshot (aen-sql-25-a-pg.17), retomou a I/O e terminou com um backup somente de metadados, tudo confirmado por meio de logs do SQL Server e respostas 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

Encerrando as coisas

Este exemplo destaca como o sp_invoke_external_rest_endpointnovoprocedimento do SQL Server 2025 transforma a automação de backup. Anteriormente, a integração com sistemas de armazenamento exigia PowerShell ou ferramentas externas. Agora, podemos fazer chamadas de API REST nativamente a partir do T-SQL, simplificando fluxos de trabalho e reduzindo a complexidade.

Principais benefícios:

• Integração REST nativa: Por fim, podemos fazer chamadas de API diretamente do T-SQL sem usar o PowerShell ou outras linguagens de script
• Automação simplificada: Crie todo o fluxo de trabalho de backup em um só lugar, sem troca de contexto entre diferentes ferramentas
• Dependências reduzidas: Elimine essas camadas intermediárias entre o SQL Server e seus sistemas de armazenamento. Menos peças móveis significa menos pontos de falha potenciais
• Segurança aprimorada: Mantenha sua autenticação centralizada no SQL Server, e não em arquivos de script externos
• Melhor desempenho: Executar operações no SQL Server significa sobrecarga mais baixa e tempos de execução mais rápidos

Esse recurso elimina a troca de contexto e traz recursos avançados de automação para o mecanismo de banco de dados. Basta armazenar com segurança os tokens de API e implementar o tratamento adequado de erros na produção.

A conclusão é que a integração REST do SQL Server 2025 é uma grande vitória para DBAs que gerenciam ambientes complexos e de grande escala.

Mantenha-se calmo e
Recuperar em

Recupere seus dados antes de dizer a qualquer pessoa que você tenha que recuperá-los.

Elimine Ransomware com uma recuperação rápida e limpa dos seus dados.

Mantenha-se calmo e recupere-se ativo