リゾルバーの Azure SQL データ ソース

適用対象: Developer | Basic | Basic v2 | Standard | Standard v2 | Premium | Premium v2

sql-data-source リゾルバー ポリシーは、Azure SQL データベースに対する Transact-SQL (T-SQL) 要求と、GraphQL スキーマ内のオブジェクト型とフィールドのデータを解決するためのオプションの応答を構成します。 スキーマは API Management に GraphQL API としてインポートする必要があります。

Note

このポリシーはプレビュー段階です。 現時点では、ポリシーは API Management の従量課金レベルではサポートされていません。

Note

ポリシーの要素と子要素を、ポリシー ステートメントで指定された順序で設定します。 API Management ポリシーを設定または編集する方法について説明します。

ポリシー ステートメント

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

要素

名前	説明	必須
connection-info	Azure SQL データベースへの接続を指定します。	はい
include-fragment	ポリシー定義にポリシー フラグメントを挿入します。 複数のフラグメントがある場合は、追加の include-fragment 要素を追加します。	いいえ
request	リゾルバーの T-SQL 要求と省略可能なパラメーターを指定します。	はい
response	必要に応じて、Azure SQL データベースからの応答を構成する子ポリシーを指定します。 指定しない場合、応答は JSON として Azure SQL から返されます。	いいえ

connection-info 要素

Note

特に明記されている場合を除き、各子要素は最大で 1 回指定できます。 リストされている順序で要素を指定します。

要素	説明	必須
connection-string	Azure SQL の接続文字列を指定します。 接続文字列は、API Management の マネージド ID が構成されている場合、SQL 認証 (ユーザー名とパスワード) または Microsoft Entra 認証を使用します。	はい
include-fragment	ポリシー定義にポリシー フラグメントを挿入します。 複数のフラグメントがある場合は、追加の include-fragment 要素を追加します。	いいえ
authentication-certificate	リゾルバーの SQL 要求内でクライアント証明書を使用して認証します。	いいえ

接続文字列属性

属性	説明	必要	Default
use-managed-identity	ブール型。 接続文字列内のユーザー名とパスワードの代わりに、API Management インスタンスのシステム割り当てマネージド ID を Azure SQL データベースへの接続に使用するかどうかを指定します。 ポリシー式を使用できます。 Azure SQL データベースにアクセスするように ID を構成する必要があります。	いいえ	false

要求の属性

属性	説明	必要	Default
single-result	ブール型。 クエリに対する応答が最大でも 1 行で返される必要があるかどうかを指定します。 ポリシー式を使用できます。	いいえ	false

要求の要素

注意

各子要素は、最大で 1 回指定できます。 リストされている順序で要素を指定します。

要素	説明	必須
include-fragment	ポリシー定義にポリシー フラグメントを挿入します。	No
set-body	リゾルバーの SQL 要求の本文を設定します。	いいえ
sql-statement	Azure SQL データベースへの要求の T-SQL ステートメント。 SQL ステートメントには、順番に実行される UPDATE、DELETE、SELECT などの複数の独立したサブステートメントを含めることができます。 結果は、最後のサブステートメントから返されます。	はい
parameters	要求の parameter サブ要素内の SQL パラメーターの一覧。	いいえ

パラメーター属性

属性	説明	必要	Default
name	文字列 をオンにします。 SQL パラメーターの名前。	はい	該当なし
sql-type	文字列。 SQL パラメーターのデータ型です。	いいえ	該当なし

応答の要素

Note

各子要素は、最大で 1 回指定できます。 リストされている順序で要素を指定します。

名前	説明	必須
include-fragment	ポリシー定義にポリシー フラグメントを挿入します。	No
set-body	リゾルバーの応答の本文を設定します。	No
publish-event	GraphQL API スキーマで指定された 1 つ以上のサブスクリプションにイベントを発行します。	いいえ

使用法

• ポリシー スコープ: GraphQL リゾルバー
• ゲートウェイ: クラシック、v2

使用上の注意

• このポリシーを使用してリゾルバーを構成および管理するには、「GraphQL リゾルバーの構成」を参照してください。
• このポリシーは、スキーマ内の一致する操作の種類の中の 1 つのフィールドを解決する場合にのみ呼び出されます。

マネージド ID と Azure SQL の統合を構成する

ユーザー名とパスワードを使用して SQL 認証を構成する代わりに、Azure SQL へのアクセスのための API Management システム割り当てマネージド ID を構成できます。 バックグランドに関しては、Azure SQL での Microsoft Entra 認証の構成および管理に関する説明を参照してください。

前提条件

• API Management インスタンスで、システム割り当てマネージド ID を有効にします。

Microsoft Entra ID アクセスを有効にする

Microsoft Entra ユーザーをサーバーの管理者として割り当てることで、SQL Database への Microsoft Entra 認証を有効にします。

1. ポータルで、Azure SQL サーバーに移動します。
2. [Microsoft Entra ID] を選びます。
3. [管理者の設定] を選択し、自分または自分が所属するグループを選択します。
4. [保存] を選択します。

ロールを割り当てる

1. ポータルで、Azure SQL データベースに移動します。

2. [クエリ エディター (プレビュー)] を選択します。

3. Active Directory 認証を使用してログインします。

4. 次の SQL スクリプトを実行します。 <identity-name> を API Management インスタンスの名前で置き換えます。

   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
   

例

スキーマの例

このセクションの例は、次の GraphQL スキーマのリゾルバーです。

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
}

単一結果 T-SQL 要求を使用した GraphQL クエリのリゾルバー

次の例では、バックエンド Azure SQL データベースに対して単一結果 T-SQL 要求を行うことで、GraphQL クエリを解決します。 接続文字列は、ユーザー名とパスワードを使用した SQL 認証を使用し、名前付き値を使用して提供されます。 応答は、1 つの行を表す 1 つの JSON オブジェクトとして返されます。

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

変換された複数行クエリ応答を持つ GraphQL クエリのリゾルバー

次の例では、Azure SQL データベースへの T-SQL クエリを使用して GraphQL クエリを解決します。 データベースへの接続では、API Management インスタンスのシステム割り当てマネージド ID が使用されます。 Azure SQL データベースにアクセスするように ID を構成する必要があります。

クエリ パラメーターには、context.GraphQL.Arguments コンテキスト変数を使用してアクセスします。 複数行クエリ応答は、set-body ポリシーを液体テンプレートと使用して変換されます。

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

GraphQL 変化のリゾルバー

次の例では、T-SQL INSERT ステートメントを使用して GraphQL の変化を解決し、行を Azure SQL データベースに挿入します。 データベースへの接続では、API Management インスタンスのシステム割り当てマネージド ID が使用されます。 Azure SQL データベースにアクセスするように ID を構成する必要があります。

<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 リゾルバー

関連するコンテンツ

ポリシーに対する処理の詳細については、次のトピックを参照してください。

• チュートリアル:API を変換および保護する
• ポリシー ステートメントとその設定の一覧に関するポリシー リファレンス
• ポリシー式
• ポリシーの設定または編集
• ポリシー構成を再利用する
• ポリシー スニペットのリポジトリ
• Azure API Management ポリシー ツールキット
• Azure で Microsoft Copilot を使用してポリシーを作成する