Sumber data Cosmos DB untuk resolver

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

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

• Cakupan kebijakan: Pemecah masalah GraphQL
• Gateway: klasik, v2

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

• Aktifkan identitas terkelola yang ditetapkan sistem di instans API Management Anda. Di portal, perhatikan ID objek (utama) identitas terkelola.

• • Gunakan lingkungan Bash di Azure Cloud Shell. Untuk informasi selengkapnya, lihat Mulai Cepat untuk Bash di Azure Cloud Shell.

    

  • Jika Anda lebih suka menjalankan perintah referensi CLI secara lokal, instal Azure CLI. Jika Anda menjalankan Windows atau macOS, pertimbangkan untuk menjalankan Azure CLI dalam kontainer Docker. Untuk informasi lebih lanjut, lihat Cara menjalankan Azure CLI di kontainer Docker.

    • Jika Anda menggunakan instalasi lokal, masuk ke Azure CLI dengan menggunakan perintah login az. Untuk menyelesaikan proses autentikasi, ikuti langkah-langkah yang ditampilkan di terminal Anda. Untuk opsi masuk lainnya, lihat Masuk dengan Azure CLI.

    • Saat Anda diminta, instal ekstensi Azure CLI pada penggunaan pertama. Untuk informasi selengkapnya tentang ekstensi, lihat Menggunakan ekstensi dengan Azure CLI.

    • Jalankan versi az untuk menemukan versi dan pustaka dependen yang diinstal. Untuk meningkatkan ke versi terbaru, jalankan peningkatan az.

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

Kebijakan terkait

• Pemecah masalah GraphQL

Konten terkait

Untuk informasi selengkapnya tentang bekerja dengan kebijakan, lihat:

• Tutorial: Mengubah dan melindungi API Anda
• Referensi Kebijakan untuk daftar lengkap pernyataan kebijakan dan pengaturannya
• Ekspresi kebijakan
• Mengatur atau mengedit kebijakan
• Menggunakan kembali konfigurasi kebijakan
• Repositori cuplikan kebijakan
• Kebijakan penulis menggunakan Microsoft Copilot untuk Azure