Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Gilt für:
SQL Server 2025 (17.x) Azure SQL-Datenbank AzureSQL Managed InstanceSQL SQL-Datenbank in Microsoft Fabric
Die sp_invoke_external_rest_endpoint gespeicherte Prozedur ruft einen HTTPS-REST-Endpunkt auf, der als Eingabeargument für die Prozedur bereitgestellt wird.
Note
Das sp_invoke_external_rest_endpoint gespeicherte Verfahren ist in der Vorschau für SQL Server 2025 (17.x).
Möglichkeiten zur Minderung des Risikos eines nicht autorisierten Zugriffs oder der Übertragung von Daten
Caution
Die Verwendung der sp_invoke_external_rest_endpoint gespeicherten Prozedur ermöglicht die Übertragung von Daten an eine externe Entität.
Um das Risiko eines nicht autorisierten Zugriffs oder der Übertragung von Daten zu verringern, sollten Sie die folgenden bewährten Sicherheitsmethoden berücksichtigen:
- Implementieren sie starke Zugriffssteuerungen: Stellen Sie sicher, dass nur autorisierte Benutzer Zugriff auf vertrauliche Daten und REST-API-Endpunkte haben. Verwenden Sie das Prinzip der geringsten Rechtesowie Datenbankrollen und -berechtigungen.
- Ordnungsgemäße Authentifizierung und Autorisierung: Stellen Sie sicher, dass alle REST-Aufrufe authentifiziert und autorisiert sind, um unbefugten Zugriff zu verhindern.
- Überwachen und Überwachen des Zugriffs: Überwachen und Überwachen des Zugriffs auf die Datenbank und REST-API-Aufrufe regelmäßig, um verdächtige Aktivitäten zu erkennen.
- regelmäßige Sicherheitsbewertungen: Führen Sie regelmäßige Sicherheitsbewertungen und Sicherheitsrisiken durch, um potenzielle Risiken zu identifizieren und zu mindern.
- Mitarbeiterschulung: Informieren Sie Mitarbeiter über die Risiken der Datenexfiltration und die Bedeutung der folgenden Sicherheitsprotokolle.
Syntax
Transact-SQL-Syntaxkonventionen
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'
DIE URL des HTTPS-REST-Endpunkts, der aufgerufen werden soll. @url ist nvarchar(4000) ohne Standard.
[ @payload = ] N'request_payload'
Unicode-Zeichenfolge in einem JSON-, XML- oder TEXT-Format, das die Nutzlast enthält, die an den HTTPS-REST-Endpunkt gesendet werden soll. Nutzlasten müssen ein gültiges JSON-Dokument, ein wohlgeformtes XML-Dokument oder Text sein. @payload ist nvarchar(max) ohne Standard.
[ @headers = ] N'headers'
Header, die als Teil der Anforderung an den HTTPS-REST-Endpunkt gesendet werden müssen. Header müssen mit einem flachen JSON-Format (einem JSON-Dokument ohne geschachtelte Strukturen) angegeben werden. Überschriften, die in der Namensliste "Verbotene Kopfzeilen " definiert sind, werden ignoriert, auch wenn der parameter @headers explizit übergeben wird; ihre Werte werden beim Starten der HTTPS-Anforderung verworfen oder durch vom System bereitgestellte Werte ersetzt.
Der @headers-Parameter ist nvarchar(4000) ohne Standard.
[ @method = ] N'methode'
HTTP-Methode zum Aufrufen der URL. Muss einer der folgenden Werte sein: GET, , POST, PUT, PATCH, . DELETEHEAD
@method ist nvarchar(6) mit POST dem Standardwert.
[ @timeout = ] Sekunden
Zeit in Sekunden, die für die Ausführung des HTTPS-Aufrufs zulässig ist. Wenn die vollständige HTTP-Anforderung und -Antwort nicht innerhalb des definierten Timeouts in Sekunden gesendet und empfangen werden kann, wird die Ausführung der gespeicherten Prozedur angehalten und eine Ausnahme ausgelöst. Timeout beginnt, wenn die HTTP-Verbindung gestartet und beendet wird, wenn die Antwort und nutzlast, falls vorhanden, empfangen wurde. @timeout ist ein positiver Kleinerwert mit dem Standardwert 30. Akzeptierte Werte: 1 bis 230.
Wenn der @retry_count Parameter angegeben ist, fungiert der @timeout Parameter als kumuliertes Timeout für die Prozedur.
[ @credential = ] Anmeldeinformationen
Geben Sie an, welches DATABASE SCOPED CREDENTIAL-Objekt verwendet wird, um Authentifizierungsinformationen in die HTTPS-Anforderung einzustellen. @credential ist "sysname" ohne Standardwert.
@response AUSGABE
Zulassen, dass die vom aufgerufenen Endpunkt empfangene Antwort an die angegebene Variable übergeben wird. @response ist nvarchar(max).
[ @retry_count = ] Anzahl der Wiederholungen, wenn Fehler vorhanden sind
Gibt an, wie oft die gespeicherte Prozedur eine Verbindung mit dem angegebenen Endpunkt herstellt, wenn ein Fehler auftritt.
@retry_count ist ein positiver Winzwert mit dem Standardwert 0. Akzeptierte Werte: 0 bis 10, wobei 0 alle Wiederholungslogik umgeht. Das Wiederholungsintervall wird mithilfe des Retry-After Headers bestimmt, wenn es vorhanden ist. Wenn der Header nicht vorhanden ist, wendet das System eine exponentielle Backoff-Strategie für bestimmte Fehlercodes an. In allen anderen Fällen wird eine Standardverzögerung von 200 Millisekunden verwendet.
Rückgabewert
Die Ausführung gibt zurück 0 , wenn der HTTPS-Aufruf abgeschlossen wurde und der empfangene HTTP-Statuscode ein 2xx-Statuscode (Success). Wenn der empfangene HTTP-Statuscode nicht im 2xx-Bereich liegt, ist der Rückgabewert der empfangene HTTP-Statuscode. Wenn der HTTPS-Aufruf überhaupt nicht ausgeführt werden kann, wird eine Ausnahme ausgelöst.
Permissions
Datenbankberechtigungen
Erfordert EXECUTE ANY EXTERNAL ENDPOINT database permission.
Beispiel:
GRANT EXECUTE ANY EXTERNAL ENDPOINT TO [<PRINCIPAL>];
Aktivieren in SQL Server 2025 und azure SQL Managed Instance
Note
Das sp_invoke_external_rest_endpoint gespeicherte Verfahren ist in der Vorschau für SQL Server 2025 (17.x).
Das gespeicherte sp_invoke_external_rest_endpoint Verfahren ist in SQL Server 2025 (17.x) und Azure SQL Managed Instance mit der SQL Server 2025- oder Always-up-to-Date-Update-Policy verfügbar und standardmäßig deaktiviert.
Um die gespeicherte sp_invoke_external_rest_endpoint Prozedur in SQL Server 2025 (17.x) und Azure SQL Managed Instance zu aktivieren, führen Sie folgenden T-SQL-Code aus:
EXECUTE sp_configure 'external rest endpoint enabled', 1;
RECONFIGURE WITH OVERRIDE;
Um eine sp_configure Konfigurationsoption zu ändern oder die RECONFIGURE-Anweisung auszuführen, muss einem Benutzer die Berechtigung auf Serverebene ALTER SETTINGS erteilt werden. Die ALTER SETTINGS-Berechtigung wird implizit von den festen Serverrollen "sysadmin" und "serveradmin" gespeichert.
Note
sp_invoke_external_rest_endpoint ist in Azure SQL-Datenbank und SQL-Datenbank in Fabric standardmäßig aktiviert.
Antwortformat
Die Antwort des HTTP-Aufrufs und die resultierenden Daten, die vom aufgerufenen Endpunkt zurückgesendet werden, sind über den @response Ausgabeparameter verfügbar. @response kann ein JSON-Dokument mit dem folgenden Schema enthalten:
{
"response": {
"status": {
"http": {
"code": "",
"description": ""
}
},
"headers": {}
},
"result": {}
}
Specifically:
- antwort: ein JSON-Objekt, das das HTTP-Ergebnis und andere Antwortmetadaten enthält.
-
Ergebnis: die JSON-Nutzlast, die vom HTTP-Aufruf zurückgegeben wird. Wird ausgelassen, wenn das empfangene HTTP-Ergebnis ein 204 (
No Content) ist.
Oder die @response kann ein XML-Dokument mit dem folgenden Schema enthalten:
<output>
<response>
<status>
<http code="" description=" " />
</status>
<headers>
<header key="" value="" />
<header key="" value="" />
</headers>
</response>
<result>
</result>
</output>
Specifically:
- antwort: ein XML-Objekt, das das HTTP-Ergebnis und andere Antwortmetadaten enthält.
-
Ergebnis: die vom HTTP-Aufruf zurückgegebene XML-Nutzlast. Wird ausgelassen, wenn das empfangene HTTP-Ergebnis ein 204 (
No Content) ist.
response Im Abschnitt werden neben dem HTTP-Statuscode und der Beschreibung die gesamte Gruppe der empfangenen Antwortheader im headers Objekt bereitgestellt. Das folgende Beispiel zeigt einen response Abschnitt in JSON (auch die Struktur für Textantworten):
"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"
}
}
Das folgende Beispiel zeigt einen response Abschnitt 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>
Zulässige Endpunkte
Important
Diese Liste gilt nur für Azure SQL-Datenbank und azure SQL Managed Instance.
Es sind nur Aufrufe an Endpunkte für die folgenden Dienste zulässig:
| Azure-Dienst | Domain |
|---|---|
| Azure Functions | *.azurewebsites.net |
| Azure-App s-Dienst | *.azurewebsites.net |
| Azure App Service-Umgebung | *.appserviceenvironment.net |
| Azure Statische Webanwendungen | *.azurestaticapps.net |
| Azure Logic Apps | *.logic.azure.com |
| Azure Event Hubs | *.servicebus.windows.net |
| Azure-Ereignisraster | *.eventgrid.azure.net |
| Azure KI-Services | *.cognitiveservices.azure.com*.api.cognitive.microsoft.com |
| Azure OpenAI | *.openai.azure.com |
| PowerApps / Dataverse | *.api.crm.dynamics.com |
| Microsoft Dynamics | *.dynamics.com |
| Azure-Containerinstanzen | *.azurecontainer.io |
| Azure Container Apps – ein Dienst für containerbasierte Anwendungen | *.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 (Speicherdienst von Azure für unstrukturierte Daten) | *.blob.core.windows.net |
| Azure Files | *.file.core.windows.net |
| Azure Queue Storage (Warteschlangenspeicher) | *.queue.core.windows.net |
| Azure Tabellenspeicher | *.table.core.windows.net |
| Azure Communication Services | *.communications.azure.com |
| Bing Search | api.bing.microsoft.com |
| Azure Key Vault (ein Dienst zur sicheren Verwaltung kryptografischer Schlüssel) | *.vault.azure.net |
| Azure KI Cognitive Search | *.search.windows.net |
| Azure Maps | *.atlas.microsoft.com |
| Azure KI Übersetzer | api.cognitive.microsofttranslator.com |
Ausgehende Firewallregeln für Azure SQL-Datenbank und Azure Synapse Analytics-Kontrollmechanismus können verwendet werden, um den ausgehenden Zugriff auf externe Endpunkte weiter einzuschränken.
Note
Wenn Sie einen REST-Dienst aufrufen möchten, der nicht in der Liste zulässig ist, können Sie die API-Verwaltung verwenden, um den gewünschten Dienst sicher verfügbar zu machen und verfügbar zu sp_invoke_external_rest_endpointmachen.
Limits
Nutzlastgröße
Nutzlast, sowohl beim Empfang als auch beim Senden, wird UTF-8 codiert, wenn sie über das Kabel gesendet werden. In diesem Format ist die Größe auf 100 MB begrenzt.
URL-Länge
Die maximale URL-Länge (generiert nach Verwendung des @url Parameters und Hinzufügen der angegebenen Anmeldeinformationen zur Abfragezeichenfolge, falls vorhanden), beträgt 8 KB; die maximale Länge der Abfragezeichenfolge (Abfragezeichenfolge + Abfragezeichenfolge mit Anmeldeinformationen) beträgt 4 KB.
Größe der Kopfzeilen
Die maximale Anforderungs- und Antwortheadergröße (alle Kopfzeilenfelder: Kopfzeilen, die über @headers Parameter + Anmeldeinformationsheader + vom System bereitgestellte Header übergeben werden) beträgt 8 KB.
Throttling
Die Anzahl der gleichzeitigen Verbindungen mit externen Endpunkten, die über sp_invoke_external_rest_endpoint diese Verbindung durchgeführt werden, sind auf 10 % der Arbeitsthreads begrenzt, mit maximal 150 Mitarbeitern. Bei einer einzelnen Datenbankeinschränkung wird auf Datenbankebene erzwungen, während bei einer flexiblen Pooldrosselung sowohl auf Datenbank- als auch auf Poolebene erzwungen wird.
Führen Sie die folgende Abfrage aus, um zu überprüfen, wie viele gleichzeitige Verbindungen eine Datenbank erhalten kann:
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();
Wenn eine neue Verbindung mit einem externen Endpunkt sp_invoke_external_rest_endpoint versucht wird, wenn die maximalen gleichzeitigen Verbindungen bereits erreicht sind, wird der Fehler 10928 (oder 10936, wenn Sie die Grenzwerte für elastische Pools erreicht haben) ausgelöst. Beispiel:
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
Einige REST-Endpunkte erfordern eine Authentifizierung, um ordnungsgemäß aufgerufen zu werden. Die Authentifizierung kann in der Regel erfolgen, indem bestimmte Schlüsselwertpaare in der Abfragezeichenfolge oder in den MIT der Anforderung festgelegten HTTP-Headern übergeben werden.
Es ist möglich, DATABASE SCOPED CREDENTIAL Authentifizierungsdaten (z. B. ein Bearer-Token) sicher zu speichern, um von sp_invoke_external_rest_endpoint einem geschützten Endpunkt aufgerufen zu werden. Verwenden Sie beim Erstellen des DATABASE SCOPED CREDENTIALParameters, IDENTITY um anzugeben, welche Authentifizierungsdaten an den aufgerufenen Endpunkt übergeben werden und wie.
IDENTITY unterstützt vier Optionen:
-
HTTPEndpointHeaders: Senden von angegebenen Authentifizierungsdaten mithilfe der Anforderungsheader -
HTTPEndpointQueryString: Senden von angegebenen Authentifizierungsdaten mithilfe der Abfragezeichenfolge -
Managed Identity: Senden der vom System zugewiesenen verwalteten Identität mithilfe der Anforderungsheader -
Shared Access Signature: Bereitstellen eines eingeschränkten delegierten Zugriffs auf Ressourcen über eine signierte URL (auch als SAS bezeichnet)
Die erstellung DATABASE SCOPED CREDENTIAL kann über den parameter @credential verwendet werden:
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>];
Mit diesem IDENTITY Wert wird der DATABASE SCOPED CREDENTIAL Anforderungsheader hinzugefügt. Das Schlüssel-Wert-Paar, das die Authentifizierungsinformationen enthält, muss über den SECRET Parameter mit einem flachen JSON-Format bereitgestellt werden. Beispiel:
CREATE DATABASE SCOPED CREDENTIAL [https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>]
WITH IDENTITY = 'HTTPEndpointHeaders', SECRET = '{"x-functions-key":"<your-function-key-here>"}';
Namensregeln für Anmeldeinformationen
Die erstellten DATABASE SCOPED-ANMELDEINFORMATIONEN müssen bestimmten Regeln entsprechen, damit sie verwendet sp_invoke_external_rest_endpointwerden können. Die Regeln sind wie folgt:
- Muss eine gültige URL sein
- Die URL-Domäne muss eine dieser Domänen sein, die in der Zulassungsliste enthalten sind.
- Die URL darf keine Abfragezeichenfolge enthalten.
- Protokoll + Vollqualifizierter Domänenname (FQDN) der aufgerufenen URL muss mit Protokoll + FQDN des Anmeldeinformationsnamens übereinstimmen.
- Jeder Teil des aufgerufenen URL-Pfads muss vollständig mit dem jeweiligen Teil des URL-Pfads im Anmeldeinformationsnamen übereinstimmen.
- Die Anmeldeinformationen müssen auf einen Pfad verweisen, der allgemeiner als die Anforderungs-URL ist. Beispielsweise kann eine für den Pfad
https://northwind.azurewebsite.net/customerserstellte Anmeldeinformation nicht für die URL verwendet werden.https://northwind.azurewebsite.net
Regeln für die Sortierung und Anmeldeinformationen
RFC 3986 Section 6.2.2.1 gibt an, dass "Wenn ein URI Komponenten der generischen Syntax verwendet, gelten die Regeln für die Komponentensyntax immer; nämlich, dass das Schema und der Host die Groß-/Kleinschreibung nicht beachten" und RFC 7230 Section 2.7.3 erwähnt, dass "alle anderen in einer Groß-/Kleinschreibung verglichen werden".
Da auf Datenbankebene eine Sortierregel festgelegt ist, wird die folgende Logik angewendet, um mit der Datenbanksortierungsregel und dem oben genannten RFC in Einklang zu treten. (Die beschriebene Regel könnte möglicherweise restriktiver sein als die RFC-Regeln, z. B. wenn die Datenbank für die Verwendung einer Sortierung mit Groß-/Kleinschreibung festgelegt ist.):
- Überprüfen Sie, ob die URL und anmeldeinformationen mit rfc übereinstimmen, was bedeutet:
- Überprüfen sie das Schema und den Host mithilfe einer Sortierung ohne Groß-/Kleinschreibung (
Latin1_General_100_CI_AS_KS_WS_SC) - Überprüfen, ob alle anderen Segmente der URL in einer Sortierung mit Groß-/Kleinschreibung verglichen werden (
Latin1_General_100_BIN2)
- Überprüfen sie das Schema und den Host mithilfe einer Sortierung ohne Groß-/Kleinschreibung (
- Überprüfen Sie, ob die URL und die Anmeldeinformationen mit den Datenbanksortierungsregeln übereinstimmen (und ohne URL-Codierung).
Erteilen von Berechtigungen zur Verwendung einer Anmeldeinformation
Datenbankbenutzer, die auf DATENBANKBEREICHS-ANMELDEINFORMATIONEN zugreifen, müssen über die Berechtigung zum Verwenden dieser Anmeldeinformationen verfügen.
Um die Anmeldeinformationen zu verwenden, muss ein Datenbankbenutzer über die Berechtigung für bestimmte Anmeldeinformationen verfügen REFERENCES :
GRANT REFERENCES ON DATABASE SCOPED CREDENTIAL::[<CREDENTIAL_NAME>] TO [<PRINCIPAL>];
Remarks
Wartetyp
Wenn sp_invoke_external_rest_endpoint auf den Abschluss des Aufrufs des aufgerufenen Diensts gewartet wird, meldet er einen HTTP_EXTERNAL_CONNECTION Wartetyp.
HTTPS und TLS
Es werden nur Endpunkte unterstützt, die für die Verwendung von HTTPS mit TLS-Verschlüsselungsprotokoll konfiguriert sind.
HTTP-Umleitungen
sp_invoke_external_rest_endpoint folgt keiner HTTP-Umleitung, die als Antwort vom aufgerufenen Endpunkt empfangen wird.
HTTP-Header
sp_invoke_external_rest_endpoint fügt automatisch die folgenden Header in die HTTP-Anforderung ein:
-
inhaltstyp: auf
application/json; charset=utf-8 -
accept: Set to
application/json -
User-Agent: Zum Beispiel
<EDITION>/<PRODUCT VERSION>:SQL Azure/12.0.2000.8
Während der Benutzer-Agent immer von der gespeicherten Prozedur überschrieben wird, kann der Inhaltstyp und die Annahme von Headerwerten über den parameter @headers benutzerdefinierte werden. Nur die Medientypdirektive darf im Inhaltstyp angegeben werden und die Angabe der Zeichensatz- oder Begrenzungsdirektiven ist nicht möglich.
Anforderungs- und Antwortnutzlast unterstützte Medientypen
Im Folgenden finden Sie akzeptierte Werte für den Headerinhaltstyp.
- application/json
- application/vnd.microsoft.*.json
- application/xml
- application/vnd.microsoft.*.xml
- application/vnd.microsoft.*+xml
- application/x-www-form-urlencoded
- text/*
Für den Accept-Header sind die folgenden Werte zulässig.
- application/json
- application/xml
- text/*
Weitere Informationen zu Textkopfzeilentypen finden Sie in der Texttypregistrierung bei IANA.
Note
Wenn Sie den Aufruf des REST-Endpunkts mit anderen Tools wie cURL oder einem modernen REST-Client wie Schlaflosigkeit testen, stellen Sie sicher, dass sie dieselben Header enthalten, die automatisch eingefügt sp_invoke_external_rest_endpoint werden, um dasselbe Verhalten und die gleichen Ergebnisse zu haben.
Wiederholungszählungslogik
Wenn Sie den parameter @retry_count festlegen, wird die Anforderung wiederholt, wenn die folgenden Fehler aufgetreten sind:
HTTP-Fehler
| HTTP-Statuscode | Fehler | Description |
|---|---|---|
| 408 | Anforderungstimeout | Der Client hat keine Anforderung innerhalb des Zeitlimits des Servers oder das Servertimeout beim Warten erzeugt. |
| 429 | Zu viele Anforderungen | Der Client ist zinsgeschränkt. Wiederholen Sie die Zeit basierend auf dem Headerwert "Retry-After", falls angegeben. |
| 500 | Interner Serverfehler | Generischer Serverfehler. |
| 502 | Ungültiges Gateway | Der Server hat eine ungültige Antwort von einem Back-End erhalten. |
| 503 | Dienst nicht verfügbar | Gibt eine temporäre Überladung oder Ausfallzeit an. |
| 504 | Gatewaytimeout | Der Server hat keine rechtzeitige Antwort erhalten. |
Bewährte Methoden
Verwenden einer Batchverarbeitungsmethode
Wenn Sie eine Reihe von Zeilen an einen REST-Endpunkt senden müssen, z. B. an eine Azure-Funktion oder an einen Event Hub, empfiehlt es sich, die Zeilen in ein einzelnes JSON-Dokument zu stapeln, um den HTTPS-Aufrufaufwand für jede gesendete Zeile zu vermeiden. Dies kann beispielsweise mithilfe der FOR JSON Anweisung erfolgen:
-- 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 finden Sie einige Beispiele für die Integration sp_invoke_external_rest_endpoint in gängige Azure-Dienste wie Azure Functions oder Azure Event Hubs. Weitere Beispiele für die Integration in andere Dienste finden Sie auf GitHub.
A. Aufrufen einer Azure-Funktion mithilfe einer HTTP-Triggerbindung ohne Authentifizierung
Im folgenden Beispiel wird eine Azure-Funktion mithilfe einer HTTP-Triggerbindung aufgerufen, die anonymen Zugriff zulässt.
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. Aufrufen einer Azure-Funktion mithilfe einer HTTP-Triggerbindung mit einem Autorisierungsschlüssel
Im folgenden Beispiel wird eine Azure-Funktion mithilfe einer HTTP-Triggerbindung aufgerufen, die so konfiguriert ist, dass ein Autorisierungsschlüssel erforderlich ist. Der Autorisierungsschlüssel wird nach Bedarf von Azure Functions im x-function-key Header übergeben. Weitere Informationen finden Sie unter Azure Functions – API-Schlüsselautorisierung.
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. Lesen des Inhalts einer Datei aus Azure Blob Storage mit einem SAS-Token
In diesem Beispiel wird eine Datei aus Azure Blob Storage mit einem SAS-Token für die Authentifizierung gelesen. Die Ergebnisse werden in XML zurückgegeben, sodass Sie den Header "Accept":"application/xml"verwenden müssen.
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. Senden einer Nachricht an einen Ereignishub mithilfe der Azure SQL-Datenbank verwalteten Identität
In diesem Beispiel wird gezeigt, wie Sie Nachrichten mithilfe der verwalteten Azure SQL-Identität an Event Hubs senden können. Stellen Sie sicher, dass Sie die vom System verwaltete Identität für den Azure SQL-Datenbank logischen Server konfiguriert haben, auf dem Ihre Datenbank gehostet wird, z. B.:
az sql server update -g <resource-group> -n <azure-sql-server> --identity-type SystemAssigned
Konfigurieren Sie anschließend Event Hubs so, dass die verwaltete Identität von Azure SQL Server Nachrichten ("Azure Event Hubs Data Sender"-Rolle) an den gewünschten Event Hub senden kann. Weitere Informationen finden Sie unter Verwenden von Event Hubs mit verwalteten Identitäten.
Sobald dies erfolgt ist, können Sie den Managed Identity Identitätsnamen verwenden, wenn Sie die von der Datenbank verwendeten sp_invoke_external_rest_endpointAnmeldeinformationen mit Bereich definieren. Wie in der Authentifizierung einer Anwendung mit der Microsoft Entra-ID für den Zugriff auf Event Hubs-Ressourcen erläutert, lautet der Ressourcenname (oder die ID), der bei der Verwendung der Microsoft Entra-Authentifizierung verwendet werden soll 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. Lesen und Schreiben einer Datei in Azure File Storage mit einer Azure SQL-Datenbank bereichsbezogenen Anmeldeinformationen
In diesem Beispiel wird eine Datei mithilfe eines Azure SQL-Datenbank bereichsbezogenen Anmeldeinformationen für die Authentifizierung in einen Azure-Dateispeicher geschrieben und anschließend der Inhalt zurückgegeben. Die Ergebnisse werden in XML zurückgegeben, sodass Sie den Header "Accept":"application/xml"verwenden müssen.
Erstellen Sie zunächst einen Hauptschlüssel für die Azure SQL-Datenbank. Ersetzen Sie <password> es durch ein sicheres Kennwort.
CREATE MASTER KEY ENCRYPTION BY PASSWORD = '<password>';
GO
Erstellen Sie dann die Anmeldeinformationen für den Datenbankbereich mithilfe des SAS-Tokens, das vom Azure Blob Storage-Konto bereitgestellt wird. Ersetzen Sie <token> es durch das bereitgestellte SAS-Token.
CREATE DATABASE SCOPED CREDENTIAL [filestore]
WITH IDENTITY = 'SHARED ACCESS SIGNATURE', SECRET = '<token>';
GO
Erstellen Sie als Nächstes die Datei, und fügen Sie ihr Text mit den folgenden beiden Anweisungen hinzu. Ersetzen Sie <domain> den entsprechenden Pfad.
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
Verwenden Sie schließlich die folgende Anweisung, um die Datei zu lesen. Ersetzen Sie <domain> den entsprechenden Pfad.
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. Aufrufen einer Azure OpenAI mit verwalteter Identität
Im folgenden Beispiel wird ein Azure OpenAI-Modell mit verwalteten Identitäten in Microsoft Entra für Azure SQL aufgerufen. Ersetzen Sie <my-azure-openai-endpoint><model-deployment-name> ihren Azure OpenAI-Endpunkt bzw. ihren Modellnamen, und stellen Sie sicher, dass Sie die Managed Identity der OpenAI-Benutzerrolle "Cognitive Services" im Azure OpenAI-Dienst erteilt haben.
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
Verwandte Inhalte
- Ressourcenverwaltung in Azure SQL-Datenbank
- sys.dm_resource_governor_resource_pools_history_ex
- sys.dm_resource_governor_workload_groups_history_ex
- sys.dm_user_db_resource_governance
- GRANT (Datenbankberechtigungen) (Transact-SQL)
- DATENBANK-SCOPED CREDENTIAL ERSTELLEN (Transact-SQL)
- API-Verwaltung
- sp_invoke_external_rest_endpoint Verwendungsbeispiele