Cosmos DB-adatforrás egy feloldóhoz

A cosmosdb-data-source feloldó házirend egy GraphQL-séma objektumtípusának és mezőjének adatait egy Cosmos DB-adatforrás használatával oldja fel. A sémát GraphQL API-ként kell importálni az API Managementbe.

A házirend használatával egyetlen lekérdezési kérést, olvasási kérést, törlési vagy írási kérést és a Cosmos DB-adatforrás opcionális válaszát konfigurálhatja.

Feljegyzés

Ez a szabályzat előzetes verzióban érhető el. A szabályzat jelenleg nem támogatott az API Management használati szintjén.

Feljegyzés

Állítsa be a szabályzat elemeit és gyermekelemeit a szabályzatutasításban megadott sorrendben. További információ az API Management-szabályzatok beállításáról és szerkesztéséről.

Szabályzatutasítás

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

Elemek

Név	Leírás	Kötelező
kapcsolati adatok	A Cosmos DB-adatbázisban lévő tárolóhoz való kapcsolatot adja meg.	Igen
lekérdezés-kérés	Megadja a Cosmos DB-tárolónak küldött lekérdezéskérés beállításait.	Konfigurálja az egyik `query-request`, `read-request`, `delete-request`vagy `write-request`
olvasási kérés	Megadja a Cosmos DB-tárolónak küldött olvasási kérés beállításait.	Konfigurálja az egyik `query-request`, `read-request`, `delete-request`vagy `write-request`
delete-request	Megadja a Cosmos DB-tároló törlési kérésének beállításait.	Konfigurálja az egyik `query-request`, `read-request`, `delete-request`vagy `write-request`
írási kérés	Megadja a Cosmos DB-tárolóba irányuló írási kérés beállításait.	Konfigurálja az egyik `query-request`, `read-request`, `delete-request`vagy `write-request`
válasz	Opcionálisan gyermekszabályzatokat ad meg a feloldó válaszának konfigurálásához. Ha nincs megadva, a cosmos DB JSON-ként adja vissza a választ.	Nem

kapcsolat-információs elemek

Név	Leírás	Kötelező
kapcsolati karakterlánc	A Cosmos DB-fiók kapcsolati sztring adja meg. Ha egy API Management által felügyelt identitás van konfigurálva, hagyja ki a fiókkulcsot.	Igen
adatbázis neve	Húr. A Cosmos DB-adatbázis neve.	Igen
tároló neve	Húr. Tároló neve a Cosmos DB-adatbázisban.	Igen

kapcsolati sztring attribútumai

Attribútum	Leírás	Kötelező	Alapértelmezett
use-managed-identity	Logikai. Megadja, hogy az API Management-példány rendszer által hozzárendelt felügyelt identitását használja-e a Cosmos DB-fiókhoz való csatlakozáshoz a kapcsolati sztring egy fiókkulcsa helyett. Az identitást úgy kell konfigurálni , hogy hozzáférjen a Cosmos DB-tárolóhoz.	Nem	`false`

query-request attribútumok

Attribútum	Leírás	Kötelező	Alapértelmezett
enable-low-precision-order-by	Logikai. Megadja, hogy engedélyezi-e az EnableLowPrecisionOrderBy lekérdezéskérési tulajdonságot a Cosmos DB szolgáltatásban.	Nem	N.A.

lekérdezés-kérelem elemei

Név	Leírás	Kötelező
sql-utasítás	A lekérdezési kérelem SQL-utasítása.	Nem
paraméterek	A lekérdezési kérelem lekérdezési paramétereinek listája paraméter-alelemekben.	Nem
partíciókulcs	Egy Cosmos DB partíciókulcs , ahová a lekérdezést a tárolóban lévő helyre irányíthatja.	Nem
lapozás	Megadja a lekérdezési eredmények több lapra való felosztásának beállításait.	Nem

paraméterattribútumok

Attribútum	Leírás	Kötelező	Alapértelmezett
név	Húr. A paraméter neve a @ jelölésben.	Igen	N.A.

lapozási elemek

Név	Leírás	Kötelező
max-item-count	A lekérdezés által visszaadott elemek maximális számát adja meg. Állítsa -1 értékre, ha nem szeretné korlátozni a lekérdezés-végrehajtásonkénti eredmények számát.	Igen
folytatási jogkivonat	Megadja a lekérdezéshez csatolandó folytatási jogkivonatot a következő eredménykészlet lekéréséhez.	Igen

max-item-count attribútum

Attribútum	Leírás	Kötelező	Alapértelmezett
sablon	A templating mód beállítására szolgál a `max-item-count`. Jelenleg az egyetlen támogatott érték: - `liquid` - a `max-item-count` folyadék templatáló motort használja.	Nem	N.A.

folytatási jogkivonat attribútum

Attribútum	Leírás	Kötelező	Alapértelmezett
sablon	A folytatási jogkivonat templating módjának beállítására szolgál. Jelenleg az egyetlen támogatott érték: - `liquid` - a folytatási jogkivonat a folyékony templatáló motort használja.	Nem	N.A.

olvasási-kérési elemek

Név	Leírás	Kötelező
azonosító	A tárolóban beolvasandó elem azonosítója.	Igen
partíciókulcs	Az elem tárolóban való helyének partíciókulcsa. Ha meg van `id`adva, lehetővé teszi a tárolóban lévő elem gyors pontolvasását (kulcs/érték keresését).	Nem

delete-request attribútumok

Attribútum	Leírás	Kötelező	Alapértelmezett
konzisztenciaszint	Húr. A törlési kérelem Cosmos DB-konzisztenciaszintjének beállítása.	Nem	N.A.
elő-trigger	Húr. A Cosmos DB-tárolóban regisztrált eseményindító előtti függvény azonosítója.	Nem	N.A.
eseményindító utáni	Húr. A Cosmos DB-tárolóban regisztrált eseményindító utáni függvény azonosítója.	Nem	N.A.

delete-request elements

Név	Leírás	Kötelező
azonosító	A tárolóban törölni kívánt elem azonosítója.	Igen
partíciókulcs	Az elem tárolóban való helyének partíciókulcsa.	Nem
etag	A tárolóban lévő elem entitáscímkéje, amelyet az optimista egyidejűség-vezérléshez használnak.	Nem

write-request attribútumok

Attribútum	Leírás	Kötelező	Alapértelmezett
típus	Az írási kérelem típusa: `insert`, `replace`vagy `upsert`.	Nem	`upsert`
konzisztenciaszint	Húr. Az írási kérelem Cosmos DB-konzisztenciaszintjének beállítása.	Nem	N.A.
indexelési irányelv	Az indexelési szabályzat , amely meghatározza a tároló elemeinek indexelését.	Nem	`default`
elő-trigger	Húr. A Cosmos DB-tárolóban regisztrált eseményindító előtti függvény azonosítója.	Nem	N.A.
eseményindító utáni	Húr. A Cosmos DB-tárolóban regisztrált eseményindító utáni függvény azonosítója.	Nem	N.A.

írási-kérési elemek

Név	Leírás	Kötelező
azonosító	A tárolóban lévő elem azonosítója.	Igen, amikor `type` van `replace`.
etag	A tárolóban lévő elem entitáscímkéje, amelyet az optimista egyidejűség-vezérléshez használnak.	Nem
set-body	Beállítja a törzset az írási kérelemben. Ha nincs megadva, a kérelem hasznos adatai JSON formátumban leképezik az argumentumokat.	Nem

válaszelemek

Név	Leírás	Kötelező
set-body	Beállítja a törzset a feloldó válaszában. Ha nincs megadva, és a visszaadott JSON a GraphQL-séma mezőinek megfelelő mezőket tartalmaz, a rendszer automatikusan leképezi a mezőket.	Nem
közzétételi esemény	Esemény közzététele a GraphQL API-sémában megadott egy vagy több előfizetésben.	Nem

partíciókulcs-attribútumok

Attribútum	Leírás	Kötelező	Alapértelmezett
adattípus	A partíciókulcs adattípusa: `string`, `number`, `bool`, `none`vagy `null`.	Nem	`string`
sablon	A partíciókulcs templating módjának beállítására szolgál. Jelenleg az egyetlen támogatott érték: - `liquid` - a partíciókulcs a folyékony templatáló motort használja	Nem	N.A.

etag attribútum

Attribútum	Leírás	Kötelező	Alapértelmezett
típus	Húr. Az alábbi értékek egyike: - `match` - az `etag` értéknek meg kell egyeznie az elem rendszer által létrehozott entitáscímkéjének - `no-match` - az `etag` érték nem szükséges az elem rendszer által létrehozott entitáscímkéjének megfelelő értékhez	Nem	`match`
sablon	Az etag templating módjának beállítására szolgál. Jelenleg az egyetlen támogatott érték: - `liquid` - az etag a folyadék templatáló motort használja	Nem	N.A.

Használat

Szabályzat hatókörei: GraphQL-feloldó
Átjárók: klasszikus, v2

Használati megjegyzések

A feloldó ezzel a szabályzattal történő konfigurálásához és kezeléséhez lásd : GraphQL-feloldó konfigurálása.
Ez a szabályzat csak akkor lesz meghívva, ha a séma egy egyező művelettípusában lévő egyetlen mezőt old fel.

Felügyelt identitásintegráció konfigurálása a Cosmos DB-vel

Az API Management rendszer által hozzárendelt felügyelt identitását úgy konfigurálhatja, hogy hozzáférjen egy Cosmos DB-fiókhoz, ahelyett, hogy egy fiókkulcsot ad meg a kapcsolati sztring.

A felügyelt identitás konfigurálásához kövesse az alábbi lépéseket az Azure CLI használatával.

Előfeltételek

Engedélyezze a rendszer által hozzárendelt felügyelt identitást az API Management-példányban. A portálon jegyezze fel a felügyelt identitás objektum-(egyszerű) azonosítóját.
- Használja a Bash-környezetet az Azure Cloud Shellben. További információ: Az Azure Cloud Shell használatának első lépései.
- Ha inkább helyi cli-referenciaparancsokat szeretne futtatni, telepítse az Azure CLI-t. Ha Windows vagy macOS rendszert használ, fontolja meg az Azure CLI Docker-tárolóban való futtatását. További információ: Az Azure CLI futtatása Docker-tárolóban.
  - Ha helyi telepítést használ, jelentkezzen be az Azure CLI-be az az login parancs futtatásával. A hitelesítési folyamat befejezéséhez kövesse a terminálon megjelenő lépéseket. További bejelentkezési lehetőségekért lásd: Hitelesítés az Azure-ba az Azure CLI használatával.
  - Amikor a rendszer kéri, először telepítse az Azure CLI-bővítményt. További információ a bővítményekről: Bővítmények használata és kezelése az Azure CLI-vel.
  - Futtassa az az version parancsot a telepített verzió és a függő kódtárak megkereséséhez. A legújabb verzióra az az upgrade paranccsal frissíthet.

Azure CLI-szkript a felügyelt identitás konfigurálásához

# 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

Példák

Cosmos DB-lekérdezési kérelem

Az alábbi példa egy GraphQL-lekérdezést old fel SQL-lekérdezéssel egy Cosmos DB-tárolóra.

<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 olvasási kérése

Az alábbi példa egy Cosmos DB-tároló pontolvasási kérésével old fel egy GraphQL-lekérdezést. A Cosmos DB-fiókhoz való kapcsolat az API Management-példány rendszer által hozzárendelt felügyelt identitását használja. Az identitást úgy kell konfigurálni , hogy hozzáférjen a Cosmos DB-tárolóhoz.

id Az partition-key olvasási kérést lekérdezési paraméterekként továbbítja a rendszer, és a context.GraphQL.Arguments["id"] környezeti változó használatával éri el.

<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 törlési kérése

Az alábbi példa egy Cosmos DB-tároló törlési kérésével old fel egy GraphQL-mutációt. A id törlési kéréshez használt és partition-key a rendszer lekérdezési paraméterekként adja át, és a context.GraphQL.Arguments["id"] környezeti változóval érhető el.

<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 írási kérése

Az alábbi példa egy Cosmos DB-tárolóra irányuló upsert kéréssel oldja fel a GraphQL-mutációt. A Cosmos DB-fiókhoz való kapcsolat az API Management-példány rendszer által hozzárendelt felügyelt identitását használja. Az identitást úgy kell konfigurálni , hogy hozzáférjen a Cosmos DB-tárolóhoz.

Az partition-key írási kérelemhez használt paramétert a rendszer lekérdezési paraméterként adja át, és a context.GraphQL.Arguments["id"] környezeti változó használatával éri el. Az upsert-kérelem egy "validateInput" nevű trigger előtti művelettel rendelkezik. A kérelem törzse folyékony sablonnal van leképezve.

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

Paraméterbemenet létrehozása Cosmos DB-lekérdezéshez

Az alábbi példák azt mutatják be, hogyan hozhat létre Cosmos DB paraméteres lekérdezéseket szabályzatkifejezések használatával. Válasszon egy metódust a paraméterbemenet formája alapján.

A példák a következő Minta GraphQL-sémán alapulnak, és létrehoznak egy cosmos DB paraméteres lekérdezést.

Példa GraphQL-sémára

input personInput {
  id: String!
  firstName: String
}

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

Példa Cosmos DB-lekérdezésre

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

JSON-objektum (JObject) átadása kifejezésből

Példaházirend

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

.NET bemeneti típus (sztring, int, decimális, bool) átadása kifejezésből

Példaházirend

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

JSON-érték (JValue) átadása kifejezésből

Példaházirend

[...]
<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-feloldók

A szabályzatok használatával kapcsolatos további információkért lásd:

Oktatóanyag: AZ API átalakítása és védelme
Szabályzathivatkozás a szabályzatutasságok és azok beállításainak teljes listájához
Házirend-kifejezések
Házirendek beállítása vagy szerkesztése
Szabályzatkonfigurációk újrafelhasználása
Szabályzatrészletek adattára
Házirend-játszótér adattára
Azure API Management policy toolkit
A Copilot segítségével szabályzatokat hozhat létre, magyarázhat el és háríthat el hibákat.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2024-07-04

Megosztás a következőn keresztül:

Cosmos DB-adatforrás egy feloldóhoz

Szabályzatutasítás

Elemek

kapcsolat-információs elemek

kapcsolati sztring attribútumai

query-request attribútumok

lekérdezés-kérelem elemei

paraméterattribútumok

lapozási elemek

max-item-count attribútum

folytatási jogkivonat attribútum

olvasási-kérési elemek

delete-request attribútumok

delete-request elements

write-request attribútumok

írási-kérési elemek

válaszelemek

partíciókulcs-attribútumok

etag attribútum

Használat

Használati megjegyzések

Felügyelt identitásintegráció konfigurálása a Cosmos DB-vel

Előfeltételek

Azure CLI-szkript a felügyelt identitás konfigurálásához

Példák

Cosmos DB-lekérdezési kérelem

Cosmos DB olvasási kérése

Cosmos DB törlési kérése

Cosmos DB írási kérése

Paraméterbemenet létrehozása Cosmos DB-lekérdezéshez

JSON-objektum (JObject) átadása kifejezésből

.NET bemeneti típus (sztring, int, decimális, bool) átadása kifejezésből

JSON-érték (JValue) átadása kifejezésből

Kapcsolódó szabályzatok

Kapcsolódó tartalom

Visszajelzés

További források