Çözümleyici için Azure SQL veri kaynağı

Makale
04/04/2024

Çözümleyici ilkesi, sql-data-source Bir Azure SQL veritabanına transact-SQL (T-SQL) isteği ve GraphQL şemasındaki bir nesne türü ve alanı için verileri çözümlemek için isteğe bağlı bir yanıt yapılandırıyor. Şema, GRAPHQL API'si olarak API Management'a aktarılmalıdır.

Not

Bu ilke önizleme aşamasındadır. İlke şu anda API Management'ın Tüketim katmanında desteklenmemektedir.

Not

İlkenin öğelerini ve alt öğelerini ilke bildiriminde sağlanan sırayla ayarlayın. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.

İlke bildirimi

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

Öğeler

Veri Akışı Adı	Açıklama	Gerekli
connection-info	Azure SQL veritabanı bağlantısını belirtir.	Yes
include-fragment	İlke tanımına bir ilke parçası ekler. Birden çok parça varsa, ek `include-fragment` öğeler ekleyin.	Hayır
Istek	Çözümleyicinin T-SQL isteğini ve isteğe bağlı parametrelerini belirtir.	Yes
Yanıt	İsteğe bağlı olarak, Azure SQL veritabanından yanıtı yapılandırmak için alt ilkeleri belirtir. Belirtilmezse, yanıt Azure SQL'den JSON olarak döndürülür.	Hayır

bağlantı bilgileri öğeleri

Not

Belirtilen durumlar dışında, her alt öğe en fazla bir kez belirtilebilir. Öğeleri listelenen sırada belirtin.

Öğe	Açıklama	Gerekli
connection-string	Azure SQL bağlantı dizesi belirtir. bağlantı dizesi, API Management yönetilen kimliği yapılandırılmışsa SQL kimlik doğrulaması (kullanıcı adı ve parola) veya Microsoft Entra kimlik doğrulaması kullanır.	Yes
include-fragment	İlke tanımına bir ilke parçası ekler. Birden çok parça varsa, ek `include-fragment` öğeler ekleyin.	Hayır
kimlik doğrulama sertifikası	Çözümleyicinin SQL isteğinde bir istemci sertifikası kullanarak kimlik doğrulaması yapar.	Hayır

bağlantı dizesi öznitelikleri

Öznitelik	Açıklama	Zorunlu	Varsayılan
use-managed-identity	Boole. bağlantı dizesi bir kullanıcı adı ve parola yerine Azure SQL veritabanına bağlantı için API Management örneğinin sistem tarafından atanan yönetilen kimliğinin kullanılıp kullanılmayacağını belirtir. İlke ifadelerine izin verilir. Kimlik, Azure SQL veritabanına erişecek şekilde yapılandırılmalıdır.	Hayır	`false`

request özniteliği

Öznitelik	Açıklama	Zorunlu	Varsayılan
tek sonuçlu	Boole. Sorgu yanıtının en fazla bir satır döndürmesinin beklenip beklenmeyeceğini belirtir. İlke ifadelerine izin verilir.	Hayır	`false`

istek öğeleri

Not

Her alt öğe en fazla bir kez belirtilebilir. Öğeleri listelenen sırada belirtin.

Öğe	Açıklama	Gerekli
include-fragment	İlke tanımına bir ilke parçası ekler.	Hayır
set-body	Çözümleyicinin SQL isteğindeki gövdeyi ayarlar.	Hayır
sql-deyimi	Azure SQL veritabanına yönelik istek için bir T-SQL deyimi. SQL deyimi, sırayla yürütülecek UPDATE, DELETE ve SELECT gibi birden çok bağımsız alt ifade içerebilir. Sonuçlar son alt ifadeden döndürülür.	Yes
parametreler	İstek için alt öğelerdeki `parameter` SQL parametrelerinin listesi.	Hayır

parametre öznitelikleri

Öznitelik	Açıklama	Zorunlu	Varsayılan
Adı	Dize. SQL parametresinin adı.	Yes	Yok
sql-type	Dize. SQL parametresinin veri türü.	Hayır	YOK

yanıt öğeleri

Not

Her alt öğe en fazla bir kez belirtilebilir. Öğeleri listelenen sırada belirtin.

Veri Akışı Adı	Açıklama	Gerekli
include-fragment	İlke tanımına bir ilke parçası ekler.	Hayır
set-body	Çözümleyicinin yanıtında gövdeyi ayarlar.	Hayır
publish-event	GraphQL API şemasında belirtilen bir veya daha fazla aboneliğe bir olay yayımlar.	Hayır

Kullanım

İlke kapsamları: GraphQL çözümleyicisi
Ağ geçitleri: klasik, v2

Kullanım notları

Bu ilkeyle bir çözümleyiciyi yapılandırmak ve yönetmek için bkz . GraphQL çözümleyicisini yapılandırma.
Bu ilke yalnızca şemadaki eşleşen işlem türündeki tek bir alan çözümlendiğinde çağrılır.

Azure SQL ile yönetilen kimlik tümleştirmeyi yapılandırma

KULLANıCı adı ve parolayla SQL kimlik doğrulamasını yapılandırmak yerine Azure SQL'e erişim için API Management sistem tarafından atanan yönetilen kimliği yapılandırabilirsiniz. Arka plan için bkz . Azure SQL ile Microsoft Entra kimlik doğrulamasını yapılandırma ve yönetme.

Önkoşullar

API Management örneğinizde sistem tarafından atanan yönetilen kimliği etkinleştirin.

Microsoft Entra Id erişimini etkinleştirme

Microsoft Entra kullanıcısını sunucunun yöneticisi olarak atayarak SQL Veritabanı için Microsoft Entra kimlik doğrulamasını etkinleştirin.

Portalda Azure SQL sunucunuza gidin.
Microsoft Entra Kimlik'i seçin.
Yöneticiyi ayarla'yı seçin ve kendinizi veya ait olduğunuz grubu seçin.
Kaydet'i seçin.

Rol atama

Portalda Azure SQL veritabanı kaynağınıza gidin.
Sorgu düzenleyicisi (önizleme) seçeneğini belirleyin.
Active Directory kimlik doğrulaması kullanarak oturum açın.

Aşağıdaki SQL betiğini yürütür. değerini API Management örneğinizin adıyla değiştirin <identity-name> .

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

Örnekler

Örnek şema

Bu bölümdeki örnekler aşağıdaki GraphQL şeması için çözümleyicilerdir:

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
}

Tek sonuçlu T-SQL isteği kullanan GraphQL sorgusu için çözümleyici

Aşağıdaki örnek, arka uç Azure SQL veritabanına tek sonuçlu bir T-SQL isteği oluşturarak GraphQL sorgusunu çözümler. bağlantı dizesi kullanıcı adı ve parola ile SQL kimlik doğrulaması kullanır ve adlandırılmış bir değer kullanılarak sağlanır. Yanıt, tek bir satırı temsil eden tek bir JSON nesnesi olarak döndürülür.

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

Dönüştürülmüş çok satırlı sorgu yanıtıyla GraphQL sorgusu çözümleyicisi

Aşağıdaki örnek, Azure SQL veritabanına yönelik T-SQL sorgusu kullanarak GraphQL sorgusunu çözümler. Veritabanı bağlantısı API Management örneğinin sistem tarafından atanan yönetilen kimliğini kullanır. Kimlik, Azure SQL veritabanına erişecek şekilde yapılandırılmalıdır.

Sorgu parametresine context.GraphQL.Arguments bağlam değişkeni kullanılarak erişilir. Çok satırlı sorgu yanıtı, ilke kullanılarak bir sıvı şablonuyla dönüştürülür 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 mutasyonu için çözümleyici

Aşağıdaki örnek, Azure SQL veritabanı satırı eklemek için T-SQL INSERT deyimini kullanarak GraphQL mutasyonunu çözer. Veritabanı bağlantısı API Management örneğinin sistem tarafından atanan yönetilen kimliğini kullanır. Kimlik, Azure SQL veritabanına erişecek şekilde yapılandırılmalıdır.

<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 çözümleyicileri

İlkelerle çalışma hakkında daha fazla bilgi için bkz: