Mit SQL Server 2025 HTTP-APIs aufrufen

Mit SQL Server 2025 lässt sich erstmals direkt aus T-SQL heraus ein externer HTTPS-REST-Endpunkt aufrufen. Dafür stellt Microsoft die Systemprozedur sys.sp_invoke_external_rest_endpoint bereit. Die Idee dahinter ist ziemlich elegant: Die Datenbank ist nicht mehr nur der geduldige Klotz im Keller, der Daten verwaltet, sondern kann selbst aktiv reagieren und externe Systeme anstoßen – etwa Webhooks, REST-APIs, Azure-Dienste oder interne Fachservices. Microsoft führt diese Funktion offiziell als neue Möglichkeit in SQL Server 2025 auf, und dieser Artikel zeigt dazu einen praxisnahen Aufbau mit einem eigenen .NET-API als Zielsystem.

Der wichtigste Grundgedanke ist: SQL Server agiert hier als Client. Das heißt, ein T-SQL-Skript, ein Job oder eine gespeicherte Prozedur erkennt ein Ereignis – zum Beispiel einen abgeschlossenen Batchlauf, eine erfolgreiche Sicherung oder einen Statuswechsel – und sendet dann gezielt eine Nachricht an einen HTTP-Endpunkt oder ruft Daten von diesem ab. Im Gegensatz zu einem Polling-Ansatz muss also kein externes System ständig nachfragen, ob etwas passiert ist. Die Datenbank meldet sich selbst, sobald etwas Relevantes geschieht oder benötigt wird. Genau das macht das Verfahren für ereignisgetriebene Architekturen interessant.

HTTPS ist Pflicht

Der erste und härteste Punkt: SQL Server 2025 akzeptiert für diese Aufrufe nur HTTPS. Ein einfaches http:// wird nicht toleriert. Unverschlüsseltes HTTP wird konsequent abgelehnt, selbst in lokalen Entwicklungsumgebungen. Microsoft formuliert es in der Dokumentation klar und deutlich: Ohne TLS keine Party.

Für die Praxis bedeutet das mehr als nur „URL mit HTTPS“. Das Zertifikat muss zum Hostnamen passen. Läuft das API unter einem Rechnernamen oder einer DNS-Adresse, dann muss das Zertifikat genau für diesen Namen gültig sein. Ein lokales API, das nur auf localhost sauber konfiguriert ist, reicht nicht automatisch aus, wenn SQL Server es unter einem anderen Namen anspricht. Zertifikat, Hostname und Vertrauenskette müssen zusammenpassen.

Aktivierung und Berechtigungen

Die Funktionalität ist standardmäßig deaktiviert. Sie muss also zunächst aktiviert werden, bevor die Prozedur nutzbar ist. Zusätzlich braucht der ausführende Benutzer die passende Berechtigung für externe Endpunkte. Das ist wichtig, denn ohne diese Freigabe scheitert der Aufruf, selbst wenn der Rest sauber konfiguriert ist.

-- REST API-Aufrufe aktivieren
EXECUTE sp_configure 'external rest endpoint enabled', 1;
RECONFIGURE WITH OVERRIDE;
-- Berechtigung vergeben, wenn nötig
GRANT EXECUTE ANY EXTERNAL ENDPOINT TO [<PRINCIPAL>];

Für erste Tests mit sa- oder sysadmin-Rechten ist das nicht notwendig, es wird aber später bei den meisten Szenarien relevant.

Credentials

Für die Authentifizierung werden die benötigten Zugangsdaten typischerweise nicht im JSON-Body und auch nicht in der Querystring-Zeile mitgegeben, sondern als HTTP-Header. Das ist sauberer, standardisierter und trennt Sicherheitsinformationen von der eigentlichen Nutzlast.

Damit diese sensiblen Angaben nicht an sämtlichen Stellen im T-SQL-Code stehen müssen, können diese sicher als Credentials abgelegt und per Name (eigentlich per URL) bei einem Aufruf verwendet werden.

Dafür wird eine Master Key Encryption benötigt; es wird also ein Datenbank-Master-Key inklusive Kennwort als Grundlage für die geschützte Ablage geheimer Informationen verwendet. Das ist nichts Spezielles für HTTP-Aufrufe, sondern gilt für alle Arten von Credentials, die der SQL Server kennt.

-- Master Key für die Datenbank
IF NOT EXISTS (SELECT *
               FROM sys.symmetric_keys
               WHERE [name] = '##MS_DatabaseMasterKey##')
    BEGIN
        -- ALTER SERVICE MASTER KEY FORCE REGENERATE;
        CREATE MASTER KEY ENCRYPTION BY PASSWORD = N'<Geheim>';
    END
GO
-- Erstellen von Credentials unter Verwendung eines api-keys
CREATE DATABASE SCOPED CREDENTIAL [https://MeineUrl/]
    WITH IDENTITY = 'HTTPEndpointHeaders', secret = '{"api-key":"123"}';
GO
-- Und zentral ändern wenn nötig
ALTER DATABASE SCOPED CREDENTIAL [https://MeineUrl/]
    WITH IDENTITY = 'HTTPEndpointHeaders', secret = '{"api-key":"abc"}';
GO

Eine Besonderheit ist die Benennung der Credentials: Der Name des Credentials entspricht dem Ziel-URL oder einem passenden URL-Präfix. Beispielsweise kann https://LaptopK:7013 für alle darunterliegenden Pfade verwendet werden, oder man gibt detaillierter etwa https://LaptopK:7013/api/webhook an. Entscheidend sind Protokoll, Hostname und gegebenenfalls Port. Das ist praktisch, weil man Credentials gezielt für einen API-Bereich oder einen kompletten Host definieren kann.

Struktur der Nutzlast

Für den Request-Body, also die „Payload“, bietet sich JSON an. Aber auch XML ist denkbar, je nachdem, was der aufgerufene Server versteht und akzeptiert.

Ob der Inhalt dabei formatiert ist oder nicht, spielt keine Rolle. Hauptsache, das Format ist korrekt. Aus Performancegründen sollte aber nach Möglichkeit auf ein Format verzichtet werden, das mehr Zeichen bedeutet. Es sei noch einmal angemerkt, dass die Nutzlast (@playload) zwar vom Typ NVARCHAR(MAX) ist, aber natürlich mit den SQL-Server-Mitteln für JSON/XML erzeugt werden kann.

Der Aufruf

Hat man alles zusammen, ist der Aufruf an sich eigentlich recht einfach und besteht aus dem Aufruf einer Stored Procedure. Einige der Parameter, wie zum Beispiel das Time-out (@timeout) oder die Credentials (@credential), sind optional, wenn sie nicht benötigt werden oder der Standardwert verwendet werden soll.

DECLARE
    @url NVARCHAR(4000) = 'https://MeineUrl/embeddings?api-version=2023-05-15',
    @method NVARCHAR(10) = 'POST' /* GET | POST | PUT | PATCH | DELETE | HEAD */,
    @headers NVARCHAR(MAX) = N'{"Content-Type":"application/json"}',
    @payload NVARCHAR(MAX) = '{"input": "Dies ist ein Beispielinhalt."}',
    @timeout INT = 60, /* Default 30 sec */ 
    @ret INT,
    @response NVARCHAR(MAX);
EXEC @ret = sys.sp_invoke_external_rest_endpoint 
     @url = @url,
     @method = @method,
     @headers = @headers,
     @payload = @payload,
     @credential = [https://MeineUrl/]
     @timeout = @timeout,
     @response = @response output;

Die Rückgabe

Die direkte Rückgabe von sys.sp_invoke_external_rest_endpoint (@ret) ist entweder 0, wenn der HTTP-Status 2xx entspricht (Success) oder 0, wenn der Status keinen Erfolg darstellt. In beiden Fällen wurde der Aufruf technisch erfolgreich durchgeführt. Ist der Aufruf nicht möglich, wirft die Stored Procedure einen Fehler. So lässt sich nachvollziehen, ob der Aufruf erfolgreich war, ob ein Fehlercode vom Server kam oder ob schon auf Transportebene etwas schiefgelaufen ist.

Die vollständige Rückgabe (@response) erfolgt strukturiert, typischerweise ebenfalls als JSON. Die direkte Rückgabe von XML ist ebenfalls möglich.

-- Rückgabe JSON
{
  "response": {
    "status": {
      "http": {
        "code": "",
        "description": ""
      }
    },
    "headers": {}
  },
  "result": {}
}
-- Rückgabe XML
<output>
    <response>
        <status>
            <http code="" description=" " />
        </status>
        <headers>
            <header key="" value="" />
            <header key="" value="" />
        </headers>
    </response>
    <result>
    </result>
</output>

Die genauen Details hängen natürlich von dem konkreten Aufruf ab.

Fazit

API-Aufrufe mit SQL Server 2025 sind kein Spielzeug, sondern ein ernst zu nehmender Integrationsmechanismus. Die zentrale Technik ist sys.sp_invoke_external_rest_endpoint, mit der SQL Server direkt HTTPS-Endpunkte ansprechen kann. Dafür müssen drei Dinge sauber vorbereitet sein: erstens HTTPS mit funktionierendem und vertrauenswürdigem Zertifikat, zweitens sicher gespeicherte Credentials auf Basis eines Master Keys, drittens klare Berechtigungen und eine strukturierte JSON/XML-Nutzlast. Sind diese drei Punkte sauber umgesetzt, kann SQL Server 2025 externe Systeme ereignisgesteuert informieren, Webhooks auslösen oder REST-Services nutzen – stabil, nachvollziehbar und deutlich eleganter als viele Bastellösungen mit Polling oder Hilfsdiensten.