Çözümleyici için Cosmos DB veri kaynağı

ŞUNLAR IÇIN GEÇERLIDIR: Geliştirici | Temel | Temel v2 | Standart | Standart v2 | Premium | Premium v2

cosmosdb-data-source Çözümleyici ilkesi, Cosmos DB veri kaynağı kullanarak GraphQL şemasındaki bir nesne türü ve alanı için verileri çözümler. Şema, GRAPHQL API'si olarak API Management'a aktarılmalıdır.

Cosmos DB veri kaynağından tek bir sorgu isteği, okuma isteği, silme isteği veya yazma isteği ve isteğe bağlı bir yanıt yapılandırmak için ilkeyi kullanın.

İlke bildirimi

<cosmosdb-data-source> 
    <!-- Required information that specifies connection to Cosmos DB -->
    <connection-info> 
        <connection-string use-managed-identity="true | false"> 
            AccountEndpoint=...;[AccountKey=...;]
        </connection-string> 
        <database-name>Cosmos DB database name</database-name> 
        <container-name>Name of container in Cosmos DB database</container-name>     
    </connection-info>

    <!-- Settings to query using a SQL statement and optional query parameters -->
    <query-request enable-low-precision-order-by="true | false"> 
        <sql-statement> 
            SQL statement 
        </sql-statement> 
        <parameters> 
            <parameter name="Query parameter name in @ notation"> 
                "Query parameter value or expression"
            </parameter>
            <!-- if there are multiple parameters, then add additional parameter elements --> 
        </parameters> 
        <partition-key data-type="string | number | bool | none | null" template="liquid" > 
            "Container partition key" 
        </partition-key> 
        <paging> 
            <max-item-count template="liquid" > 
                Maximum number of items returned by query
            </max-item-count> 
            <continuation-token template="liquid"> 
                Continuation token for paging 
            </continuation-token> 
        </paging>
    </query-request>
    
    <!-- Settings to read item by item ID and optional partition key --> 
    <read-request> 
        <id template="liquid" >
            "Item ID in container"
        </id> 
        <partition-key data-type="string | number | bool | none | null" template="liquid" > 
            "Container partition key" 
        </partition-key>  
    </read-request> 
    
    <!-- Settings to delete item by ID and optional partition key --> 
    <delete-request consistency-level="bounded-staleness | consistent-prefix | eventual | session | strong" pre-trigger="myPreTrigger" post-trigger="myPostTrigger">
        <etag type="entity tag type" template="liquid" > 
            "System-generated entity tag" 
        </etag> 
        <id template="liquid">
            "Item ID in container"
        </id> 
        <partition-key data-type="string | number | bool | none | null" template="liquid"> 
            "Container partition key" 
        </partition-key> 
    </delete-request> 
    
    <!-- Settings to write item -->
    <write-request type="insert | replace | upsert" consistency-level="bounded-staleness | consistent-prefix | eventual | session | strong" pre-trigger="myPreTrigger" post-trigger="myPostTrigger">
        <id template="liquid">
            "Item ID in container"
        </id>
         <partition-key data-type="string | number | bool | none | null" template="liquid"> 
            "Container partition key"
        </partition-key>      
        <etag type="match | no-match" template="liquid" > 
            "System-generated entity tag" 
        </etag>
        <set-body template="liquid" >...set-body policy configuration...</set-body> 
    </write-request>
    
    <response> 
        <set-body>...set-body policy configuration...</set-body> 
        <publish-event>...publish-event policy configuration...</publish-event>
    </response>
    
</cosmosdb-data-source> 

Öğeler

bağlantı bilgileri öğeleri

bağlantı dizesi öznitelikleri

query-request öznitelikleri

sorgu isteği öğeleri

parametre öznitelikleri

sayfalama öğeleri

max-item-count özniteliği

continuation-token özniteliği

read-request öğeleri

delete-request öznitelikleri

delete-request öğeleri

write-request öznitelikleri

yazma isteği öğeleri

yanıt öğeleri

partition-key öznitelikleri

etag özniteliği

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.

Cosmos DB ile yönetilen kimlik tümleştirmeyi yapılandırma

bağlantı dizesi bir hesap anahtarı sağlamak yerine Cosmos DB hesabına erişmek için API Management sistem tarafından atanan yönetilen kimliği yapılandırabilirsiniz.

Yönetilen kimliği yapılandırmak için Azure CLI'yı kullanmak için bu adımları izleyin.

Önkoşullar

• API Management örneğinizde sistem tarafından atanan yönetilen kimliği etkinleştirin. Portalda, yönetilen kimliğin nesne (sorumlu) kimliğini not edin.

• • Azure Cloud Shell'de Bash ortamını kullanın. Daha fazla bilgi için bkz . Azure Cloud Shell'de Bash için hızlı başlangıç.

    

  • CLI başvuru komutlarını yerel olarak çalıştırmayı tercih ediyorsanız Azure CLI'yı yükleyin . Windows veya macOS üzerinde çalışıyorsanız Azure CLI’yi bir Docker kapsayıcısında çalıştırmayı değerlendirin. Daha fazla bilgi için bkz . Docker kapsayıcısında Azure CLI'yi çalıştırma.

    • Yerel yükleme kullanıyorsanız az login komutunu kullanarak Azure CLI ile oturum açın. Kimlik doğrulama işlemini tamamlamak için terminalinizde görüntülenen adımları izleyin. Diğer oturum açma seçenekleri için bkz . Azure CLI ile oturum açma.

    • İstendiğinde, ilk kullanımda Azure CLI uzantısını yükleyin. Uzantılar hakkında daha fazla bilgi için bkz. Azure CLI ile uzantıları kullanma.

    • Yüklü sürümü ve bağımlı kitaplıkları bulmak için az version komutunu çalıştırın. En son sürüme yükseltmek için az upgrade komutunu çalıştırın.

Yönetilen kimliği yapılandırmak için Azure CLI betiği

# Set variables

# Variable for Azure Cosmos DB account name
cosmosName="<MY-COSMOS-DB-ACCOUNT>"

# Variable for resource group name
resourceGroupName="<MY-RESOURCE-GROUP>"

# Variable for subscription
resourceGroupName="<MY-SUBSCRIPTION-NAME>"

# Set principal variable to the value from Managed identities page of API Management instance in Azure portal
principal="<MY-APIM-MANAGED-ID-PRINCIPAL-ID>"

# Get the scope value of Cosmos DB account
 
scope=$(
    az cosmosdb show \
        --resource-group $resourceGroupName \
        --name $cosmosName \
        --subscription $subscriptionName \
        --query id \
        --output tsv
)

# List the built-in Cosmos DB roles
# Currently, the roles aren't visible in the portal

az cosmosdb sql role definition list \
    --resource-group $resourceGroupName \
    --account-name $cosmosName \
    --subscription $subscriptionName \

# Take note of the role you want to assign, such as "Cosmos DB Built-in Data Contributor" in this example

# Assign desired Cosmos DB role to managed identity

az cosmosdb sql role assignment create \
    --resource-group $resourceGroupName \
    --account-name $cosmosName \
    --subscription $subscriptionName \
    --role-definition-name "Cosmos DB Built-in Data Contributor" \
    --principal-id $principal \
    --scope $scope    

Örnekler

Cosmos DB sorgu isteği

Aşağıdaki örnek, Cosmos DB kapsayıcısına sql sorgusu kullanarak GraphQL sorgusunu çözümler.

<cosmosdb-data-source>
    <connection-info>
        <connection-string>
            AccountEndpoint=https://contoso-cosmosdb.
documents.azure.com:443/;AccountKey=CONTOSOKEY;
        </connection-string>
        <database-name>myDatabase</database-name>
        <container-name>myContainer</container-name>
    </connection-info>
    <query-request>
        <sql-statement>SELECT * FROM c </sql-statement>
    </query-request>
</cosmosdb-data-source>

Cosmos DB okuma isteği

Aşağıdaki örnek, Cosmos DB kapsayıcısına yönelik bir nokta okuma isteği kullanarak GraphQL sorgusunu çözümler. Cosmos DB hesabıyla bağlantı, API Management örneğinin sistem tarafından atanan yönetilen kimliğini kullanır. Kimliğin Cosmos DB kapsayıcısına erişecek şekilde yapılandırılması gerekir.

id okuma isteği için kullanılan ve partition-key sorgu parametresi olarak geçirilir ve bağlam değişkeni kullanılarak context.GraphQL.Arguments["id"] erişilir.

<cosmosdb-data-source>
    <connection-info>
        <connection-string use-managed-identity="true">
            AccountEndpoint=https://contoso-cosmosdb.
documents.azure.com:443/;
        </connection-string>
        <database-name>myDatabase</database-name>
        <container-name>myContainer</container-name>
    </connection-info>
    <read-request>
        <id>
            @(context.GraphQL.Arguments["id"].ToString())
        </id>
        <partition-key>
            @(context.GraphQL.Arguments["id"].ToString())
    <read-request>
</cosmosdb-data-source>

Cosmos DB silme isteği

Aşağıdaki örnek, Cosmos DB kapsayıcısına yönelik silme isteğiyle GraphQL mutasyonunu çözer. id silme isteği için kullanılan ve partition-key sorgu parametresi olarak geçirilir ve bağlam değişkeni kullanılarak context.GraphQL.Arguments["id"] erişilir.

<cosmosdb-data-source>
    <connection-info>
        <connection-string>
            AccountEndpoint=https://contoso-cosmosdb.
documents.azure.com:443/;AccountKey=CONTOSOKEY;
        </connection-string>
        <database-name>myDatabase</database-name>
        <container-name>myContainer</container-name>
    </connection-info>
    <delete-request>
        <id>
            @(context.GraphQL.Arguments["id"].ToString())
        </id>
        <partition-key>
            @(context.GraphQL.Arguments["id"].ToString())
        </partition-key>
    </delete-request>
</cosmosdb-data-source>

Cosmos DB yazma isteği

Aşağıdaki örnek, Cosmos DB kapsayıcısına yönelik bir upsert isteğiyle GraphQL mutasyonunu çözer. Cosmos DB hesabıyla bağlantı, API Management örneğinin sistem tarafından atanan yönetilen kimliğini kullanır. Kimliğin Cosmos DB kapsayıcısına erişecek şekilde yapılandırılması gerekir.

partition-key Yazma isteği için kullanılan sorgu parametresi olarak geçirilir ve bağlam değişkeni kullanılarak context.GraphQL.Arguments["id"] erişilir. upsert isteğinde "validateInput" adlı bir ön tetikleyici işlemi vardır. İstek gövdesi bir sıvı şablonu kullanılarak eşlenir.

<cosmosdb-data-source>
    <connection-info>
        <connection-string use-managed-identity="true">
            AccountEndpoint=https://contoso-cosmosdb.
documents.azure.com:443/;
        </connection-string>
        <database-name>myDatabase</database-name>
        <container-name>myContainer</container-name>
    </connection-info>
    <write-request type="upsert" pre-trigger="validateInput">
        <partition-key>
            @(context.GraphQL.Arguments["id"].ToString())
        </partition-key>
        <set-body template="liquid">
            {"id" : "{{body.arguments.id}}" ,
            "firstName" : "{{body.arguments.firstName}}",
            "intField" : {{body.arguments.intField}} ,
            "floatField" : {{body.arguments.floatField}} ,
            "boolField" : {{body.arguments.boolField}}}
        </set-body>
    </write-request>
</cosmosdb-data-source>

Cosmos DB sorgusu için parametre girişi oluşturma

Aşağıdaki örneklerde, ilke ifadelerini kullanarak Cosmos DB parametreli sorguları oluşturmanın yolları gösterilmektedir. Parametre girişinizin biçimine göre bir yöntem seçin.

Örnekler aşağıdaki örnek GraphQL şemasını temel alır ve ilgili Cosmos DB parametreli sorgusunu oluşturur.

Örnek GraphQL şeması

input personInput {
  id: String!
  firstName: String
}

type Query {
  personsStringParam(stringInput: String): personsConnection
  personsPersonParam(input: personInput): personsConnection
}

Örnek Cosmos DB sorgusu

{
    "query": "query { 
        personsPersonParam(input: { id: \"3\" } { 
        items { id firstName lastName } 
        } 
    }"
}    

JSON nesnesini (JObject) ifadeden geçirme

Örnek ilke

[...]
<query-request>
    <sql-statement>SELECT * FROM c where c.familyId =@param.id</sql-statement>
    <parameters>
        <parameter name="@param">@(context.GraphQL.Arguments["input"])</parameter>
    </parameters>
    </query-request>
[...]

İfadeden .NET giriş türünü (dize, int, ondalık, bool) geçirme

Örnek ilke

[...]
<query-request>
    <sql-statement>SELECT * FROM c where c.familyId =@param</sql-statement>
    <parameters>
        <parameter name="@param">@($"start.{context.GraphQL.Arguments["stringInput"]}")</parameter>
    </parameters>
</query-request>
[...]

İfadeden JSON değeri (JValue) geçirme

Örnek ilke

[...]
<query-request>
    <sql-statement>SELECT * FROM c where c.familyId =@param</sql-statement>
    <parameters>
        <parameter name="@param">@(context.GraphQL.Arguments["stringInput"])</parameter>
    </parameters>
</query-request>
[...]

İlgili ilkeler

• GraphQL çözümleyicileri

İlgili içerik

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

• Öğretici: API'nizi dönüştürme ve koruma
• İlke deyimlerinin ve ayarlarının tam listesi için ilke başvurusu
• İlke ifadeleri
• İlkeleri ayarlama veya düzenleme
• İlke yapılandırmalarını yeniden kullanma
• İlke kod parçacıkları deposu
• Azure API Management ilke araç seti
• Azure'da Microsoft Copilot kullanarak ilke yazma