Megosztás a következőn keresztül:

sp_invoke_external_rest_endpoint (Transact-SQL)

A következőkre vonatkozik: SQL Server 2025 (17.x) Azure SQL DatabaseAzure SQL Managed InstanceSQL Database a Microsoft Fabricben

A sp_invoke_external_rest_endpoint tárolt eljárás meghívja az eljárás bemeneti argumentumaként megadott HTTPS REST-végpontot.

Módszerek a jogosulatlan hozzáférés vagy adattovábbítás kockázatának csökkentésére

Caution

A sp_invoke_external_rest_endpoint tárolt eljárás lehetővé teszi az adatok külső entitásba való átvitelét.

A jogosulatlan hozzáférés vagy adattovábbítás kockázatának csökkentése érdekében vegye figyelembe az alábbi ajánlott biztonsági eljárásokat:

  • Erős hozzáférés-vezérlésiimplementálása: Győződjön meg arról, hogy csak a jogosult felhasználók férhetnek hozzá bizalmas adatokhoz és REST API-végpontokhoz. Használja a minimális jogosultsági, valamint az adatbázis-szerepkörök és jogosultságok elvét.
  • Megfelelő hitelesítés és engedélyezés: Győződjön meg arról, hogy minden REST-hívás hitelesítve van, és jogosult a jogosulatlan hozzáférés megakadályozására.
  • Hozzáférés figyelése és naplózása: Az adatbázishoz és a REST API-hívásokhoz való hozzáférés rendszeres monitorozása és naplózása a gyanús tevékenységek észleléséhez.
  • rendszeres biztonsági értékelések: Rendszeres biztonsági felméréseket és sebezhetőségi vizsgálatokat végezhet a lehetséges kockázatok azonosítása és csökkentése érdekében.
  • Alkalmazotti betanítási: Tájékoztassa az alkalmazottakat az adatkiszivárgás kockázatairól és a következő biztonsági protokollok fontosságáról.

Syntax

Transact-SQL szintaxis konvenciói

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

A meghívandó HTTPS REST-végpont URL-címe. @url alapértelmezés nélkül nvarchar(4000).

[ @payload = ] N'request_payload'

Unicode-sztring JSON-, XML- vagy TEXT-formátumban, amely tartalmazza a HTTPS REST-végpontnak küldendő hasznos adatokat. A hasznos adatoknak érvényes JSON-dokumentumnak, jól formázott XML-dokumentumnak vagy szövegnek kell lenniük. @payload alapértelmezés nélkül nvarchar(max).

[ @headers = ] N'fejlécek'

A kérelem részeként a HTTPS REST-végpontnak küldendő fejlécek. Az élőfejeket sík JSON-formátummal (beágyazott struktúrák nélküli JSON-dokumentummal) kell megadni. A Tiltott fejlécek névlistában definiált fejlécek akkor is figyelmen kívül lesznek hagyva, ha a @headers paraméterben explicit módon adnak át; a HTTPS-kérés indításakor a rendszer elveti vagy lecseréli az értékeket a rendszer által megadott értékekre.

A @headers paraméter alapértelmezés nélkül nvarchar(4000).

[ @method = ] N'metódus'

HTTP-metódus az URL meghívásához. A következő értékek egyikének kell lennie: GET, POST, PUT, PATCH, DELETE, HEAD. @methodnvarchar(6) alapértelmezett értékként POST.

[ @timeout = ] másodperc

A HTTPS-hívás futtatásának időtartama másodpercben. Ha a teljes HTTP-kérés és -válasz nem küldhető el és fogadható a megadott időkorláton belül másodpercek alatt, a tárolt eljárás végrehajtása leáll, és kivétel keletkezik. Az időtúllépés akkor kezdődik, amikor a HTTP-kapcsolat elindul és véget ér, amikor a válasz és a hasznos adatok is érkeznek, ha vannak ilyenek. @timeout egy pozitív kis, amelynek alapértelmezett értéke 30. Elfogadott értékek: 1–230.

Ha a @retry_count paraméter van megadva, a @timeout paraméter az eljárás összesített időtúllépéseként működik.

[ @credential = ] hitelesítő adatok

Adja meg, hogy melyik DATABASE SCOPED CREDENTIAL objektumot használja a hitelesítési adatok a HTTPS-kérelembe való beszúrásához. @credential alapértelmezett érték nélküli sysname .

@response KIMENET

Engedélyezze a hívott végponttól kapott válasz átadását a megadott változóba. @responsenvarchar(max).

[ @retry_count = ] az újrapróbálkozások száma, ha vannak hibák

Megadja, hogy a tárolt eljárás hányszor próbálkozik újra a megadott végponthoz való csatlakozással, ha hiba történik. @retry_count egy pozitív apróság , amelynek alapértelmezett értéke 0. Elfogadott értékek: 0–10, a 0 pedig megkerüli az újrapróbálkozási logikát. Az újrapróbálkozási időközt a Retry-After fejléc határozza meg, ha az jelen van. Ha a fejléc hiányzik, a rendszer exponenciális visszalépési stratégiát alkalmaz adott hibakódokra. Minden más esetben az alapértelmezett késleltetés 200 ezredmásodperc.

Visszaadott érték

A végrehajtás akkor ad 0 vissza, ha a HTTPS-hívás befejeződött, és a fogadott HTTP-állapotkód egy 2xx állapotkód (Success). Ha a kapott HTTP-állapotkód nem szerepel a 2xx tartományban, a visszatérési érték a fogadott HTTP-állapotkód. Ha a HTTPS-hívás egyáltalán nem hajtható végre, a rendszer kivételt jelez.

Permissions

Adatbázis-engedélyek

BÁRMELY KÜLSŐ VÉGPONT-adatbázis engedélyének végrehajtása szükséges.

Például:

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

Engedélyezés az SQL Server 2025-ben és a felügyelt Azure SQL-példányban

A sp_invoke_external_rest_endpoint tárolt eljárás elérhető SQL Server 2025 (17.x) és Azure SQL Managed Instance verzióban az SQL Server 2025 vagy az Always-up-to-dateupdate policy rendszerrel, és alapértelmezés szerint le van tiltva.

Az SQL Server 2025 (17.x) és Azure SQL Managed Instance tárolt eljárásának engedélyezéséhez sp_invoke_external_rest_endpoint futtassuk a következő T-SQL kódot:

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

sp_configure A konfigurációs beállítás módosításához vagy a RECONFIGURE utasítás futtatásához a felhasználónak rendelkeznie kell az ALTER SETTINGS kiszolgálószintű engedélyével. Az ALTER SETTINGS engedélyt implicit módon a sysadmin és a serveradmin rögzített kiszolgálói szerepkörök birtokolják.

Note

sp_invoke_external_rest_endpoint alapértelmezés szerint engedélyezve van az Azure SQL Database-ben és az SQL Database-ben a Fabricben.

Válaszformátum

A HTTP-hívás és a meghívott végpont által visszaküldött adatok válasza a @response kimeneti paraméteren keresztül érhető el. @response az alábbi sémával rendelkező JSON-dokumentumot tartalmazhat:

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

Specifically:

  • válasz: a HTTP-eredményt és más válasz metaadatokat tartalmazó JSON-objektum.
  • eredmény: a HTTP-hívás által visszaadott JSON hasznos adat. Kihagyva, ha a kapott HTTP-eredmény 204 (No Content).

Vagy a @response a következő sémával rendelkező XML-dokumentumot tartalmazhat:

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

Specifically:

  • válasz: a HTTP-eredményt és más válasz metaadatokat tartalmazó XML-objektum.
  • eredmény: a HTTP-hívás által visszaadott XML-hasznos adat. Kihagyva, ha a kapott HTTP-eredmény 204 (No Content).

A szakaszban a response HTTP-állapotkód és a leírás mellett a kapott válaszfejlécek teljes készlete is meg van adva az headers objektumban. Az alábbi példa egy response szakaszt mutat be a JSON-ban (a szöveges válaszok struktúráját is):

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

Az alábbi példa pedig egy response szakaszt mutat be AZ XML-ben:

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

Engedélyezett végpontok

Important

Ez a lista csak az Azure SQL Database-re és a felügyelt Azure SQL-példányra vonatkozik.

Csak a következő szolgáltatások végpontjaira irányuló hívások engedélyezettek:

Azure-szolgáltatás Domain
Azure Functions *.azurewebsites.net
Azure Apps Service *.azurewebsites.net
Azure App Service Environment *.appserviceenvironment.net
Azure Static Web Apps *.azurestaticapps.net
Azure Logic Apps *.logic.azure.com
Azure Event Hubs *.servicebus.windows.net
Azure Event Grid *.eventgrid.azure.net
Azure AI Services *.cognitiveservices.azure.com
*.api.cognitive.microsoft.com
Azure OpenAI *.openai.azure.com
PowerApps / Dataverse *.api.crm.dynamics.com
Microsoft Dynamics *.dynamics.com
Azure Container Instances *.azurecontainer.io
Azure Container Apps *.azurecontainerapps.io
Power BI api.powerbi.com
Microsoft Graph graph.microsoft.com
Analysis Services *.asazure.windows.net
IoT Central *.azureiotcentral.com
API Management *.azure-api.net
Azure Blob Storage *.blob.core.windows.net
Azure Files *.file.core.windows.net
Azure Queue Storage *.queue.core.windows.net
Azure táblázat-tároló *.table.core.windows.net
Azure Communication Services *.communications.azure.com
Bing Search api.bing.microsoft.com
Azure Key Vault *.vault.azure.net
Azure AI Keresés *.search.windows.net
Azure Maps *.atlas.microsoft.com
Azure AI Fordító api.cognitive.microsofttranslator.com

kimenő tűzfalszabályok az Azure SQL Database és az Azure Synapse Analytics vezérlési mechanizmusa segítségével tovább korlátozhatja a külső végpontokhoz való kimenő hozzáférést.

Note

Ha olyan REST-szolgáltatást szeretne meghívni, amely nem szerepel az engedélyezett listában, az API Management használatával biztonságosan elérhetővé teheti a kívánt szolgáltatást, és elérhetővé teheti azt sp_invoke_external_rest_endpoint.

Limits

Hasznos adat mérete

A hasznos adatok mind fogadáskor, mind küldéskor UTF-8 kódolásúak, amikor a vezetéken keresztül küldik őket. Ebben a formátumban a mérete legfeljebb 100 MB lehet.

URL-cím hossza

A maximális URL-hossz (amely a @url paraméter használata után jön létre, és hozzáadja a megadott hitelesítő adatokat a lekérdezési sztringhez, ha van ilyen), 8 KB; a lekérdezési sztring maximális hossza (lekérdezési sztring + hitelesítőadat-lekérdezési sztring) 4 KB.

Fejlécek mérete

A kérelem- és válaszfejléc maximális mérete (az összes fejlécmező: @headers paraméter + hitelesítőadat-fejléc + a rendszer által megadott fejlécek) 8 KB.

Throttling

A sp_invoke_external_rest_endpoint keresztül végzett külső végpontokhoz való egyidejű kapcsolatok száma 10% feldolgozószálra van leképezve, legfeljebb 150 feldolgozóval. Egy önálló adatbázison szabályozás az adatbázis szintjén, míg egy rugalmas készleten szabályozást kényszerít az adatbázis és a készlet szintjén is.

Annak ellenőrzéséhez, hogy egy adatbázis hány egyidejű kapcsolatot képes fenntartani, futtassa a következő lekérdezést:

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

Ha egy külső végponthoz sp_invoke_external_rest_endpoint a maximális egyidejű kapcsolatok elérésekor új kapcsolatot próbál ki, az 10928-ás (vagy 10936-os, ha elérte a rugalmas készletek korlátait) hiba lép fel. Például:

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

Egyes REST-végpontok hitelesítést igényelnek a megfelelő meghíváshoz. A hitelesítés általában bizonyos kulcs-érték párok lekérdezési sztringben vagy a kéréssel beállított HTTP-fejlécekben való átadásával végezhető el.

A hitelesítési adatok biztonságos tárolására DATABASE SCOPED CREDENTIAL használható (például egy Tulajdonosi jogkivonat), amelyet egy védett végpont meghívásához sp_invoke_external_rest_endpoint használhat. A DATABASE SCOPED CREDENTIALparaméter létrehozásakor adja meg, IDENTITY hogy a rendszer milyen hitelesítési adatokat ad át a meghívott végpontnak, és hogyan. IDENTITY négy lehetőséget támogat:

  • HTTPEndpointHeaders: megadott hitelesítési adatok küldése a Kérelemfejlécek
  • HTTPEndpointQueryString: megadott hitelesítési adatok küldése a lekérdezési sztring
  • Managed Identity: a rendszer által hozzárendelt felügyelt identitás elküldése a kérelemfejlécek használatával
  • Shared Access Signature: korlátozott delegált hozzáférést biztosít az erőforrásokhoz egy aláírt URL- (MÁS NÉVEN SAS) keresztül

A létrehozott fájl DATABASE SCOPED CREDENTIAL a @credential paraméter használatával használható:

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

Ezzel az IDENTITY értékkel a rendszer hozzáadja a DATABASE SCOPED CREDENTIAL kérésfejlécekhez. A hitelesítési adatokat tartalmazó kulcs-érték párnak a SECRET paraméteren keresztül kell megadnia egy sima JSON-formátumot. Például:

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

Hitelesítőadat-név szabályai

A létrehozott ADATBÁZIS HATÓKÖRŰ HITELESÍTŐ ADATAInak meg kell felelnie bizonyos szabályoknak ahhoz, hogy sp_invoke_external_rest_endpointhasználhassák. A szabályok a következők:

  • Érvényes URL-címnek kell lennie
  • Az URL-tartománynak az engedélyezési lista egyik tartományának kell lennie
  • Az URL-cím nem tartalmazhat lekérdezési sztringet
  • A hívott URL protokoll + teljes tartománynévnek (FQDN) meg kell egyeznie a hitelesítőadat-név protokoll + teljes tartományneve
  • A hívott URL-elérési út minden részének teljesen meg kell egyeznie az URL-elérési út megfelelő részével a hitelesítő adatok nevében
  • A hitelesítő adatoknak egy általánosabb elérési útra kell mutatniuk, mint a kérelem URL-címe. A https://northwind.azurewebsite.net/customers elérési úthoz létrehozott hitelesítő adatok például nem használhatók az URL-https://northwind.azurewebsite.net

Rendezési és hitelesítő adatok névszabályai

Az RFC 3986 6.2.2.1 szakasza kimondja, hogy "Amikor egy URI az általános szintaxis összetevőit használja, az összetevő szintaxisának egyenértékűségi szabályai mindig érvényesek; nevezetesen, hogy a rendszer és a gazdagép nem érzékeny a kis- és nagybetűkre", és az RFC 7230 2.7.3 szakasza megemlíti, hogy "minden mást kis- és nagybetűk megkülönböztetésével hasonlítanak össze".

Mivel az adatbázis szintjén egy rendezési szabály van beállítva, a rendszer a következő logikát alkalmazza, hogy összhangban legyen az adatbázis-rendezési szabállyal és a fent említett RFC-vel. (A leírt szabály esetleg szigorúbb lehet az RFC-szabályoknál, például ha az adatbázis kis- és nagybetűk megkülönböztetésére van beállítva.):

  1. Ellenőrizze, hogy az URL-cím és a hitelesítő adatok megegyeznek-e az RFC használatával, ami a következőt jelenti:
    • Ellenőrizze a sémát és a gazdagépet a kis- és nagybetűk megkülönböztetésével (Latin1_General_100_CI_AS_KS_WS_SC)
    • Ellenőrizze, hogy az URL-cím összes többi szegmense összehasonlítva van-e a kis- és nagybetűk megkülönböztetésével (Latin1_General_100_BIN2)
  2. Ellenőrizze, hogy az URL-cím és a hitelesítő adatok egyeznek-e az adatbázis-rendezési szabályokkal (és az URL-kódolás nélkül).

Hitelesítő adatok használatára vonatkozó engedélyek megadása

A DATABASE SCOPED CREDENTIAL-hoz hozzáférő adatbázis-felhasználóknak rendelkezniük kell a hitelesítő adatok használatára vonatkozó engedéllyel.

A hitelesítő adatok használatához az adatbázis-felhasználónak REFERENCES engedéllyel kell rendelkeznie egy adott hitelesítő adathoz:

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

Remarks

Várakozás típusa

Amikor sp_invoke_external_rest_endpoint a meghívott szolgáltatás hívásának befejezésére vár, várakozási típust HTTP_EXTERNAL_CONNECTION jelent.

HTTPS és TLS

Csak azok a végpontok támogatottak, amelyek a HTTPS TLS titkosítási protokollal való használatára vannak konfigurálva.

HTTP-átirányítások

sp_invoke_external_rest_endpoint nem követi automatikusan a meghívott végpont válaszaként kapott HTTP-átirányítást.

HTTP-fejlécek

sp_invoke_external_rest_endpoint automatikusan injektálja a következő fejléceket a HTTP-kérelemben:

  • tartalomtípusú: application/json; charset=utf-8
  • elfogadási: application/json
  • felhasználói ügynök: állítsa be a <EDITION>/<PRODUCT VERSION> például: SQL Azure/12.0.2000.8

Bár a felhasználó-ügynököt mindig felülírja a tárolt eljárás, a tartalomtípus és az elfogadás fejlécértékeit a felhasználó a @headers paraméterrel definiálhatja. Csak a médiatípusra vonatkozó irányelv adható meg a tartalomtípusban, és a charset- vagy határirányirányok megadása nem lehetséges.

A kérelem- és választartalmak támogatott médiatípusok

A fejléc tartalomtípusúaz alábbi értékek fogadhatók el.

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

Az fogadja el fejlécet, az alábbiak az elfogadott értékek.

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

A szövegfejléctípusokról további információt az IANA szövegtípus-beállításjegyzékében talál.

Note

Ha a REST-végpont meghívását más eszközökkel( például cURL vagy bármely modern REST-ügyféllel, például Insomnia) teszteli, ügyeljen arra, hogy ugyanazokat a fejléceket tartalmazza, amelyeket a sp_invoke_external_rest_endpoint automatikusan injektál, hogy ugyanazzal a viselkedéssel és eredménnyel rendelkezzen.

Újrapróbálkozás számláló logikája

Ha a @retry_count paramétert állítja be, a kérés újrapróbálkozott a következő hibák esetén:

HTTP-hibák

HTTP-állapotkód Error Description
408 Kérelem időtúllépése Az ügyfél nem indított kérést a szerver időkorlátján belül, vagy a szerver nem időzítette a várakozást.
429 Túl sok kérés Az ügyfél díjszabása korlátozott. Újrapróbálási idő a "Retry-After" fejléc értéke alapján, ha megadják.
ötszáz Belső kiszolgálóhiba Általános kiszolgálóhiba.
502 Rossz átjáró A kiszolgáló érvénytelen választ kapott egy háttérrendszertől.
503 A szolgáltatás nem érhető el Átmeneti túlterhelést vagy állásidőt jelez.
504 Átjáró időtúllépése A kiszolgáló nem kap időben választ.

Ajánlott eljárások

Kötegelési technika használata

Ha sorkészletet kell küldenie egy REST-végpontnak, például egy Azure-függvénynek vagy egy eseményközpontnak, javasoljuk, hogy a sorokat egyetlen JSON-dokumentumba köteselje, hogy elkerülje az egyes elküldött sorok HTTPS-hívásának többletterhelését. Ezt a FOR JSON utasítással teheti meg, például:

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

Itt talál néhány példát arra, hogyan használható sp_invoke_external_rest_endpoint integrálható olyan gyakori Azure-szolgáltatásokkal, mint az Azure Functions vagy az Azure Event Hubs. További, más szolgáltatásokkal integrálható minták találhatók GitHub.

A. Azure-függvény meghívása HTTP-eseményindító-kötés használatával hitelesítés nélkül

Az alábbi példa meghív egy Azure-függvényt egy HTTP-eseményindító-kötés használatával, amely lehetővé teszi a névtelen hozzáférést.

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. Azure-függvény meghívása HTTP-eseményindító-kötéssel egy engedélyezési kulccsal

Az alábbi példa meghív egy Azure-függvényt egy engedélyezési kulcs megkövetelésére konfigurált HTTP-eseményindító-kötés használatával. Az engedélyezési kulcs az Azure Functions által megkövetelt módon kerül átadásra a x-function-key fejlécben. További információ: Azure Functions – API-kulcsengedélyezési.

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. Fájl tartalmának olvasása az Azure Blob Storage-ból SAS-jogkivonattal

Ez a példa egy fájlt olvas be az Azure Blob Storage-ból egy SAS-jogkivonat használatával a hitelesítéshez. Az eredmények XML formátumban jelennek meg, ezért a fejlécet "Accept":"application/xml"kell használnia.

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. Üzenet küldése eseményközpontba az Azure SQL Database felügyelt identitásával

Ez a minta bemutatja, hogyan küldhet üzeneteket az Event Hubsnak az Azure SQL Managed Identity használatával. Győződjön meg arról, hogy konfigurálta a rendszer által felügyelt identitás az adatbázist üzemeltető Logikai Azure SQL Database-kiszolgálóhoz, például:

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

Ezután konfigurálja az Event Hubsot úgy, hogy az Azure SQL Server felügyelt identitása képes legyen üzeneteket küldeni ("Azure Event Hubs Data Sender" szerepkör) a kívánt eseményközpontba. További információ: Event Hubs használata felügyelt identitásokkal.

Ha ez megtörtént, használhatja az Managed Identity identitásnevet a használt sp_invoke_external_rest_endpointadatbázis-hatókörű hitelesítő adatok definiálásakor. Ahogyan az Az alkalmazás hitelesítése a Microsoft Entra-azonosítóval az Event Hubs-erőforrásokeléréséhez, a Microsoft Entra-hitelesítés használatakor használandó erőforrásnév (vagy azonosító) 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. Fájl olvasása és írása az Azure File Storage-ba egy Azure SQL Database-hatókörű hitelesítő adatokkal

Ez a példa egy fájlt ír egy Azure File Storage-ba egy Azure SQL Database-hatókörű hitelesítő adatokkal a hitelesítéshez, majd visszaadja a tartalmat. Az eredmények XML formátumban jelennek meg, ezért a fejlécet "Accept":"application/xml"kell használnia.

Először hozzon létre egy főkulcsot az Azure SQL-adatbázishoz. Cserélje le <password> erős jelszóra.

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

Ezután hozza létre az adatbázis hatókörébe tartozó hitelesítő adatokat az Azure Blob Storage-fiók által biztosított SAS-jogkivonat használatával. Cserélje le <token> a megadott SAS-jogkivonatra.

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

Ezután hozza létre a fájlt, és adjon hozzá szöveget a következő két utasítással. Cserélje le <domain> a megfelelő elérési útra.

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

Végül a következő utasítást használva olvassa be a fájlt. Cserélje le <domain> a megfelelő elérési útra.

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. Azure OpenAI meghívása felügyelt identitással

Az alábbi példa egy Felügyelt identitásokat használó Azure OpenAI-modellt hív meg az Azure SQL-hez készült Microsoft Entra-ban. Cserélje le és <my-azure-openai-endpoint> cserélje le <model-deployment-name> az Azure OpenAI-végpontot és a modell nevét, és győződjön meg arról, hogy a felügyelt identitásnak a Cognitive Services OpenAI felhasználói szerepkört adta az Azure OpenAI szolgáltatásban.

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

Kapcsolódó tartalom

  • Last updated on