sp_invoke_external_rest_endpoint (Transact-SQL)

Si applica a: SQL Server 2025 (17.x) Anteprima del databaseSQL di Azure Istanza gestita di SQL di Azurein Microsoft Fabric

La sp_invoke_external_rest_endpoint stored procedure richiama un endpoint REST HTTPS fornito come argomento di input per la procedura.

Nota

La sp_invoke_external_rest_endpoint stored procedure è disponibile in anteprima per l'anteprima di SQL Server 2025 (17.x).

Modi per ridurre il rischio di accesso o trasferimento non autorizzato dei dati

Attenzione

L'uso della stored procedure sp_invoke_external_rest_endpoint consente il trasferimento di dati a un'entità esterna.

Per ridurre il rischio di accesso o trasferimento non autorizzato dei dati, prendere in considerazione le procedure consigliate per la sicurezza seguenti:

• Implementare controlli di accesso sicuri: assicurarsi che solo gli utenti autorizzati abbiano accesso ai dati sensibili e agli endpoint dell'API REST. Usare il principio dei privilegi minimi, nonché i ruoli e i privilegi del database.
• autenticazione e autorizzazione appropriate: assicurarsi che tutte le chiamate REST siano autenticate e autorizzate per impedire l'accesso non autorizzato.
• Monitorare e controllare l'accesso: monitorare e controllare regolarmente l'accesso al database e alle chiamate API REST per rilevare eventuali attività sospette.
• valutazioni regolari della sicurezza: eseguire normali analisi di valutazione della sicurezza e vulnerabilità per identificare e attenuare i potenziali rischi.
• formazione dei dipendenti: informare i dipendenti sui rischi dell'esfiltrazione dei dati e sull'importanza dei protocolli di sicurezza seguenti.

Sintassi

Convenzioni relative alla sintassi Transact-SQL

EXECUTE @returnValue = sp_invoke_external_rest_endpoint
  [ @url = ] N'url'
  [ , [ @payload = ] N'request_payload' ]
  [ , [ @headers = ] N'http_headers_as_json_array' ]
  [ , [ @method = ] 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' ]
  [ , [ @timeout = ] seconds ]
  [ , [ @credential = ] credential ]
  [ , @response OUTPUT ]

Argomenti

[ @url = ] N'url'

URL dell'endpoint REST HTTPS da chiamare. @url è nvarchar(4000) senza impostazione predefinita.

[ @payload = ] N'request_payload'

Stringa Unicode in un formato JSON, XML o TEXT che contiene il payload da inviare all'endpoint REST HTTPS. I payload devono essere un documento JSON valido, un documento XML ben formato o un testo. @payload è nvarchar(max) senza impostazione predefinita.

[ @headers = ] N'headers'

Intestazioni che devono essere inviate come parte della richiesta all'endpoint REST HTTPS. Le intestazioni devono essere specificate usando un formato JSON flat (un documento JSON senza strutture annidate). Le intestazioni definite nell'elenco dei nomi delle intestazioni non consentite vengono ignorate anche se vengono passate in modo esplicito nel parametro @headers ; i relativi valori vengono eliminati o sostituiti con i valori forniti dal sistema all'avvio della richiesta HTTPS.

Il parametro @headers è nvarchar(4000) senza impostazione predefinita.

[ @method = ] N'method'

Metodo HTTP per chiamare l'URL. Deve essere uno dei valori seguenti: GET, POST, PUT, PATCH, DELETE, HEAD. @method è nvarchar(6) con POST come valore predefinito.

[ @timeout = ] secondi

Tempo in secondi consentito per l'esecuzione della chiamata HTTPS. Se la richiesta HTTP completa e la risposta non possono essere inviate e ricevute entro il timeout definito in secondi, l'esecuzione della stored procedure viene interrotta e viene generata un'eccezione. Il timeout viene avviato all'avvio della connessione HTTP e termina quando la risposta e il payload inclusi, se presenti, sono stati ricevuti. @timeout è un smallint positivo con un valore predefinito 30. Valori accettati: da 1 a 230.

[ @credential = ] credenziali

Indicare l'oggetto DATABASE SCOPED CREDENTIAL usato per inserire le informazioni di autenticazione nella richiesta HTTPS. @credential è sysname senza alcun valore predefinito.

@response PRODOTTO

Consentire il passaggio della risposta ricevuta dall'endpoint chiamato nella variabile specificata. @response è nvarchar(max).

Valore restituito

L'esecuzione restituisce 0 se la chiamata HTTPS è stata eseguita e il codice di stato HTTP ricevuto è un codice di stato 2xx (Success). Se il codice di stato HTTP ricevuto non è compreso nell'intervallo 2xx, il valore restituito è il codice di stato HTTP ricevuto. Se la chiamata HTTPS non può essere eseguita affatto, viene generata un'eccezione.

Autorizzazioni

Autorizzazioni per il database

È richiesta l'autorizzazione EXECUTE ANY EXTERNAL ENDPOINT database.

Ad esempio:

GRANT EXECUTE ANY EXTERNAL ENDPOINT TO [<PRINCIPAL>];

Abilitare in SQL Server 2025 e Istanza gestita di SQL di Azure

Nota

La sp_invoke_external_rest_endpoint stored procedure è disponibile in anteprima per l'anteprima di SQL Server 2025 (17.x).

La sp_invoke_external_rest_endpoint stored procedure è disponibile nell'anteprima di SQL Server 2025 (17.x) e nell'Istanza gestita di SQL di Azure configurata con i criteri di aggiornamento always-up-to-date ed è disabilitata per impostazione predefinita.

Per abilitare la sp_invoke_external_rest_endpoint stored procedure in SQL Server 2025 (17.x) Preview e Istanza gestita di SQL di Azure, eseguire il codice T-SQL seguente:

EXECUTE sp_configure 'external rest endpoint enabled', 1;

RECONFIGURE WITH OVERRIDE;

Per eseguire sp_configure per modificare un'opzione di configurazione o per eseguire l'istruzione RECONFIGURE , all'utente deve essere concessa l'autorizzazione a livello di server ALTER SETTINGS. L'autorizzazione ALTER SETTINGS viene mantenuta in modo implicito dai ruoli predefiniti del server sysadmin e serveradmin.

Nota

sp_invoke_external_rest_endpoint è abilitato per impostazione predefinita nel database SQL di Azure e nel database SQL in Fabric.

Formato della risposta

La risposta della chiamata HTTP e i dati risultanti inviati dall'endpoint richiamato sono disponibili tramite il parametro di output @response . @response potrebbe contenere un documento JSON con lo schema seguente:

{
  "response": {
    "status": {
      "http": {
        "code": "",
        "description": ""
      }
    },
    "headers": {}
  },
  "result": {}
}

In particolare:

• response: oggetto JSON che contiene il risultato HTTP e altri metadati di risposta.
• result: il payload JSON restituito dalla chiamata HTTP. Omesso se il risultato HTTP ricevuto è 204 (No Content).

In alternativa, il @response potrebbe contenere un documento XML con lo schema seguente:

<output>
    <response>
        <status>
            <http code="" description=" " />
        </status>
        <headers>
            <header key="" value="" />
            <header key="" value="" />
        </headers>
    </response>
    <result>
    </result>
</output>

In particolare:

• response: oggetto XML che contiene il risultato HTTP e altri metadati di risposta.
• result: payload XML restituito dalla chiamata HTTP. Omesso se il risultato HTTP ricevuto è 204 (No Content).

response Nella sezione, a parte il codice di stato HTTP e la descrizione, l'intero set di intestazioni di risposta ricevute viene fornito nell'oggetto headers . L'esempio seguente mostra una response sezione in JSON (anche la struttura per le risposte di testo):

"response": {
  "status": {
    "http": {
      "code": 200,
      "description": "OK"
    }
  },
  "headers": {
    "Date": "Thu, 08 Sep 2022 21:51:22 GMT",
    "Content-Length": "1345",
    "Content-Type": "application\/json; charset=utf-8",
    "Server": "Kestrel",
    "Strict-Transport-Security": "max-age=31536000; includeSubDomains"
    }
  }

L'esempio seguente illustra una response sezione in XML:

<response>
    <status>
        <http code="200" description="OK" />
    </status>
    <headers>
        <header key="Date" value="Tue, 01 Apr 1976 21:12:04 GMT" />
        <header key="Content-Length" value="2112" />
        <header key="Content-Type" value="application/xml" />
        <header key="Server" value="Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0" />
        <header key="x-ms-request-id" value="31536000-64bi-64bi-64bi-31536000" />
        <header key="x-ms-version" value="2021-10-04" />
        <header key="x-ms-creation-time" value="Wed, 19 Apr 2023 22:17:33 GMT" />
        <header key="x-ms-server-encrypted" value="true" />
    </headers>
</response>

Endpoint consentiti

Importante

Questo elenco si applica solo al database SQL di Azure e all'istanza gestita di SQL di Azure.

Sono consentite solo chiamate agli endpoint per i servizi seguenti:

Servizio di Azure	Dominio
Funzioni di Azure	*.azurewebsites.net
Servizio app Azure s	*.azurewebsites.net
Ambiente del servizio app di Azure	*.appserviceenvironment.net
App Web statiche di Azure	*.azurestaticapps.net
App per la logica di azure	*.logic.azure.com
Hub eventi di Azure	*.servicebus.windows.net
Griglia di eventi di Azure	*.eventgrid.azure.net
Servizi di intelligenza artificiale di Azure	*.cognitiveservices.azure.com *.api.cognitive.microsoft.com
OpenAI di Azure	*.openai.azure.com
PowerApps/Dataverse	*.api.crm.dynamics.com
Microsoft Dynamics	*.dynamics.com
Istanze di Azure Container	*.azurecontainer.io
App contenitore di Azure	*.azurecontainerapps.io
Power BI	api.powerbi.com
Microsoft Graph	graph.microsoft.com
Servizi di analisi	*.asazure.windows.net
IoT Central	*.azureiotcentral.com
Gestione API	*.azure-api.net
Archiviazione BLOB di Azure	*.blob.core.windows.net
File di Azure	*.file.core.windows.net
Archiviazione code di Azure	*.queue.core.windows.net
Archiviazione delle tabelle di Azure	*.table.core.windows.net
Servizi di comunicazione di Azure	*.communications.azure.com
Ricerca Bing	api.bing.microsoft.com
Azure Key Vault (Archivio chiavi di Azure)	*.vault.azure.net
Ricerca di intelligenza artificiale di Azure	*.search.windows.net
Mappe di Azure	*.atlas.microsoft.com
Traduttore per Azure AI	api.cognitive.microsofttranslator.com

Le regole del firewall in uscita per database SQL di Azure e il meccanismo di controllo di Azure Synapse Analytics possono essere usate per limitare ulteriormente l'accesso in uscita agli endpoint esterni.

Nota

Se si vuole richiamare un servizio REST non compreso nell'elenco consentito, è possibile usare Gestione API per esporre in modo sicuro il servizio desiderato e renderlo disponibile a sp_invoke_external_rest_endpoint.

Limiti

Dimensioni del payload

Il payload, sia quando ricevuto che quando inviato, è codificato tramite UTF-8 quando inviato in rete. In tale formato le dimensioni sono limitate a 100 MB.

Lunghezza URL

La lunghezza massima dell'URL (generata dopo l'uso del parametro @url e l'aggiunta delle credenziali specificate alla stringa di query, se presente) è di 8 KB. La lunghezza massima della stringa di query (stringa di query e stringa di query delle credenziali) è di 4 KB.

Dimensioni intestazioni

La dimensione massima dell'intestazione di richiesta e risposta (tutti i campi di intestazione: intestazioni passate tramite @headers parametro + intestazione delle credenziali e intestazioni fornite dal sistema) è di 8 KB.

Limitazione

Il numero di connessioni simultanee agli endpoint esterni eseguite tramite sp_invoke_external_rest_endpoint è limitato al 10% dei thread di lavoro, con un massimo di 150 ruoli di lavoro. In un'unica limitazione del database viene applicata a livello di database, mentre in una limitazione del pool elastico viene applicata sia a livello di database che a livello di pool.

Per verificare il numero di connessioni simultanee che un database può sostenere, eseguire la query seguente:

SELECT [database_name],
       DATABASEPROPERTYEX(DB_NAME(), 'ServiceObjective') AS service_level_objective,
       [slo_name] AS service_level_objective_long,
       [primary_group_max_outbound_connection_workers] AS max_database_outbound_connection,
       [primary_pool_max_outbound_connection_workers] AS max_pool_outbound_connection
FROM sys.dm_user_db_resource_governance
WHERE database_id = DB_ID();

Se viene tentata una nuova connessione a un endpoint esterno quando sp_invoke_external_rest_endpoint vengono già raggiunte le connessioni simultanee massime, viene generato l'errore 10928 (o 10936 se sono stati raggiunti i limiti dei pool elastici). Ad esempio:

Msg 10928, Level 16, State 4, Procedure sys.sp_invoke_external_rest_endpoint_internal, Line 1 [Batch Start Line 0]
Resource ID : 1. The outbound connections limit for the database is 20 and has been reached.
See 'https://docs.microsoft.com/azure/azure-sql/database/resource-limits-logical-server' for assistance.

Credenziali

Alcuni endpoint REST richiedono l'autenticazione per poter essere richiamati correttamente. L'autenticazione può essere in genere eseguita passando alcune coppie chiave-valore specifiche nella stringa di query o nelle intestazioni HTTP impostate con la richiesta.

È possibile usare DATABASE SCOPED CREDENTIAL per archiviare in modo sicuro i dati di autenticazione,ad esempio un token di connessione, da usare per sp_invoke_external_rest_endpoint chiamare un endpoint protetto. Quando si crea DATABASE SCOPED CREDENTIAL, usare il IDENTITY parametro per specificare quali dati di autenticazione vengono passati all'endpoint richiamato e come. IDENTITY supporta quattro opzioni:

• HTTPEndpointHeaders: inviare dati di autenticazione specificati usando le intestazioni della richiesta
• HTTPEndpointQueryString: inviare dati di autenticazione specificati usando la stringa di query
• Managed Identity: inviare l'identità gestita assegnata dal sistema usando le intestazioni della richiesta
• Shared Access Signature: fornire accesso delegato limitato alle risorse tramite un URL firmato (detto anche firma di accesso condiviso)

L'oggetto creato DATABASE SCOPED CREDENTIAL può essere usato tramite il parametro @credential :

EXECUTE sp_invoke_external_rest_endpoint
    @url = N'https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?key1=value1',
    @credential = [https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>];

Intestazioni della richiesta

Con questo IDENTITY valore, l'oggetto DATABASE SCOPED CREDENTIAL viene aggiunto alle intestazioni della richiesta. La coppia chiave-valore contenente le informazioni di autenticazione deve essere fornita tramite il SECRET parametro usando un formato JSON flat. Ad esempio:

CREATE DATABASE SCOPED CREDENTIAL [https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>]
WITH IDENTITY = 'HTTPEndpointHeaders', SECRET = '{"x-functions-key":"<your-function-key-here>"}';

Stringa di query

Con questo IDENTITY valore, l'oggetto DATABASE SCOPED CREDENTIAL viene aggiunto alla stringa di query. La coppia chiave-valore contenente le informazioni di autenticazione deve essere fornita tramite il SECRET parametro usando un formato JSON flat. Ad esempio:

CREATE DATABASE SCOPED CREDENTIAL [https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>]
WITH IDENTITY = 'HTTPEndpointQueryString', SECRET = '{"code":"<your-function-key-here>"}';

Identità gestita

• Password offre l'autenticazione con le credenziali di Microsoft Entra
• Universal con MFA aggiunge l'autenticazione a più fattori
• L'integrazione usa provider federatici come Active Directory Federation Services (ADFS) per abilitare le esperienze Single Sign-On (SSO)
• Entità servizio abilita l'autenticazione con le applicazioni Azure
• Identità gestita abilita l'autenticazione dalle applicazioni assegnate alle identità di Microsoft Entra

Con questo IDENTITY valore, le informazioni di autenticazione per vengono DATABASE SCOPED CREDENTIAL ricavate dall'identità gestita assegnata dal sistema del server logico in cui risiede il database e vengono passate nelle intestazioni della richiesta. Deve SECRET essere impostato su APP_ID (o CLIENT_ID) utilizzato per configurare l'autenticazione di Microsoft Entra dell'endpoint chiamato. Per un esempio, vedere Configurare il servizio app o l'app Funzioni di Azure per l'uso dell'accesso a Microsoft Entra.

CREATE DATABASE SCOPED CREDENTIAL [https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>]
WITH IDENTITY = 'Managed Identity', SECRET = '{"resourceid":"<APP_ID>"}';

Sono supportate sia le identità gestite assegnate dal sistema che le identità gestite assegnate dall'utente:

• Se è presente almeno un'identità gestita assegnata dall'utente, l'identità primaria definita viene usata per l'autenticazione quando si usano credenziali con ambito database basato su identità gestite.

• Se non è assegnata alcuna identità gestita assegnata dall'utente, viene usata l'identità gestita assegnata dal sistema, se abilitata, per l'autenticazione quando si usa una credenziale con ambito database basato sull'identità gestita.

• Se vengono definite identità gestite assegnate dall'utente e assegnate dal sistema, viene usata l'identità gestita assegnata dall'utente.

• Se sono assegnate più identità gestite assegnate dall'utente, viene usata solo l'identità primaria.

Regole per il nome delle credenziali

L'CREDENTIAL CON AMBITO DATABASE creato deve rispettare regole specifiche per poter essere usate con sp_invoke_external_rest_endpoint. Le regole sono le seguenti:

• Deve essere un URL valido
• Il dominio URL deve essere uno di questi domini inclusi nell'elenco consenti
• L'URL non deve contenere una stringa di query
• Protocollo + nome di dominio completo (FQDN) dell'URL chiamato deve corrispondere al protocollo e al nome FQDN del nome della credenziale
• Ogni parte del percorso URL chiamato deve corrispondere completamente alla rispettiva parte del percorso URL nel nome delle credenziali
• Le credenziali devono puntare a un percorso più generico rispetto all'URL della richiesta. Ad esempio, non è possibile usare credenziali create per il percorso https://northwind.azurewebsite.net/customers per l'URL https://northwind.azurewebsite.net

Regole di confronto e nome credenziali

RFC 3986 Sezione 6.2.2.1 indica che "Quando un URI usa componenti della sintassi generica, le regole di equivalenza della sintassi dei componenti si applicano sempre; vale a dire che lo schema e l'host non fanno distinzione tra maiuscole e minuscole" e RFC 7230 Sezione 2.7.3 indica che "tutti gli altri vengono confrontati in modo con distinzione tra maiuscole e minuscole".

Poiché è presente un set di regole di confronto a livello di database, viene applicata la logica seguente per essere coerente con la regola delle regole di confronto del database e la RFC indicata in precedenza. La regola descritta potrebbe potenzialmente essere più restrittiva rispetto alle regole RFC, ad esempio se il database è impostato per usare regole di confronto con distinzione tra maiuscole e minuscole.

1. Controllare se l'URL e la corrispondenza delle credenziali usano la RFC, ovvero:
   • Controllare lo schema e l'host usando regole di confronto senza distinzione tra maiuscole e minuscole (Latin1_General_100_CI_AS_KS_WS_SC)
   • Verificare che tutti gli altri segmenti dell'URL vengano confrontati in regole di confronto con distinzione tra maiuscole e minuscole (Latin1_General_100_BIN2)
2. Verificare che l'URL e le credenziali corrispondano usando le regole di confronto del database (e senza eseguire alcuna codifica URL).

Concedere le autorizzazioni per l'uso delle credenziali

Gli utenti del database che accedono a UN DATABASE SCOPED CREDENTIAL devono disporre dell'autorizzazione per l'utilizzo di tali credenziali.

Per usare le credenziali, un utente del database deve disporre REFERENCES dell'autorizzazione per credenziali specifiche:

GRANT REFERENCES ON DATABASE SCOPED CREDENTIAL::[<CREDENTIAL_NAME>] TO [<PRINCIPAL>];

Osservazioni:

Tipo di attesa

Quando sp_invoke_external_rest_endpoint è in attesa del completamento della chiamata al servizio richiamato, segnala un HTTP_EXTERNAL_CONNECTION tipo di attesa.

HTTPS e TLS

Sono supportati solo gli endpoint configurati per l'uso di HTTPS con il protocollo di crittografia TLS.

Reindirizzamenti HTTP

sp_invoke_external_rest_endpoint non segue automaticamente alcun reindirizzamento HTTP ricevuto come risposta dall'endpoint richiamato.

Intestazioni HTTP

sp_invoke_external_rest_endpoint inserisce automaticamente le intestazioni seguenti nella richiesta HTTP:

• content-type: impostato su application/json; charset=utf-8
• accept: impostato su application/json
• user-agent: impostare <EDITION>/<PRODUCT VERSION> ad esempio: SQL Azure/12.0.2000.8

Anche se l'agente utente viene sempre sovrascritto dalla stored procedure, il tipo di contenuto e accettare i valori di intestazione può essere definito dall'utente tramite il parametro @headers . È consentito specificare solo la direttiva media type nel tipo di contenuto e specificare le direttive charset o boundary non è possibile.

Tipi di supporti supportati per il payload di richiesta e risposta

Di seguito sono riportati i valori accettati per il tipo di contenuto dell'intestazione.

• application/json
• application/vnd.microsoft.*.json
• Applicazione/XML
• application/vnd.microsoft.*.xml
• application/vnd.microsoft.*+xml
• application/x-www-form-urlencoded
• Testo/*

Per l'intestazione accept , di seguito sono riportati i valori accettati.

• application/json
• Applicazione/XML
• Testo/*

Per altre informazioni sui tipi di intestazione di testo, vedere registro dei tipi di testo in IANA.

Nota

Se si sta testando la chiamata dell'endpoint REST con altri strumenti, ad esempio cURL o qualsiasi client REST moderno come Insonnia, assicurarsi di includere le stesse intestazioni inserite automaticamente da sp_invoke_external_rest_endpoint per avere lo stesso comportamento e risultati.

Procedure consigliate

Usare una tecnica di invio in batch

Se è necessario inviare un set di righe a un endpoint REST, ad esempio a una funzione di Azure o a un hub eventi, è consigliabile inviare in batch le righe in un singolo documento JSON, per evitare il sovraccarico delle chiamate HTTPS per ogni riga inviata. Questa operazione può essere eseguita usando l'istruzione FOR JSON , ad esempio:

-- create the payload
DECLARE @payload AS NVARCHAR (MAX);

SET @payload = (SELECT [object_id],
                       [name],
                       [column_id]
                FROM sys.columns
                FOR JSON AUTO);

-- invoke the REST endpoint
DECLARE @retcode AS INT, @response AS NVARCHAR (MAX);

EXECUTE
    @retcode = sp_invoke_external_rest_endpoint
    @url = '<REST_endpoint>',
    @payload = @payload,
    @response = @response OUTPUT;

-- return the result
SELECT @retcode,
       @response;

Esempi

Di seguito sono riportati alcuni esempi su come usare per l'integrazione sp_invoke_external_rest_endpoint con servizi di Azure comuni, ad esempio Funzioni di Azure o Hub eventi di Azure. Altri esempi per l'integrazione con altri servizi sono disponibili in GitHub.

R. Chiamare una funzione di Azure usando un'associazione di trigger HTTP senza autenticazione

L'esempio seguente chiama una funzione di Azure usando un'associazione di trigger HTTP che consente l'accesso anonimo.

DECLARE @ret AS INT, @response AS NVARCHAR (MAX);

EXECUTE
    @ret = sp_invoke_external_rest_endpoint
    @url = N'https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?key1=value1',
    @headers = N'{"header1":"value_a", "header2":"value2", "header1":"value_b"}',
    @payload = N'{"some":{"data":"here"}}',
    @response = @response OUTPUT;

SELECT @ret AS ReturnCode,
       @response AS Response;

B. Chiamare una funzione di Azure usando un'associazione di trigger HTTP con una chiave di autorizzazione

L'esempio seguente chiama una funzione di Azure usando un'associazione di trigger HTTP configurata per richiedere una chiave di autorizzazione. La chiave di autorizzazione viene passata nell'intestazione x-function-key come richiesto da Funzioni di Azure. Per altre informazioni, vedere Funzioni di Azure - Autorizzazione della chiave API.

CREATE DATABASE SCOPED CREDENTIAL [https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>]
    WITH IDENTITY = 'HTTPEndpointHeaders', SECRET = '{"x-functions-key":"<your-function-key-here>"}';

DECLARE @ret AS INT, @response AS NVARCHAR (MAX);

EXECUTE
    @ret = sp_invoke_external_rest_endpoint
    @url = N'https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?key1=value1',
    @headers = N'{"header1":"value_a", "header2":"value2", "header1":"value_b"}',
    @credential = [https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>],
    @payload = N'{"some":{"data":"here"}}',
    @response = @response OUTPUT;

SELECT @ret AS ReturnCode,
       @response AS Response;

C. Leggere il contenuto di un file da Archiviazione BLOB di Azure con un token di firma di accesso condiviso

Questo esempio legge un file da Archiviazione BLOB di Azure usando un token di firma di accesso condiviso per l'autenticazione. I risultati vengono restituiti in XML, pertanto è necessario usare l'intestazione "Accept":"application/xml".

DECLARE @ret AS INT, @response AS NVARCHAR (MAX);

EXECUTE
    @ret = sp_invoke_external_rest_endpoint
    @url = N'https://blobby.blob.core.windows.net/datafiles/my_favorite_blobs.txt?sp=r&st=2023-07-28T19:56:07Z&se=2023-07-29T03:56:07Z&spr=https&sv=2022-11-02&sr=b&sig=XXXXXX1234XXXXXX6789XXXXX',
    @headers = N'{"Accept":"application/xml"}',
    @method = 'GET',
    @response = @response OUTPUT;

SELECT @ret AS ReturnCode,
       @response AS Response;

D. Inviare un messaggio a un hub eventi usando l'identità gestita database SQL di Azure

Questo esempio illustra come inviare messaggi a Hub eventi usando l'identità gestita di SQL di Azure. Assicurarsi di aver configurato l'identità gestita di sistema per il server logico database SQL di Azure che ospita il database, ad esempio:

az sql server update -g <resource-group> -n <azure-sql-server> --identity-type SystemAssigned

Successivamente, configurare Hub eventi per consentire all'identità gestita di SQL Server di Azure di poter inviare messaggi ("Hub eventi di Azure ruolo Mittente dati") all'hub eventi desiderato. Per altre informazioni, vedere Usare Hub eventi con identità gestite.

Al termine, è possibile usare il nome dell'identità Managed Identity quando si definiscono le credenziali con ambito database usate da sp_invoke_external_rest_endpoint. Come illustrato in Autenticare un'applicazione con Microsoft Entra ID per accedere alle risorse di Hub eventi, il nome della risorsa (o l'ID) da usare quando si usa l'autenticazione Microsoft Entra è https://eventhubs.azure.net:

CREATE DATABASE SCOPED CREDENTIAL [https://<EVENT-HUBS-NAME>.servicebus.windows.net]
WITH IDENTITY = 'Managed Identity', SECRET = '{"resourceid": "https://eventhubs.azure.net"}';
GO

DECLARE @Id AS UNIQUEIDENTIFIER = NEWID();

DECLARE @payload AS NVARCHAR (MAX) = (SELECT *
    FROM (VALUES (@Id, 'John', 'Doe')) AS UserTable(UserId, FirstName, LastName)
    FOR JSON AUTO, WITHOUT_ARRAY_WRAPPER);

DECLARE @url AS NVARCHAR (4000) = 'https://<EVENT-HUBS-NAME>.servicebus.windows.net/from-sql/messages';

DECLARE @headers AS NVARCHAR (4000) = N'{"BrokerProperties": "'
    + STRING_ESCAPE('{"PartitionKey": "'
    + CAST (@Id AS NVARCHAR (36)) + '"}', 'json') + '"}';

DECLARE @ret AS INT, @response AS NVARCHAR (MAX);

EXECUTE
    @ret = sp_invoke_external_rest_endpoint
    @url = @url,
    @headers = @headers,
    @credential = [https://<EVENT-HUBS-NAME>.servicebus.windows.net],
    @payload = @payload,
    @response = @response OUTPUT;

SELECT @ret AS ReturnCode,
       @response AS Response;

E. Leggere e scrivere un file in Archiviazione file di Azure con un database SQL di Azure credenziali con ambito

Questo esempio scrive un file in un archivio file di Azure usando un database SQL di Azure credenziali con ambito per l'autenticazione e quindi restituisce il contenuto. I risultati vengono restituiti in XML, pertanto è necessario usare l'intestazione "Accept":"application/xml".

Per iniziare, creare una chiave master per il database SQL di Azure. Sostituire <password> con una password complessa.

CREATE MASTER KEY ENCRYPTION BY PASSWORD = '<password>';
GO

Creare quindi le credenziali con ambito database usando il token di firma di accesso condiviso fornito dall'account Archiviazione BLOB di Azure. Sostituire <token> con il token di firma di accesso condiviso fornito.

CREATE DATABASE SCOPED CREDENTIAL [filestore]
WITH IDENTITY = 'SHARED ACCESS SIGNATURE', SECRET = '<token>';
GO

Creare quindi il file e aggiungervi testo con le due istruzioni seguenti. Sostituire <domain> con il percorso appropriato.

DECLARE @payload AS NVARCHAR (MAX) = (SELECT *
    FROM (VALUES ('Hello from Azure SQL!', sysdatetime())) AS payload([message], [timestamp])
    FOR JSON AUTO, WITHOUT_ARRAY_WRAPPER);

DECLARE @response AS NVARCHAR (MAX);
DECLARE @url AS NVARCHAR (MAX);
DECLARE @headers AS NVARCHAR (1000);

DECLARE @len AS INT = len(@payload);

-- Create the file
SET @url = 'https://<domain>.file.core.windows.net/myfiles/test-me-from-azure-sql.json';
SET @headers = JSON_OBJECT('x-ms-type':'file', 'x-ms-content-length':CAST (@len AS VARCHAR (9)), 'Accept':'application/xml');

EXECUTE sp_invoke_external_rest_endpoint
    @url = @url,
    @method = 'PUT',
    @headers = @headers,
    @credential = [filestore],
    @response = @response OUTPUT;

SELECT CAST (@response AS XML);

-- Add text to the file
SET @headers = JSON_OBJECT('x-ms-range':'bytes=0-' + CAST (@len - 1 AS VARCHAR (9)), 'x-ms-write':'update', 'Accept':'application/xml');
SET @url = 'https://<domain>.file.core.windows.net/myfiles/test-me-from-azure-sql.json';
SET @url += '?comp=range';

EXECUTE sp_invoke_external_rest_endpoint
    @url = @url,
    @method = 'PUT',
    @headers = @headers,
    @payload = @payload,
    @credential = [filestore],
    @response = @response OUTPUT;

SELECT CAST (@response AS XML);
GO

Usare infine l'istruzione seguente per leggere il file. Sostituire <domain> con il percorso appropriato.

DECLARE @response AS NVARCHAR (MAX);

DECLARE @url AS NVARCHAR (MAX) = 'https://<domain>.file.core.windows.net/myfiles/test-me-from-azure-sql.json';

EXECUTE sp_invoke_external_rest_endpoint
    @url = @url,
    @headers = '{"Accept":"application/xml"}',
    @credential = [filestore],
    @method = 'GET',
    @response = @response OUTPUT;

SELECT CAST (@response AS XML);
GO

F. Chiamare un'istanza di Azure OpenAI usando l'identità gestita

L'esempio seguente chiama un modello OpenAI di Azure usando identità gestite in Microsoft Entra per SQL di Azure. Sostituire <my-azure-openai-endpoint> e <model-deployment-name> con l'endpoint e il nome del modello OpenAI di Azure rispettivamente e assicurarsi di avere assegnato il ruolo utente OpenAI di Servizi cognitivi nel servizio Azure OpenAI .

CREATE DATABASE SCOPED CREDENTIAL [https://<my-azure-openai-endpoint>.openai.azure.com]
    WITH IDENTITY = 'Managed Identity', SECRET = '{"resourceid":"https://cognitiveservices.azure.com"}';
GO

DECLARE @response AS NVARCHAR (MAX);

DECLARE @payload AS NVARCHAR (MAX) = JSON_OBJECT('input':'hello world');

EXECUTE sp_invoke_external_rest_endpoint
    @url = 'https://<my-azure-openai-endpoint>.openai.azure.com/openai/deployments/<model-deployment-name>/embeddings?api-version=2024-08-01-preview',
    @method = 'POST',
    @credential = [https://<my-azure-openai-endpoint>.openai.azure.com],
    @payload = @payload,
    @response = @response OUTPUT;

SELECT json_query(@response, '$.result.data[0].embedding'); -- Assuming the called model is an embedding model

Contenuto correlato

• Gestione di risorse nel database SQL di Azure
• sys.dm_resource_governor_resource_pools_history_ex
• sys.dm_resource_governor_workload_groups_history_ex
• sys.dm_user_db_resource_governance
• GRANT - autorizzazioni per database (Transact-SQL)
• CREATE DATABASE SCOPED CREDENTIAL (Transact-SQL)
• Gestione API
• esempi di utilizzo sp_invoke_external_rest_endpoint