Freigeben über

sp_invoke_external_rest_endpoint (Transact-SQL)

  • Artikel

Gilt für: Azure SQL-Datenbank 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.

Syntax

Transact-SQL-Syntaxkonventionen

EXEC @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 ]

Argumente

[ @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. Header, die in der Namensliste "Verbotene Header" definiert sind, werden ignoriert, auch wenn sie explizit im @headers-Parameter übergeben werden. 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, . HEADDELETE @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.

[ @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).

Rückgabewert

Die Ausführung wird zurückgegeben 0 , wenn der HTTPS-Aufruf abgeschlossen wurde, und der empfangene HTTP-Statuscode ist 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.

Berechtigungen

Erfordert EXECUTE ANY EXTERNAL ENDPOINT database permission.

Zum Beispiel:

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

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

Speziell:

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

Speziell:

  • 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 wird neben dem HTTP-Statuscode und der Beschreibung der gesamte Satz empfangener 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

Es sind nur Aufrufe an Endpunkte in den folgenden Diensten zulässig:

Azure-Dienst Domäne
Azure-Funktionen *.azurewebsites.net
Azure-App s-Dienst *.azurewebsites.net
Azure App Service-Umgebung *.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 Cognitive Services *.cognitiveservices.azure.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 Table Storage *.table.core.windows.net
Azure Communication Services *.communications.azure.com
Bing-Suche api.bing.microsoft.com
Azure Key Vault *.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.

Hinweis

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.

Grenzwerte

Größe der Nutzdaten

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.

Drosselung

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

Anmeldeinformationen

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-ANMELDEINFORMATIONEN zum sicheren Speichern von Authentifizierungsdaten (z. B. einem Bearer-Token) zu verwenden, die zum sp_invoke_external_rest_endpoint Aufrufen eines geschützten Endpunkts verwendet werden. Verwenden Sie beim Erstellen der DATABASE SCOPED CREDENTIAL den PARAMETER 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 erstellten DATABASE SCOPED-ANMELDEINFORMATIONEN können über den parameter @credential verwendet werden:

EXEC 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 werden die DATABASE SCOPED-ANMELDEINFORMATIONEN den Anforderungsheadern hinzugefügt. Das Schlüssel-Wert-Paar, das die Authentifizierungsinformationen enthält, muss über den SECRET-Parameter mit einem flachen JSON-Format bereitgestellt werden. Zum 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 die folgenden:

  • 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/customers erstellte 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 auf groß- und kleinschreibungsbezogene Weise verglichen werden".

Da eine Sortierregel auf Datenbankebene festgelegt ist, wird die folgende Logik angewendet, um mit der Datenbanksortierungsregel und der oben genannten RFC in Einklang zu stehen. (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.):

  1. Ü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)
  2. Ü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>];

Hinweise

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 mindestens TLS 1.2-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: set <EDITION>/<PRODUCT VERSION> for example: 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.

  • Anwendung/json
  • application/xml
  • Text/*

Weitere Informationen zu Textkopfzeilentypen finden Sie in der Texttypregistrierung bei IANA.

Hinweis

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.

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 INT,
    @response AS NVARCHAR(MAX);

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

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

Beispiele

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 INT, @response NVARCHAR(MAX);

EXEC @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 INT, @response NVARCHAR(MAX);

EXEC @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 die Verwendung des Headers "Accept":"application/xml" erforderlich ist.

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

EXEC @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 geschehen ist, können Sie den Managed Identity Identitätsnamen verwenden, wenn Sie die Anmeldeinformationen für den Datenbankbereich definieren, die von sp_invoke_external_rest_endpoint. 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 UNIQUEIDENTIFIER = NEWID();
DECLARE @payload NVARCHAR(MAX) = (
        SELECT *
        FROM (
            VALUES (@Id, 'John', 'Doe')
            ) AS UserTable(UserId, FirstName, LastName)
        FOR JSON AUTO,
            WITHOUT_ARRAY_WRAPPER
        )
DECLARE @url NVARCHAR(4000) = 'https://<EVENT-HUBS-NAME>.servicebus.windows.net/from-sql/messages';
DECLARE @headers NVARCHAR(4000) = N'{"BrokerProperties": "' + STRING_ESCAPE('{"PartitionKey": "' + CAST(@Id AS NVARCHAR(36)) + '"}', 'json') + '"}'
DECLARE @ret INT, @response NVARCHAR(MAX);

EXEC @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 die Verwendung des Headers "Accept":"application/xml" erforderlich ist.

Erstellen Sie zunächst einen Hauptschlüssel für die Azure SQL-Datenbank

create master key encryption by password = '2112templesmlm2BTS21.qwqw!@0dvd'
go

Erstellen Sie dann die Anmeldeinformationen für den Datenbankbereich mithilfe des SAS-Tokens, das vom Azure Blob Storage-Konto bereitgestellt wird.

create database scoped credential [filestore]
with identity='SHARED ACCESS SIGNATURE',
secret='sv=2022-11-02&ss=bfqt&srt=sco&sp=seespotrun&se=2023-08-03T02:21:25Z&st=2023-08-02T18:21:25Z&spr=https&sig=WWwwWWwwWWYaKCheeseNXCCCCCCDDDDDSSSSSU%3D'
go

Erstellen Sie als Nächstes die Datei, und fügen Sie ihr Text mit den folgenden beiden Anweisungen hinzu:

declare @payload nvarchar(max) = (select * from (values('Hello from Azure SQL!', sysdatetime())) payload([message], [timestamp])for json auto, without_array_wrapper)
declare @response nvarchar(max), @url nvarchar(max), @headers nvarchar(1000);
declare @len int = len(@payload)

-- Create the File
set @url = 'https://myfiles.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')
exec 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://myfiles.file.core.windows.net/myfiles/test-me-from-azure-sql.json'
set @url += '?comp=range'
exec 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.

declare @response nvarchar(max);
declare @url nvarchar(max) = 'https://myfiles.file.core.windows.net/myfiles/test-me-from-azure-sql.json'
exec sp_invoke_external_rest_endpoint
    @url = @url,
    @headers = '{"Accept":"application/xml"}',
    @credential = [filestore],
    @method = 'GET',
    @response = @response output
select cast(@response as xml)
go

Zugehöriger Inhalt