해결 프로그램을 위한 Azure SQL 데이터 원본

적용 대상: 개발자 | 기본 | 기본 v2 | 표준 | 표준 v2 | 프리미엄

sql-data-source 해결 프로그램 정책은 Azure SQL 데이터베이스에 대한 T-SQL(Transact-SQL) 요청과 GraphQL 스키마의 개체 형식 및 필드의 resolve 데이터에 대한 선택적 응답을 구성합니다. 스키마는 GraphQL API로 API Management에 가져와야 합니다.

참고 항목

이 정책은 미리 보기로 제공됩니다. 현재 이 정책은 API Management 소비 계층에서 지원되지 않습니다.

참고 항목

정책 문에 제공된 순서대로 정책의 요소 및 자식 요소를 설정합니다. 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> 

Elements

이름	설명	필수
connection-info	Azure SQL 데이터베이스에 대한 연결을 지정합니다.	예
include-fragment	정책 정의에 정책 조각을 삽입합니다. 헤더가 여러 개 있는 경우 추가 include-fragment 요소를 추가합니다.	아니요
request	해결 프로그램의 T-SQL 요청과 선택적 매개 변수를 지정합니다.	예
응답	필요에 따라 Azure SQL 데이터베이스에서 응답을 구성하는 자식 정책을 지정합니다. 지정하지 않으면 응답은 Azure SQL에서 JSON으로 반환됩니다.	아니요

connection-info 요소

참고 항목

언급된 경우를 제외하고 각 자식 요소를 한 번에 지정할 수 있습니다. 나열된 순서대로 요소를 지정합니다.

요소	설명	필수
connection-string	Azure SQL 연결 문자열을 지정합니다. 연결 문자열은 API Management 관리 ID가 구성된 경우 SQL 인증(사용자 이름 및 암호) 또는 Microsoft Entra 인증을 사용합니다.	예
include-fragment	정책 정의에 정책 조각을 삽입합니다. 헤더가 여러 개 있는 경우 추가 include-fragment 요소를 추가합니다.	아니요
authentication-certificate	해결 프로그램의 SQL 요청에서 클라이언트 인증서를 사용하여 인증합니다.	아니요

connection-string 특성

attribute	설명	필수 항목	기본값
use-managed-identity	부울입니다. 연결 문자열의 사용자 이름 및 암호 대신 Azure SQL 데이터베이스에 연결하는 데 API Management 인스턴스의 시스템 할당 관리 ID를 사용할지 여부를 지정합니다. 정책 식이 허용됩니다. Azure SQL 데이터베이스에 액세스하도록 ID를 구성해야 합니다.	아니요	false

요청 특성

attribute	설명	필수 항목	기본값
single-result	부울입니다. 쿼리에 대한 응답이 최대 한 행을 반환할지 여부를 지정합니다. 정책 식이 허용됩니다.	아니요	false

요청 요소

참고 항목

각 자식 요소를 최대 한 번 지정할 수 있습니다. 나열된 순서대로 요소를 지정합니다.

요소	설명	필수
include-fragment	정책 정의에 정책 조각을 삽입합니다.	아니요
set-body	해결 프로그램의 SQL 요청에서 본문을 설정합니다.	아니요
sql-statement	Azure SQL 데이터베이스에 대한 요청의 T-SQL 문입니다. SQL 문에는 순서대로 실행될 UPDATE, DELETE, SELECT와 같은 여러 독립적 하위 문이 포함될 수 있습니다. 결과는 최종 하위 문에서 반환됩니다.	예
parameters	요청에 대한 parameter 하위 요소의 SQL 매개 변수 목록입니다.	아니요

parameter 특성

attribute	설명	필수 항목	기본값
name	문자열입니다. SQL 매개 변수의 이름입니다.	예	해당 없음
sql-type	문자열입니다. SQL 매개 변수의 데이터 형식입니다.	아니요	해당 없음

응답 요소

참고 항목

각 자식 요소를 최대 한 번 지정할 수 있습니다. 나열된 순서대로 요소를 지정합니다.

이름	설명	필수
include-fragment	정책 정의에 정책 조각을 삽입합니다.	아니요
set-body	해결 프로그램의 응답에서 본문을 설정합니다.	아니요
publish-event	GraphQL API 스키마에 지정된 하나 이상의 구독에 이벤트를 게시합니다.	아니요

사용

• 정책 범위: GraphQL 해결 프로그램
• 게이트웨이: 클래식, v2

사용법 참고 사항

• 이 정책을 사용하여 해결 프로그램을 구성하고 관리하려면 GraphQL 해결 프로그램 구성을 참조하세요.
• 이 정책은 스키마의 일치하는 작업 형식에서 단일 필드를 확인할 때만 호출됩니다.

Azure SQL과의 관리 ID 통합 구성

사용자 이름과 암호를 사용하여 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
}

single-result T-SQL 요청을 사용하는 GraphQL 쿼리의 해결 프로그램

다음 예제는 백 엔드 Azure SQL 데이터베이스에 대한 single-result T-SQL 요청을 수행하여 GraphQL 쿼리를 해결합니다. 연결 문자열은 사용자 이름 및 암호와 함께 SQL 인증을 사용하며, 명명된 값을 사용하여 제공됩니다. 응답은 단일 행을 나타내는 단일 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 쿼리의 해결 프로그램

다음 예제는 T-SQL 쿼리를 사용하여 Azure SQL 데이터베이스에 대한 GraphQL 쿼리를 해결합니다. 데이터베이스에 대한 연결은 API Management 인스턴스의 시스템이 할당한 관리 ID를 사용합니다. Azure SQL 데이터베이스에 액세스하도록 ID를 구성해야 합니다.

쿼리 매개 변수는 context.GraphQL.Arguments 컨텍스트 변수를 사용하여 액세스됩니다. 다중 행 쿼리 응답은 liquid 템플릿으로 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 문을 사용하여 Azure SQL 데이터베이스 행을 삽입하는 GraphQL 변형을 해결합니다. 데이터베이스에 대한 연결은 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용 Microsoft Copilot을 사용하는 작성자 정책