Bagikan melalui


Sumber data Cosmos DB untuk resolver

BERLAKU UNTUK: Pengembang | Dasar | Dasar v2 | Standar | Standar v2 | Premi

Kebijakan cosmosdb-data-source resolver menyelesaikan data untuk jenis objek dan bidang dalam skema GraphQL dengan menggunakan sumber data Cosmos DB . Skema harus diimpor ke API Management sebagai API GraphQL.

Gunakan kebijakan untuk mengonfigurasi satu permintaan kueri, membaca permintaan, menghapus permintaan, atau menulis permintaan dan respons opsional dari sumber data Cosmos DB.

Catatan

Kebijakan ini dalam pratinjau. Saat ini, kebijakan tidak didukung di tingkat Konsumsi API Management.

Catatan

Tetapkan elemen kebijakan dan elemen turunan dalam urutan yang disediakan dalam pernyataan kebijakan. Pelajari lebih lanjut cara mengatur atau mengedit kebijakan API Management.

Pernyataan kebijakan

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

Elemen

Nama Deskripsi Wajib diisi
info koneksi Menentukan koneksi ke kontainer dalam database Cosmos DB. Ya
permintaan kueri Menentukan pengaturan untuk permintaan kueri ke kontainer Cosmos DB. Mengonfigurasi salah satu dari query-request, read-request, delete-request, atau write-request
baca-permintaan Menentukan pengaturan untuk permintaan baca ke kontainer Cosmos DB. Mengonfigurasi salah satu dari query-request, read-request, delete-request, atau write-request
delete-request Menentukan pengaturan untuk permintaan penghapusan ke kontainer Cosmos DB. Mengonfigurasi salah satu dari query-request, read-request, delete-request, atau write-request
write-request Menentukan pengaturan untuk permintaan tulis ke kontainer Cosmos DB. Mengonfigurasi salah satu dari query-request, read-request, delete-request, atau write-request
respons Secara opsional menentukan kebijakan turunan untuk mengonfigurasi respons penyelesai. Jika tidak ditentukan, respons dikembalikan dari Cosmos DB sebagai JSON. No

elemen info koneksi

Nama Deskripsi Wajib diisi
connection-string Menentukan string koneksi untuk akun Cosmos DB. Jika identitas terkelola API Management dikonfigurasi, hilangkan kunci akun. Ya
database-name String. Nama database Cosmos DB. Ya
container-name String. Nama kontainer dalam database Cosmos DB. Ya

atribut string koneksi

Atribut Deskripsi Wajib diisi Default
use-managed-identity Boolean. Menentukan apakah akan menggunakan identitas terkelola yang ditetapkan sistem instans API Management untuk koneksi ke akun Cosmos DB sebagai pengganti kunci akun di string koneksi. Identitas harus dikonfigurasi untuk mengakses kontainer Cosmos DB. No false

atribut permintaan kueri

Atribut Deskripsi Wajib diisi Default
enable-low-prescision-order-by Boolean. Menentukan apakah akan mengaktifkan properti permintaan kueri EnableLowPrecisionOrderBy di layanan Cosmos DB. No T/A

elemen permintaan kueri

Nama Deskripsi Wajib diisi
sql-statement Pernyataan SQL untuk permintaan kueri. No
parameter Daftar parameter kueri, dalam subelemen parameter , untuk permintaan kueri. No
partition-key Kunci partisi Cosmos DB untuk merutekan kueri ke lokasi dalam kontainer. No
penomoran Menentukan pengaturan untuk membagi hasil kueri menjadi beberapa halaman. No

atribut parameter

Atribut Deskripsi Wajib diisi Default
nama String. Nama parameter dalam notasi @. Ya T/A

elemen halaman

Nama Deskripsi Wajib diisi
max-item-count Menentukan jumlah maksimum item yang dikembalikan oleh kueri. Atur ke -1 jika Anda tidak ingin menempatkan batasan jumlah hasil per eksekusi kueri. Ya
token kelanjutan Menentukan token kelanjutan untuk dilampirkan ke kueri untuk mendapatkan kumpulan hasil berikutnya. Ya

atribut max-item-count

Atribut Deskripsi Wajib diisi Default
templat Digunakan untuk mengatur mode templat untuk max-item-count. Saat ini satu-satunya nilai yang didukung adalah:

- liquidmax-item-count- akan menggunakan mesin templat cair.
No T/A

atribut continuation-token

Atribut Deskripsi Wajib diisi Default
templat Digunakan untuk mengatur mode templat untuk token kelanjutan. Saat ini satu-satunya nilai yang didukung adalah:

- liquid - token kelanjutan akan menggunakan mesin templat cair.
No T/A

elemen baca-permintaan

Nama Deskripsi Wajib diisi
id Pengidentifikasi item yang akan dibaca dalam kontainer. Ya
partition-key Kunci partisi untuk lokasi item dalam kontainer. Jika ditentukan dengan id, memungkinkan pembacaan titik cepat (pencarian kunci/nilai) item dalam kontainer. No

atribut delete-request

Atribut Deskripsi Wajib diisi Default
tingkat konsistensi String. Mengatur tingkat konsistensi Cosmos DB dari permintaan penghapusan. No T/A
pra-pemicu String. Pengidentifikasi fungsi pra-pemicu yang terdaftar dalam kontainer Cosmos DB Anda. No T/A
pasca-pemicu String. Pengidentifikasi fungsi pasca-pemicu yang terdaftar dalam kontainer Cosmos DB Anda. No T/A

elemen delete-request

Nama Deskripsi Wajib diisi
id Pengidentifikasi item yang akan dihapus dalam kontainer. Ya
partition-key Kunci partisi untuk lokasi item dalam kontainer. No
etag Tag entitas untuk item dalam kontainer, digunakan untuk kontrol konkurensi optimis. No

atribut write-request

Atribut Deskripsi Wajib diisi Default
jenis Jenis permintaan tulis: insert, , replaceatau upsert. No upsert
tingkat konsistensi String. Mengatur tingkat konsistensi Cosmos DB dari permintaan tulis. No T/A
direktif pengindeksan Kebijakan pengindeksan yang menentukan bagaimana item kontainer harus diindeks. No default
pra-pemicu String. Pengidentifikasi fungsi pra-pemicu yang terdaftar dalam kontainer Cosmos DB Anda. No T/A
pasca-pemicu String. Pengidentifikasi fungsi pasca-pemicu yang terdaftar dalam kontainer Cosmos DB Anda. No T/A

elemen permintaan tulis

Nama Deskripsi Wajib diisi
id Pengidentifikasi item dalam kontainer. Ya kapan type adalah replace.
etag Tag entitas untuk item dalam kontainer, digunakan untuk kontrol konkurensi optimis. No
set-body Mengatur isi dalam permintaan tulis. Jika tidak disediakan, payload permintaan akan memetakan argumen ke dalam format JSON. No

elemen respons

Nama Deskripsi Wajib diisi
set-body Mengatur isi dalam respons resolver. Jika tidak disediakan dan JSON yang dikembalikan berisi bidang yang cocok dengan nama bidang dalam skema GraphQL, bidang akan dipetakan secara otomatis. No
publish-event Menerbitkan peristiwa ke satu atau beberapa langganan yang ditentukan dalam skema API GraphQL. No

atribut partition-key

Atribut Deskripsi Wajib diisi Default
jenis data Jenis data kunci partisi: string, , number, bool, noneatau null. No string
templat Digunakan untuk mengatur mode templat untuk kunci partisi. Saat ini satu-satunya nilai yang didukung adalah:

- liquid - kunci partisi akan menggunakan mesin templat cair
No T/A

atribut etag

Atribut Deskripsi Wajib diisi Default
jenis String. Salah satu dari nilai berikut:

- matchetag- nilai harus cocok dengan tag entitas yang dihasilkan sistem untuk item

- no-matchetag- nilai tidak diperlukan untuk mencocokkan tag entitas yang dihasilkan sistem untuk item
No match
templat Digunakan untuk mengatur mode templat untuk etag. Saat ini satu-satunya nilai yang didukung adalah:

- liquid - etag akan menggunakan mesin templat cair
No T/A

Penggunaan

Catatan penggunaan

  • Untuk mengonfigurasi dan mengelola resolver dengan kebijakan ini, lihat Mengonfigurasi pemecah masalah GraphQL.
  • Kebijakan ini hanya dipanggil saat menyelesaikan satu bidang dalam jenis operasi yang cocok dalam skema.

Mengonfigurasi integrasi identitas terkelola dengan Cosmos DB

Anda dapat mengonfigurasi identitas terkelola yang ditetapkan sistem API Management untuk mengakses akun Cosmos DB, alih-alih menyediakan kunci akun di string koneksi.

Ikuti langkah-langkah ini untuk menggunakan Azure CLI untuk mengonfigurasi identitas terkelola.

Prasyarat

Skrip Azure CLI untuk mengonfigurasi identitas terkelola

# 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    

Contoh

Permintaan kueri Cosmos DB

Contoh berikut menyelesaikan kueri GraphQL menggunakan kueri SQL ke kontainer Cosmos DB.

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

Permintaan baca Cosmos DB

Contoh berikut menyelesaikan kueri GraphQL menggunakan permintaan baca titik ke kontainer Cosmos DB. Koneksi ke akun Cosmos DB menggunakan identitas terkelola yang ditetapkan sistem instans API Management. Identitas harus dikonfigurasi untuk mengakses kontainer Cosmos DB.

id dan partition-key digunakan untuk permintaan baca diteruskan sebagai parameter kueri dan diakses menggunakan context.GraphQL.Arguments["id"] variabel konteks.

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

Permintaan penghapusan Cosmos DB

Contoh berikut menyelesaikan mutasi GraphQL dengan permintaan penghapusan ke kontainer Cosmos DB. id dan partition-key digunakan untuk permintaan penghapusan diteruskan sebagai parameter kueri dan diakses menggunakan context.GraphQL.Arguments["id"] variabel konteks.

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

Permintaan tulis Cosmos DB

Contoh berikut menyelesaikan mutasi GraphQL dengan permintaan upsert ke kontainer Cosmos DB. Koneksi ke akun Cosmos DB menggunakan identitas terkelola yang ditetapkan sistem instans API Management. Identitas harus dikonfigurasi untuk mengakses kontainer Cosmos DB.

Yang partition-key digunakan untuk permintaan tulis diteruskan sebagai parameter kueri dan diakses menggunakan context.GraphQL.Arguments["id"] variabel konteks. Permintaan upsert memiliki operasi pra-pemicu bernama "validateInput". Isi permintaan dipetakan menggunakan templat cair.

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

Membuat input parameter untuk kueri Cosmos DB

Contoh berikut menunjukkan cara untuk membuat kueri berparameter Cosmos DB menggunakan ekspresi kebijakan. Pilih metode berdasarkan bentuk input parameter Anda.

Contohnya didasarkan pada contoh skema GraphQL berikut, dan menghasilkan kueri parameter Cosmos DB yang sesuai.

Contoh skema GraphQL

input personInput {
  id: String!
  firstName: String
}

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

Contoh kueri Cosmos DB

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

Meneruskan objek JSON (JObject) dari ekspresi

Contoh kebijakan

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

Teruskan jenis input .NET (string, int, desimal, bool) dari ekspresi

Contoh kebijakan

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

Meneruskan nilai JSON (JValue) dari ekspresi

Contoh kebijakan

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

Untuk informasi selengkapnya tentang bekerja dengan kebijakan, lihat: