sp_invoke_external_rest_endpoint (Transact-SQL)

Van toepassing op: SQL Server 2025 (17.x) Preview AzureSQL Database Azure SQL Managed InstanceSQL-databasein Microsoft Fabric Preview

De sp_invoke_external_rest_endpoint opgeslagen procedure roept een HTTPS REST-eindpunt aan dat is opgegeven als invoerargument voor de procedure.

Manieren om het risico op onbevoegde toegang of overdracht van gegevens te beperken

Houd rekening met de volgende aanbevolen beveiligingsprocedures om het risico op onbevoegde toegang of overdracht van gegevens te beperken:

• Krachtige toegangsbeheer implementeren: zorg ervoor dat alleen geautoriseerde gebruikers toegang hebben tot gevoelige gegevens en REST API-eindpunten. Gebruik het principe van minimale bevoegdheden, evenals databaserollen en -bevoegdheden.
• Juiste verificatie en autorisatie: zorg ervoor dat alle REST-aanroepen worden geverifieerd en geautoriseerd om onbevoegde toegang te voorkomen.
• Toegang controleren en controleren: controleer regelmatig de toegang tot de database en REST API-aanroepen om verdachte activiteiten te detecteren.
• reguliere beveiligingsevaluaties: voer regelmatig beveiligingsevaluaties en beveiligingsscans uit om potentiële risico's te identificeren en te beperken.
• Training voor werknemers: Informeer werknemers over de risico's van gegevensexfiltratie en het belang van het volgen van beveiligingsprotocollen.

Syntax

Transact-SQL syntaxisconventies

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 ]
  [ , [ @retry_count = ] # of retries if there are errors ] 

Arguments

[ @url = ] N'URL'

URL van het HTTPS REST-eindpunt dat moet worden aangeroepen. @url is nvarchar(4000) zonder standaardinstelling.

[ @payload = ] N'request_payload'

Unicode-tekenreeks in een JSON-, XML- of TEKST-indeling die de nettolading bevat die naar het HTTPS REST-eindpunt moet worden verzonden. Payloads moeten een geldig JSON-document, een goed opgemaakt XML-document of tekst zijn. @payload is nvarchar(max) zonder standaardinstelling.

[ @headers = ] N'headers'

Headers die moeten worden verzonden als onderdeel van de aanvraag naar het HTTPS REST-eindpunt. Headers moeten worden opgegeven met een platte JSON-indeling (een JSON-document zonder geneste structuren). Kopteksten die zijn gedefinieerd in de lijst met verboden headers worden genegeerd, zelfs als deze expliciet worden doorgegeven in de parameter @headers ; hun waarden worden verwijderd of vervangen door door het systeem geleverde waarden bij het starten van de HTTPS-aanvraag.

De parameter @headers is nvarchar(4000) zonder standaardinstelling.

[ @method = ] Methode N''

HTTP-methode voor het aanroepen van de URL. Moet een van de volgende waarden zijn: GET, POST, PUT, PATCH, DELETE, HEAD. @method is nvarchar(6) met POST als standaardwaarde.

[ @timeout = ] seconden

De tijd in seconden die is toegestaan om de HTTPS-aanroep uit te voeren. Als de volledige HTTP-aanvraag en -reactie niet binnen de gedefinieerde time-out binnen enkele seconden kunnen worden verzonden en ontvangen, wordt de uitvoering van de opgeslagen procedure gestopt en wordt er een uitzondering gegenereerd. Time-out wordt gestart wanneer de HTTP-verbinding wordt gestart en eindigt wanneer het antwoord en de nettolading, indien aanwezig, is ontvangen. @timeout is een positieve kleine met een standaardwaarde 30. Geaccepteerde waarden: 1 tot 230.

Als de parameter @retry_count is opgegeven, fungeert de @timeout parameter als de cumulatieve time-out voor de procedure.

[ @credential = ] referentie

Geef aan welk DATABASE SCOPED CREDENTIAL-object wordt gebruikt om verificatiegegevens in de HTTPS-aanvraag in te voeren. @credential is sysname zonder standaardwaarde.

uitvoer @response

Hiermee staat u toe dat het antwoord dat is ontvangen van het aangeroepen eindpunt, wordt doorgegeven aan de opgegeven variabele. @response is nvarchar(max).

[ @retry_count = ] Aantal nieuwe pogingen als er fouten zijn

Hiermee geeft u op hoe vaak de opgeslagen procedure opnieuw probeert verbinding te maken met het opgegeven eindpunt als er een fout optreedt. @retry_count is een positieve kleineint met een standaardwaarde van 0. Geaccepteerde waarden: 0 tot 10, waarbij 0 alle logica voor opnieuw proberen omzeilt. Het interval voor opnieuw proberen wordt bepaald met behulp van de Retry-After header als deze aanwezig is. Als de header afwezig is, past het systeem een exponentieel uitstelstrategie toe voor specifieke foutcodes. In alle andere gevallen wordt een standaardvertraging van 200 milliseconden gebruikt.

Retourwaarde

Uitvoering retourneert 0 als de HTTPS-aanroep is uitgevoerd en de ONTVANGEN HTTP-statuscode een 2xx-statuscode (Success) is. Als de ontvangen HTTP-statuscode zich niet in het bereik 2xx bevindt, is de retourwaarde de ONTVANGEN HTTP-statuscode. Als de HTTPS-aanroep helemaal niet kan worden uitgevoerd, wordt er een uitzondering gegenereerd.

Permissions

Databasemachtigingen

Hiervoor is EEN MACHTIGING VOOR DE EXTERN EINDPUNT-database UITVOEREN vereist.

Voorbeeld:

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

Inschakelen in SQL Server 2025 en Azure SQL Managed Instance

De sp_invoke_external_rest_endpoint opgeslagen procedure is beschikbaar in SQL Server 2025 (17.x) Preview en Azure SQL Managed Instance met het SQL Server 2025- of Always-up-to-datumupdatebeleid en is standaard uitgeschakeld.

Voer de volgende T-SQL-code uit om de sp_invoke_external_rest_endpoint opgeslagen procedure in te schakelen in SQL Server 2025 (17.x) Preview en Azure SQL Managed Instance:

EXECUTE sp_configure 'external rest endpoint enabled', 1;

RECONFIGURE WITH OVERRIDE;

Als u wilt uitvoeren om een configuratieoptie te wijzigen of om de instructie sp_configure uit te voeren, moet een gebruiker de machtiging ALTER SETTINGS op serverniveau krijgen. De machtiging ALTER SETTINGS wordt impliciet bewaard door de vaste serverfuncties sysadmin en serveradmin.

Antwoordindeling

Reactie van de HTTP-aanroep en de resulterende gegevens die worden teruggestuurd door het aangeroepen eindpunt, zijn beschikbaar via de @response uitvoerparameter. @response kan een JSON-document bevatten met het volgende schema:

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

Specifically:

• antwoord: een JSON-object dat het HTTP-resultaat en andere antwoordmetagegevens bevat.
• resultaat: de JSON-nettolading die door de HTTP-aanroep wordt geretourneerd. Weggelaten als het ontvangen HTTP-resultaat een 204 (No Content) is.

Of de @response kan een XML-document bevatten met het volgende schema:

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

Specifically:

• antwoord: een XML-object dat het HTTP-resultaat en andere antwoordmetagegevens bevat.
• resultaat: de XML-nettolading die door de HTTP-aanroep wordt geretourneerd. Weggelaten als het ontvangen HTTP-resultaat een 204 (No Content) is.

In de response sectie, afgezien van de HTTP-statuscode en beschrijving, worden de volledige set ontvangen antwoordheaders opgegeven in het headers object. In het volgende voorbeeld ziet u een response sectie in JSON (ook de structuur voor tekstreacties):

"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"
    }
  }

In het volgende voorbeeld ziet u een response sectie 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>

Toegestane eindpunten

Alleen aanroepen naar eindpunten voor de volgende services zijn toegestaan:

uitgaande firewallregels voor Azure SQL Database en Azure Synapse Analytics controlemechanisme kunnen worden gebruikt om de uitgaande toegang tot externe eindpunten verder te beperken.

Limits

Grootte van nettolading

Nettolading, zowel wanneer ontvangen als wanneer verzonden, is UTF-8 gecodeerd wanneer deze via de kabel wordt verzonden. In deze indeling is de grootte beperkt tot 100 MB.

URL-lengte

De maximale URL-lengte (gegenereerd na gebruik van de parameter @url en het toevoegen van de opgegeven referenties aan de querytekenreeks, indien van toepassing) is 8 kB; de maximale lengte van de queryreeks (queryreeks en referentiequerytekenreeks) is 4 kB.

Grootte van kopteksten

De maximale grootte van de aanvraag- en antwoordheader (alle headervelden: headers die worden doorgegeven via @headers parameter + referentieheader + door het systeem opgegeven headers) is 8 KB.

Throttling

Het aantal gelijktijdige verbindingen met externe eindpunten dat via sp_invoke_external_rest_endpoint wordt uitgevoerd, wordt beperkt tot 10% werkrolthreads, met maximaal 150 werkrollen. Op een individuele database beperking wordt afgedwongen op databaseniveau, terwijl op een elastische pool beperking wordt afgedwongen op database- en poolniveau.

Voer de volgende query uit om te controleren hoeveel gelijktijdige verbindingen een database kan ondersteunen:

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();

Als er een nieuwe verbinding met een extern eindpunt sp_invoke_external_rest_endpoint wordt geprobeerd wanneer de maximale gelijktijdige verbindingen al zijn bereikt, wordt fout 10928 (of 10936 als u limieten voor elastische pools hebt bereikt) verhoogd. Voorbeeld:

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.

Credentials

Voor sommige REST-eindpunten is verificatie vereist om correct aan te roepen. Verificatie kan meestal worden uitgevoerd door een aantal specifieke sleutel-waardeparen door te geven in de querytekenreeks of in de HTTP-headers die zijn ingesteld met de aanvraag.

Het is mogelijk om DATABASE SCOPED CREDENTIAL verificatiegegevens (zoals een Bearer-token bijvoorbeeld) veilig op te slaan om sp_invoke_external_rest_endpoint een beveiligd eindpunt aan te roepen. Wanneer u de DATABASE SCOPED CREDENTIALparameter maakt, gebruikt u de IDENTITY parameter om op te geven welke verificatiegegevens worden doorgegeven aan het aangeroepen eindpunt en hoe. IDENTITY ondersteunt vier opties:

• HTTPEndpointHeaders: opgegeven verificatiegegevens verzenden met behulp van de aanvraagheaders
• HTTPEndpointQueryString: opgegeven verificatiegegevens verzenden met behulp van de queryreeks
• Managed Identity: het door het systeem toegewezen Beheerde identiteit verzenden met behulp van de aanvraagheaders
• Shared Access Signature: beperkte gedelegeerde toegang tot resources bieden via een ondertekende URL (ook wel SAS genoemd)

De gemaakte DATABASE SCOPED CREDENTIAL kan worden gebruikt via de parameter @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>];

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

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

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

EXECUTE sp_configure 'allow server scoped db credentials', 1;
RECONFIGURE WITH OVERRIDE;

Referentienaamregels

De gemaakte DATABASE SCOPED CREDENTIAL moet voldoen aan specifieke regels om te kunnen worden gebruikt met sp_invoke_external_rest_endpoint. De regels zijn als volgt:

• Moet een geldige URL zijn
• Het URL-domein moet een van deze domeinen zijn die zijn opgenomen in de acceptatielijst
• De URL mag geen querytekenreeks bevatten
• Protocol + Fully Qualified Domain Name (FQDN) van de aangeroepen URL moet overeenkomen met Protocol + FQDN van de referentienaam
• Elk deel van het aangeroepen URL-pad moet volledig overeenkomen met het respectieve deel van het URL-pad in de referentienaam
• De referentie moet verwijzen naar een pad dat algemeener is dan de aanvraag-URL. Een referentie die is gemaakt voor het pad https://northwind.azurewebsite.net/customers kan bijvoorbeeld niet worden gebruikt voor de URL-https://northwind.azurewebsite.net

Regels voor sortering en referentienaam

RFC 3986 Section 6.2.2.1 geeft aan dat "Wanneer een URI onderdelen van de algemene syntaxis gebruikt, de equivalentieregels voor de componentsyntaxis altijd van toepassing zijn; namelijk dat het schema en de host niet hoofdlettergevoelig zijn" en RFC 7230 Section 2.7.3 vermeldt dat "alle andere worden vergeleken op een hoofdlettergevoelige manier."

Omdat er een sorteringsregel is ingesteld op databaseniveau, wordt de volgende logica toegepast om coherent te zijn met de databasesorteringsregel en de RFC die hierboven wordt genoemd. (De beschreven regel kan mogelijk meer beperkend zijn dan de RFC-regels, bijvoorbeeld als de database is ingesteld op het gebruik van een hoofdlettergevoelige sortering.):

1. Controleer of de URL en referentie overeenkomen met behulp van de RFC, wat betekent:
   • Controleer het schema en de host met behulp van een niet-hoofdlettergevoelige sortering (Latin1_General_100_CI_AS_KS_WS_SC)
   • Controleer of alle andere segmenten van de URL worden vergeleken in een hoofdlettergevoelige sortering (Latin1_General_100_BIN2)
2. Controleer of de URL en referentie overeenkomen met behulp van de databasesorteringsregels (en zonder URL-codering).

Machtigingen verlenen om referenties te gebruiken

Databasegebruikers die toegang hebben tot een DATABASE SCOPED CREDENTIAL, moeten gemachtigd zijn om die referentie te gebruiken.

Als u de referentie wilt gebruiken, moet een databasegebruiker REFERENCES machtiging hebben voor een specifieke referentie:

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

Remarks

Wachttype

Wanneer sp_invoke_external_rest_endpoint wordt gewacht tot de aanroep van de aangeroepen service is voltooid, wordt er een HTTP_EXTERNAL_CONNECTION wachttype gerapporteerd.

HTTPS en TLS

Alleen eindpunten die zijn geconfigureerd voor het gebruik van HTTPS met TLS-versleutelingsprotocol, worden ondersteund.

HTTP-omleidingen

sp_invoke_external_rest_endpoint volgt niet automatisch een HTTP-omleiding die is ontvangen als reactie van het aangeroepen eindpunt.

HTTP-headers

sp_invoke_external_rest_endpoint injecteert automatisch de volgende headers in de HTTP-aanvraag:

• inhoudstype: ingesteld op application/json; charset=utf-8
• accepteren: ingesteld op application/json
• user-agent: stel <EDITION>/<PRODUCT VERSION> in, bijvoorbeeld: SQL Azure/12.0.2000.8

Hoewel user-agent altijd wordt overschreven door de opgeslagen procedure, kunnen het inhoudstype en de acceptatieheaderwaarden worden gedefinieerd via de parameter @headers . Alleen de mediatyperichtlijn mag worden opgegeven in het inhoudstype en het opgeven van de tekenset- of grensrichtlijnen is niet mogelijk.

Nettolading aanvragen en antwoorden die worden ondersteund mediatypen

Hier volgen geaccepteerde waarden voor de header inhoudstype.

• application/json
• application/vnd.microsoft.*.json
• application/xml
• application/vnd.microsoft.*.xml
• application/vnd.microsoft.*+xml
• application/x-www-form-urlencoded
• text/*

Voor de accepteren header, zijn de volgende geaccepteerde waarden.

• application/json
• application/xml
• text/*

Zie het register voor teksttypen op IANA voor meer informatie over kopteksttypen.

Logica voor aantal nieuwe pogingen

Als u de parameter @retry_count instelt, wordt de aanvraag opnieuw geprobeerd wanneer de volgende fouten worden opgetreden:

HTTP-fouten

Beste praktijken

Een batchverwerkingstechniek gebruiken

Als u een set rijen naar een REST-eindpunt moet verzenden, bijvoorbeeld naar een Azure-functie of naar een Event Hub, is het raadzaam om de rijen in één JSON-document te batcheren om te voorkomen dat de HTTPS-oproepoverhead wordt verzonden voor elke verzonden rij. U kunt dit doen met behulp van de FOR JSON-instructie, bijvoorbeeld:

-- 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;

Examples

Hier vindt u enkele voorbeelden van het gebruik van sp_invoke_external_rest_endpoint om te integreren met algemene Azure-services, zoals Azure Functions of Azure Event Hubs. Meer voorbeelden voor integratie met andere services vindt u op GitHub-.

A. Een Azure-functie aanroepen met behulp van een HTTP-triggerbinding zonder verificatie

In het volgende voorbeeld wordt een Azure-functie aangeroepen met behulp van een HTTP-triggerbinding die anonieme toegang toestaat.

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. Een Azure-functie aanroepen met behulp van een HTTP-triggerbinding met een autorisatiesleutel

In het volgende voorbeeld wordt een Azure-functie aangeroepen met behulp van een HTTP-triggerbinding die is geconfigureerd om een autorisatiesleutel te vereisen. De autorisatiesleutel wordt doorgegeven in de x-function-key header, zoals vereist door Azure Functions. Zie Azure Functions - AUTORISATIE van API-sleutelsvoor meer informatie.

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. De inhoud van een bestand uit Azure Blob Storage lezen met een SAS-token

In dit voorbeeld wordt een bestand uit Azure Blob Storage gelezen met behulp van een SAS-token voor verificatie. De resultaten worden geretourneerd in XML, dus u moet de header "Accept":"application/xml"gebruiken.

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. Een bericht verzenden naar een Event Hub met behulp van de beheerde identiteit van Azure SQL Database

In dit voorbeeld ziet u hoe u berichten naar Event Hubs kunt verzenden met behulp van azure SQL Managed Identity. Zorg ervoor dat u de System Managed Identity hebt geconfigureerd voor de logische Azure SQL Database-server die als host fungeert voor uw database, bijvoorbeeld:

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

Daarna configureert u Event Hubs om de beheerde identiteit van Azure SQL Server in staat te stellen berichten ('Azure Event Hubs Data Sender'-rol) naar de gewenste Event Hub te verzenden. Zie Event Hubs gebruiken met beheerde identiteitenvoor meer informatie.

Zodra dit is gebeurd, kunt u de naam van de identiteit gebruiken bij het Managed Identity definiëren van de databasereferentie die wordt gebruikt door sp_invoke_external_rest_endpoint. Zoals uitgelegd in Een toepassing verifiëren met Microsoft Entra-id voor toegang tot Event Hubs-resources, wordt de resourcenaam (of id) die moet worden gebruikt bij het gebruik van Microsoft Entra-verificatie 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. Een bestand lezen en schrijven naar Azure File Storage met een Azure SQL Database-bereikreferenties

In dit voorbeeld wordt een bestand naar een Azure File Storage geschreven met behulp van azure SQL Database-referenties voor verificatie en wordt vervolgens de inhoud geretourneerd. De resultaten worden geretourneerd in XML, dus u moet de header "Accept":"application/xml"gebruiken.

Begin met het maken van een hoofdsleutel voor de Azure SQL-database. Vervang <password> door een sterk wachtwoord.

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

Maak vervolgens de databasereferenties met behulp van het SAS-token dat is opgegeven door het Azure Blob Storage-account. Vervang <token> door het opgegeven SAS-token.

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

Maak vervolgens het bestand en voeg er tekst aan toe met de volgende twee instructies. Vervang <domain> door het juiste pad.

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

Gebruik ten slotte de volgende instructie om het bestand te lezen. Vervang <domain> door het juiste pad.

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. Een Azure OpenAI aanroepen met beheerde identiteit

In het volgende voorbeeld wordt een Azure OpenAI-model aanroepen met behulp van beheerde identiteiten in Microsoft Entra voor Azure SQL. Vervang en <my-azure-openai-endpoint> door <model-deployment-name> respectievelijk uw Azure OpenAI-eindpunt en modelnaam en zorg ervoor dat u de beheerde identiteit de rol Cognitive Services OpenAI-gebruiker hebt gegeven in de Azure OpenAI-service.

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

Verwante inhoud

• resourcebeheer in Azure SQL Database
• sys.dm_resource_governor_resource_pools_history_ex
• sys.dm_resource_governor_workload_groups_history_ex
• sys.dm_user_db_resource_governance
• Databasemachtigingen verlenen (Transact-SQL)
• nl-NL: CREATE DATABASE SCOPED CREDENTIAL (Transact-SQL)
• API Management-
• sp_invoke_external_rest_endpoint gebruiksvoorbeelden