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

Makale
04/04/2024

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.

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

<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

Veri Akışı Adı	Açıklama	Gerekli
connection-info	Cosmos DB veritabanında kapsayıcı bağlantısını belirtir.	Yes
sorgu isteği	Cosmos DB kapsayıcısına yönelik sorgu isteğinin ayarlarını belirtir.	, , `read-requestdelete-request`veya kaynaklarından `query-request`birini yapılandırma`write-request`
okuma isteği	Cosmos DB kapsayıcısına yönelik okuma isteğinin ayarlarını belirtir.	, , `read-requestdelete-request`veya kaynaklarından `query-request`birini yapılandırma`write-request`
delete-request	Cosmos DB kapsayıcısına yönelik silme isteğinin ayarlarını belirtir.	, , `read-requestdelete-request`veya kaynaklarından `query-request`birini yapılandırma`write-request`
yazma isteği	Cosmos DB kapsayıcısına yazma isteğinin ayarlarını belirtir.	, , `read-requestdelete-request`veya kaynaklarından `query-request`birini yapılandırma`write-request`
Yanıt	İsteğe bağlı olarak çözümleyicinin yanıtını yapılandırmak için alt ilkeleri belirtir. Belirtilmezse, yanıt Cosmos DB'den JSON olarak döndürülür.	Hayır

bağlantı bilgileri öğeleri

Veri Akışı Adı	Açıklama	Gerekli
connection-string	Cosmos DB hesabı için bağlantı dizesi belirtir. API Management yönetilen kimliği yapılandırıldıysa hesap anahtarını atla.	Yes
veritabanı adı	Dize. Cosmos DB veritabanının adı.	Yes
kapsayıcı-adı	Dize. Cosmos DB veritabanındaki kapsayıcının adı.	Yes

bağlantı dizesi öznitelikleri

Öznitelik	Açıklama	Zorunlu	Varsayılan
use-managed-identity	Boole. bağlantı dizesi bir hesap anahtarı yerine Cosmos DB hesabına bağlantı için API Management örneğinin sistem tarafından atanan yönetilen kimliğinin kullanılıp kullanılmayacağını belirtir. Kimliğin Cosmos DB kapsayıcısına erişecek şekilde yapılandırılması gerekir.	Hayır	`false`

query-request öznitelikleri

Öznitelik	Açıklama	Zorunlu	Varsayılan
enable-low-precision-order-by	Boole. Cosmos DB hizmetinde EnableLowPrecisionOrderBy sorgu isteği özelliğinin etkinleştirilip etkinleştirilmeymeyeceğini belirtir.	Hayır	YOK

sorgu isteği öğeleri

Veri Akışı Adı	Açıklama	Gerekli
sql-deyimi	Sorgu isteği için bir SQL deyimi.	Hayır
parametreler	Sorgu isteği için parametre alt öğelerindeki sorgu parametrelerinin listesi.	Hayır
partition-key	Sorguyu kapsayıcıdaki konuma yönlendirmek için cosmos DB bölüm anahtarı .	Hayır
Sayfalama	Sorgu sonuçlarını birden çok sayfaya bölme ayarlarını belirtir.	Hayır

parametre öznitelikleri

Öznitelik	Açıklama	Zorunlu	Varsayılan
Adı	Dize. @ gösterimindeki parametrenin adı.	Yes	Yok

sayfalama öğeleri

Veri Akışı Adı	Açıklama	Gerekli
max-item-count	Sorgu tarafından döndürülen en fazla öğe sayısını belirtir. Sorgu yürütme başına sonuç sayısına sınır getirmek istemiyorsanız -1 olarak ayarlayın.	Yes
continuation-token	Sonraki sonuç kümesini almak için sorguya eklenecek devamlılık belirtecini belirtir.	Yes

max-item-count özniteliği

Öznitelik	Açıklama	Zorunlu	Varsayılan
şablonu	için şablon oluşturma modunu ayarlamak için `max-item-count`kullanılır. Şu anda desteklenen tek değer: - `liquidmax-item-count`- sıvı şablonlama motorunu kullanacaktır.	Hayır	YOK

continuation-token özniteliği

Öznitelik	Açıklama	Zorunlu	Varsayılan
şablonu	Devamlılık belirteci için şablon oluşturma modunu ayarlamak için kullanılır. Şu anda desteklenen tek değer: - `liquid` - devamlılık belirteci sıvı şablonlama motorunu kullanacaktır.	Hayır	YOK

read-request öğeleri

Veri Akışı Adı	Açıklama	Gerekli
id	Kapsayıcıda okunacak öğenin tanımlayıcısı.	Yes
partition-key	Öğenin kapsayıcıdaki konumu için bölüm anahtarı. ile `id`belirtilirse, kapsayıcıdaki öğenin hızlı nokta okumasını (anahtar/değer araması) etkinleştirir.	Hayır

delete-request öznitelikleri

Öznitelik	Açıklama	Zorunlu	Varsayılan
tutarlılık düzeyi	Dize. Silme isteğinin Cosmos DB tutarlılık düzeyini ayarlar.	Hayır	YOK
ön tetikleyici	Dize. Cosmos DB kapsayıcınızda kayıtlı bir ön tetikleyici işlevinin tanımlayıcısı.	Hayır	YOK
tetikleyici sonrası	Dize. Cosmos DB kapsayıcınızda kayıtlı bir post-trigger işlevinin tanımlayıcısı.	Hayır	YOK

delete-request öğeleri

Veri Akışı Adı	Açıklama	Gerekli
id	Kapsayıcıda silinecek öğenin tanımlayıcısı.	Yes
partition-key	Öğenin kapsayıcıdaki konumu için bölüm anahtarı.	Hayır
Etag	Kapsayıcıdaki öğenin varlık etiketi, iyimser eşzamanlılık denetimi için kullanılır.	Hayır

write-request öznitelikleri

Öznitelik	Açıklama	Zorunlu	Varsayılan
Tür	Yazma isteğinin türü: `insert`, `replace`veya `upsert`.	Hayır	`upsert`
tutarlılık düzeyi	Dize. Yazma isteğinin Cosmos DB tutarlılık düzeyini ayarlar.	Hayır	YOK
indexing-yönergesi	Kapsayıcı öğelerinin nasıl dizinlenmesi gerektiğini belirleyen dizin oluşturma ilkesi .	Hayır	`default`
ön tetikleyici	Dize. Cosmos DB kapsayıcınızda kayıtlı bir ön tetikleyici işlevinin tanımlayıcısı.	Hayır	YOK
tetikleyici sonrası	Dize. Cosmos DB kapsayıcınızda kayıtlı bir post-trigger işlevinin tanımlayıcısı.	Hayır	YOK

yazma isteği öğeleri

Veri Akışı Adı	Açıklama	Gerekli
id	Kapsayıcıdaki öğenin tanımlayıcısı.	Evet olduğunda`type`.`replace`
Etag	Kapsayıcıdaki öğenin varlık etiketi, iyimser eşzamanlılık denetimi için kullanılır.	Hayır
set-body	Yazma isteğindeki gövdeyi ayarlar. Sağlanmadıysa, istek yükü bağımsız değişkenleri JSON biçiminde eşler.	Hayır

yanıt öğeleri

Veri Akışı Adı	Açıklama	Gerekli
set-body	Çözümleyicinin yanıtında gövdeyi ayarlar. Sağlanmazsa ve döndürülen JSON, GraphQL şemasında alan adları eşleşen alanlar içeriyorsa, alanlar otomatik olarak eşlenir.	Hayır
publish-event	GraphQL API şemasında belirtilen bir veya daha fazla aboneliğe bir olay yayımlar.	Hayır

partition-key öznitelikleri

Öznitelik	Açıklama	Zorunlu	Varsayılan
veri türü	Bölüm anahtarının veri türü: `string`, `number`, `bool`, `none`veya `null`.	Hayır	`string`
şablonu	Bölüm anahtarı için şablon oluşturma modunu ayarlamak için kullanılır. Şu anda desteklenen tek değer: - `liquid` - bölüm anahtarı sıvı şablonlama motorunu kullanacaktır	Hayır	YOK

etag özniteliği

Öznitelik	Açıklama	Zorunlu	Varsayılan
Tür	Dize. Aşağıdaki değerlerden biri: - `matchetag`- değer, öğenin sistem tarafından oluşturulan varlık etiketiyle eşleşmelidir - `no-matchetag`- değer öğenin sistem tarafından oluşturulan varlık etiketiyle eşleşecek şekilde gerekli değildir	Hayır	`match`
şablonu	Etag için şablon oluşturma modunu ayarlamak için kullanılır. Şu anda desteklenen tek değer: - `liquid` - etag sıvı şablonlama motorunu kullanacaktır	Hayır	YOK

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

GraphQL çözümleyicileri

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

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

İlke bildirimi

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

Kullanım notları

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

Önkoşullar

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

Örnekler

Cosmos DB sorgu isteği

Cosmos DB okuma isteği

Cosmos DB silme isteği

Cosmos DB yazma isteği

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

JSON nesnesini (JObject) ifadeden geçirme

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

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

İlgili ilkeler

İlgili içerik

Ek kaynaklar