Azure SQL-Datenquelle für einen Resolver

Artikel
03/18/2024

Die Resolver-Richtlinie sql-data-source konfiguriert eine Transact-SQL-Anforderung (T-SQL) an eine Azure SQL-Datenbank und eine optionale Antwort zum Auflösen von Daten für einen Objekttyp und ein Feld in einem GraphQL-Schema. Das Schema muss als GraphQL-API in API Management importiert werden.

Hinweis

Diese Richtlinie befindet sich in der Vorschau. Derzeit wird die Richtlinie auf der Verbrauchsebene von API Management nicht unterstützt.

Hinweis

Legen Sie die Elemente und untergeordneten Elemente einer Richtlinie in der Reihenfolge fest, die in der Richtlinienanweisung angegeben ist. Erfahren Sie mehr darüber, wie Sie API Management-Richtlinien festlegen oder bearbeiten.

Richtlinienanweisung

<sql-data-source> 
    <connection-info>
        <connection-string use-managed-identity="true | false">
            Azure SQL connection string
        </connection-string>
        <include-fragment>...include-fragment policy configuration...</include-fragment>
        <authentication-certificate>...authentication-certificate policy configuration...</authentication-certificate>     
    </connection-info>
    <include-fragment>...include-fragment policy configuration...</include-fragment>
    <request single-result="true | false">
        <include-fragment>...include-fragment policy configuration...</include-fragment>
        <set-body>...set-body policy configuration...</set-body>
        <sql-statement>T-SQL query</sql-statement>
        <parameters>
            <parameter sql-type="parameter type" name="Query parameter name in @ notation">
                "Query parameter value or expression"
            </parameter>
            <!-- if there are multiple parameters, then add additional parameter elements -->
        </parameters>
    </request>
    <response>
        <include-fragment>...include-fragment policy configuration...</include-fragment>
        <set-body>...set-body policy configuration...</set-body>
        <publish-event>...publish-event policy configuration...</publish-event>
    </response>
</sql-data-source>

Elemente

Name	BESCHREIBUNG	Erforderlich
connection-info	Gibt die Verbindung mit der Azure SQL-Datenbank an.	Ja
include-fragment	Fügt ein Richtlinienfragment in die Richtliniendefinition ein. Wenn mehrere Fragmente vorhanden sind, fügen Sie zusätzliche `include-fragment`-Elemente hinzu.	Nein
Anforderung	Gibt die T-SQL-Anforderung des Resolvers und optionale Parameter an.	Ja
response	Gibt optional untergeordnete Richtlinien an, um die Antwort aus der Azure SQL-Datenbank zu konfigurieren. Wenn Sie nichts anderes angegeben, wird die Antwort von Azure SQL als JSON zurückgegeben.	Nein

connection-info-Elemente

Hinweis

Sofern nicht anders angegeben, darf jedes untergeordnete Element höchstens einmal festgelegt werden. Geben Sie Elemente in der aufgeführten Reihenfolge an.

Element	BESCHREIBUNG	Erforderlich
connection-string	Gibt die Azure SQL-Verbindungszeichenfolge an. Die Verbindungszeichenfolge verwendet entweder die SQL-Authentifizierung (Benutzername und Kennwort) oder die Microsoft Entra-Authentifizierung, wenn eine verwaltete API Management-Identität konfiguriert ist.	Ja
include-fragment	Fügt ein Richtlinienfragment in die Richtliniendefinition ein. Wenn mehrere Fragmente vorhanden sind, fügen Sie zusätzliche `include-fragment`-Elemente hinzu.	Nein
authentication-certificate	Authentifiziert sich mithilfe eines Clientzertifikats in der SQL-Anforderung des Resolvers.	Nein

Attribute von „connection-string“

attribute	BESCHREIBUNG	Erforderlich	Standard
use-managed-identity	Boolesch. Gibt an, ob die systemseitig zugewiesene verwaltete Identität der API Management-Instanz anstelle eines Benutzernamens und Kennworts in der Verbindungszeichenfolge für die Verbindung mit der Azure SQL-Datenbank verwendet werden soll. Richtlinienausdrücke sind zulässig. Die Identität muss für den Zugriff auf die Azure SQL-Datenbank konfiguriert werden.	Nein	`false`

request-Attribut

attribute	BESCHREIBUNG	Erforderlich	Standard
single-result	Boolesch. Gibt an, ob die Antwort auf die Abfrage höchstens eine Zeile zurückgibt. Richtlinienausdrücke sind zulässig.	Nein	`false`

request-Elemente

Hinweis

Jedes untergeordnete Element kann höchstens einmal angegeben werden. Geben Sie Elemente in der aufgeführten Reihenfolge an.

Element	BESCHREIBUNG	Erforderlich
include-fragment	Fügt ein Richtlinienfragment in die Richtliniendefinition ein.	Nein
set-body	Legt den Text in der SQL-Anforderung des Resolvers fest.	Nein
sql-statement	Eine T-SQL-Anweisung für die Anforderung an die Azure SQL-Datenbank. Die SQL-Anweisung kann mehrere unabhängige Unteranweisungen wie UPDATE, DELETE und SELECT enthalten, die nacheinander ausgeführt werden. Die Ergebnisse werden von der letzten Unteranweisung zurückgegeben.	Ja
parameters	Eine Liste von SQL-Parametern in `parameter` Unterelementen für die Anforderung.	Nein

Parameterattribute

attribute	BESCHREIBUNG	Erforderlich	Standard
name	Eine Zeichenfolge. Der Name des SQL-Parameters.	Ja	–
sql-type	Zeichenfolge. Der Datentyp des SQL-Parameters.	Nein	–

response-Elemente

Hinweis

Jedes untergeordnete Element kann höchstens einmal angegeben werden. Geben Sie Elemente in der aufgeführten Reihenfolge an.

Name	BESCHREIBUNG	Erforderlich
include-fragment	Fügt ein Richtlinienfragment in die Richtliniendefinition ein.	Nein
set-body	Legt den Text in der Antwort des Resolvers fest.	Nein
publish-event	Veröffentlicht ein Ereignis für ein oder mehrere Abonnements, die im GraphQL-API-Schema angegeben sind.	Nein

Verwendung

Richtlinienbereiche: GraphQL-Auflöser
Gateways: klassisch, v2

Hinweise zur Verwendung

Informationen zum Konfigurieren und Verwalten eines Resolvers mit dieser Richtlinie finden Sie unter Konfigurieren eines GraphQL-Resolvers.
Diese Richtlinie wird nur aufgerufen, wenn ein einzelnes Feld in einem übereinstimmenden Vorgangstyp im Schema aufgelöst wird.

Konfigurieren der Integration verwalteter Identitäten mit Azure SQL

Sie können eine von API Management systemseitig zugewiesene verwaltete Identität für den Zugriff auf Azure SQL konfigurieren, anstatt die SQL-Authentifizierung mit Benutzername und Kennwort zu konfigurieren. Weitere Informationen finden Sie unter Konfigurieren und Verwalten der Microsoft Entra-Authentifizierung mit Azure SQL.

Voraussetzungen

Aktivieren Sie eine systemseitig zugewiesene verwaltete Identität in Ihrer API Management-Instanz.

Aktivieren des Microsoft Entra ID-Zugriffs

Aktivieren Sie die Microsoft Entra-Authentifizierung für SQL-Datenbank, indem Sie eine*n Microsoft Entra-Benutzer*in als Administrator*in des Servers zuweisen.

Navigieren Sie im Portal zu Ihrem Azure SQL Server.
Wählen Sie Microsoft Entra ID aus.
Wählen Sie Administrator festlegen aus, und wählen Sie sich selbst oder eine Gruppe aus, der Sie angehören.
Wählen Sie Speichern aus.

Zuweisen von Rollen

Navigieren Sie im Azure-Portal zu Ihrer Azure SQL-Datenbank-Ressource.
Wählen Sie Abfrage-Editor (Vorschau) aus.
Melden Sie sich über die Active Directory-Authentifizierung an.

Führen Sie das folgende SQL-Skript aus. Ersetzen Sie <identity-name> durch den Namen Ihrer API Management-Instanz.

CREATE USER [<identity-name>] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [<identity-name>];
ALTER ROLE db_datawriter ADD MEMBER [<identity-name>];
ALTER ROLE db_ddladmin ADD MEMBER [<identity-name>];
GO

Beispiele

Beispielschema

Die Beispiele in diesem Abschnitt sind Resolver für das folgende GraphQL Schema:

type Family {
  id: Int!
  name: String!
}

type Person {
  id: Int!
  name: String!
}

type PersonQueryResult {
  items: [Person]  
}

type Query {
  familyById(familyId: Int!): Family
  familyMembers(familyId: Int!): PersonQueryResult
}

type Mutation {
  createFamily(familyId: Int!, familyName: String!): Family
}

Resolver für GraphQL-Abfrage mithilfe einer T-SQL-Anforderung mit einem einzelnen Ergebnis

Im folgenden Beispiel wird eine GraphQL-Abfrage aufgelöst, indem eine T-SQL-Anforderung mit einem einzelnen Ergebnis an eine Azure SQL-Datenbank im Back-End gesendet wird. Die Verbindungszeichenfolge verwendet die SQL-Authentifizierung mit Benutzername und Kennwort und wird mit einem benannten Wert bereitgestellt. Die Antwort wird als einzelnes JSON-Objekt zurückgegeben, das eine einzelne Zeile darstellt.

<sql-data-source>
    <connection-info>
        <connection-string>
            {{my-connection-string}}
        </connection-string>
    </connection-info>
    <request single-result="true">
        <sql-statement>
            SELECT 
                f.[Id] AS [id]
                f.[Name] AS [name]
            WHERE @familyId = f.[Id] 
        </sql-statement> 
        <parameters> 
            <parameter name="@familyId">       
                @(context.GraphQL.Arguments["id"])
            </parameter> 
        </parameters> 
    </request>
    <response />
</sql-data-source>

Resolver für GraphQL-Abfrage mit transformierter mehrzeiliger Abfrageantwort

Im folgenden Beispiel wird eine GraphQL-Abfrage mithilfe einer T-SQL-Abfrage an eine Azure SQL-Datenbank aufgelöst. Die Verbindung zur Datenbank verwendet die systemseitig zugewiesene verwaltete Identität der API Management-Instanz. Die Identität muss für den Zugriff auf die Azure SQL-Datenbank konfiguriert werden.

Auf den Abfrageparameter wird über die Kontextvariable context.GraphQL.Arguments zugegriffen. Die mehrzeilige Abfrageantwort wird mithilfe der Richtlinie set-body mit einer Liquid-Vorlage transformiert.

<sql-data-source> 
    <connection-info>
        <connection-string use-managed-identity="true">
            Server=tcp:{your_server_name}.database.windows.net,1433;Initial Catalog={your_database_name}; 
        </connection-string>
    </connection-info> 
    <request> 
        <sql-statement> 
            SELECT 
                p.[Id] AS [Id] 
                p.[FirstName] AS [FirstName] 
                p.[LastName] AS [LastName] 
            FROM [Person] p 
            JOIN [Family] f ON p.[FamilyId] = f.[Id] 
            WHERE @familyId = f.[Id] 
        </sql-statement> 
        <parameters> 
            <parameter name="@familyId">       
                @(context.GraphQL.Arguments["id"])
            </parameter> 
        </parameters> 
    </request> 
    <response> 
        <set-body template="liquid"> 
            { 
                "items": [ 
                    {% JSONArray For person in body.items %} 
                        "id": "{{ person.id }}" 
                        "name": "{{ person.firstName }} + "" "" + {{body.lastName}}" 
                    {% endJSONArrayFor %} 
                ] 
            } 
        </set-body> 
  </response> 
</sql-data-source>

Resolver für eine GraphQL-Mutation

Im folgenden Beispiel wird eine GraphQL-Mutation mithilfe einer T-SQL INSERT-Anweisung aufgelöst, um eine Zeile und eine Azure SQL-Datenbank einzufügen. Die Verbindung zur Datenbank verwendet die systemseitig zugewiesene verwaltete Identität der API Management-Instanz. Die Identität muss für den Zugriff auf die Azure SQL-Datenbank konfiguriert werden.

<sql-data-source> 
    <connection-info>
        <connection-string use-managed-identity="true">
            Server=tcp:{your_server_name}.database.windows.net,1433;Initial Catalog={your_database_name};</connection-string>
    </connection-info> 
    <request single-result="true"> 
        <sql-statement> 
                INSERT INTO [dbo].[Family]
                       ([Id]
                       ,[Name])
                VALUES
                       (@familyId
                       , @familyName)

                SELECT
                    f.[Id] AS [id],
                    f.[Name] AS [name]
                FROM [Family] f
                WHERE @familyId = f.[Id]
        </sql-statement> 
        <parameters> 
            <parameter name="@familyId">       
                @(context.GraphQL.Arguments["id"])
            </parameter>
            <parameter name="@familyName">       
                @(context.GraphQL.Arguments["name"])
            </parameter> 
        </parameters> 
    </request>    
</sql-data-source>

GraphQL-Resolver

Weitere Informationen zum Arbeiten mit Richtlinien finden Sie hier:

Tutorial: Transformieren und Schützen Ihrer API
Unter Richtlinien für die API-Verwaltung finden Sie eine komplette Liste der Richtlinienanweisungen und der zugehörigen Einstellungen.
Richtlinienausdrücke
Festlegen oder Bearbeiten von Richtlinien
Wiederverwenden von Richtlinienkonfigurationen
Repository für Richtliniencodeausschnitte
Erstellen von Richtlinien mit Microsoft Copilot für Azure

Azure SQL-Datenquelle für einen Resolver

Richtlinienanweisung

Elemente

connection-info-Elemente

Attribute von „connection-string“

request-Attribut

request-Elemente

Parameterattribute

response-Elemente

Verwendung

Hinweise zur Verwendung

Konfigurieren der Integration verwalteter Identitäten mit Azure SQL

Voraussetzungen

Aktivieren des Microsoft Entra ID-Zugriffs

Zuweisen von Rollen

Beispiele

Beispielschema

Resolver für GraphQL-Abfrage mithilfe einer T-SQL-Anforderung mit einem einzelnen Ergebnis

Resolver für GraphQL-Abfrage mit transformierter mehrzeiliger Abfrageantwort

Resolver für eine GraphQL-Mutation

Verwandte Richtlinien

Zugehöriger Inhalt

Zusätzliche Ressourcen