Freigeben über

Azure SQL-Datenquelle für einen Resolver

  • Artikel

GILT FÜR: Developer | Basic | Basic v2 | Standard | Standard v2 | Premium

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

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

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

Zuweisen von Rollen

  1. Navigieren Sie im Azure-Portal zu Ihrer Azure SQL-Datenbank-Ressource.

  2. Wählen Sie Abfrage-Editor (Vorschau) aus.

  3. Melden Sie sich über die Active Directory-Authentifizierung an.

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

Zugehöriger Inhalt

Weitere Informationen zum Arbeiten mit Richtlinien finden Sie hier: