Cosmos DB-datakälla för en lösning

Artikel
03/18/2024

Matchningsprincipen cosmosdb-data-source löser data för en objekttyp och ett fält i ett GraphQL-schema med hjälp av en Cosmos DB-datakälla . Schemat måste importeras till API Management som ett GraphQL-API.

Använd principen för att konfigurera en enskild frågebegäran, läsa begäran, ta bort begäran eller skriva begäran och ett valfritt svar från Cosmos DB-datakällan.

Kommentar

Den här principen är i förhandsversion. För närvarande stöds inte principen på förbrukningsnivån för API Management.

Kommentar

Ange principens element och underordnade element i den ordning som anges i principbeskrivningen. Läs mer om hur du anger eller redigerar API Management-principer.

Principuttryck

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

Element

Name	beskrivning	Obligatoriskt
connection-info	Anger anslutning till container i Cosmos DB-databasen.	Ja
query-request	Anger inställningar för en frågebegäran till Cosmos DB-containern.	Konfigurera en av `query-request`, `read-request`, `delete-request`eller `write-request`
read-request	Anger inställningar för en läsbegäran till Cosmos DB-containern.	Konfigurera en av `query-request`, `read-request`, `delete-request`eller `write-request`
delete-request	Anger inställningar för en borttagningsbegäran till Cosmos DB-containern.	Konfigurera en av `query-request`, `read-request`, `delete-request`eller `write-request`
skrivbegäran	Anger inställningar för en skrivbegäran till Cosmos DB-containern.	Konfigurera en av `query-request`, `read-request`, `delete-request`eller `write-request`
svar	Du kan också ange underordnade principer för att konfigurera matcharens svar. Om inget anges returneras svaret från Cosmos DB som JSON.	Nej

connection-info-element

Name	beskrivning	Obligatoriskt
connection-string	Anger anslutningssträng för Cosmos DB-kontot. Om en hanterad API Management-identitet har konfigurerats utelämnar du kontonyckeln.	Ja
database-name	Sträng. Namnet på Cosmos DB-databasen.	Ja
containernamn	Sträng. Namnet på containern i Cosmos DB-databasen.	Ja

anslutningssträngsattribut

Attribut	beskrivning	Obligatoriskt	Standardvärde
use-managed-identity	Boolesk. Anger om API Management-instansens systemtilldelade hanterade identitet ska användas för anslutning till Cosmos DB-kontot i stället för en kontonyckel i anslutningssträng. Identiteten måste konfigureras för åtkomst till Cosmos DB-containern.	Nej	`false`

attribut för frågebegäran

Attribut	beskrivning	Obligatoriskt	Standardvärde
enable-low-precision-order-by	Boolesk. Anger om du vill aktivera egenskapen EnableLowPrecisionOrderBy-frågebegäran i Cosmos DB-tjänsten.	Nej	Ej tillämpligt

frågebegärandeelement

Name	beskrivning	Obligatoriskt
sql-instruktion	En SQL-instruktion för frågebegäran.	Nej
parametrar	En lista över frågeparametrar i parameterunderelement för frågebegäran.	Nej
partitionsnyckel	En Cosmos DB-partitionsnyckel för att dirigera frågan till platsen i containern.	Nej
Personsökning	Anger inställningar för att dela upp frågeresultat i flera sidor.	Nej

parameterattribut

Attribut	beskrivning	Obligatoriskt	Standardvärde
name	Sträng. Namnet på parametern i @ notation.	Ja	Ej tillämpligt

sidindelningselement

Name	beskrivning	Obligatoriskt
max-item-count	Anger det maximala antalet objekt som returneras av frågan. Ange till -1 om du inte vill sätta en gräns för antalet resultat per frågekörning.	Ja
fortsättningstoken	Anger fortsättningstoken som ska kopplas till frågan för att hämta nästa uppsättning resultat.	Ja

attributet max-item-count

Attribut	beskrivning	Obligatoriskt	Standardvärde
mall	Används för att ange templateringsläget för `max-item-count`. För närvarande är det enda värde som stöds: - `liquidmax-item-count`- använder vätskeberäkningsmotorn.	Nej	Ej tillämpligt

attributet continuation-token

Attribut	beskrivning	Obligatoriskt	Standardvärde
mall	Används för att ange mallläge för fortsättningstoken. För närvarande är det enda värde som stöds: - `liquid` - fortsättningstoken använder motorn för flytande templating.	Nej	Ej tillämpligt

read-request-element

Name	beskrivning	Obligatoriskt
id	Identifierare för objektet som ska läsas i containern.	Ja
partitionsnyckel	En partitionsnyckel för platsen för objektet i containern. Om det anges med `id`aktiverar du en snabbpunktsläsning (nyckel/värde-sökning) för objektet i containern.	Nej

attribut för delete-request

Attribut	beskrivning	Obligatoriskt	Standardvärde
konsekvensnivå	Sträng. Anger Cosmos DB-konsekvensnivån för borttagningsbegäran.	Nej	Ej tillämpligt
pre-trigger	Sträng. Identifierare för en pre-trigger-funktion som är registrerad i Cosmos DB-containern.	Nej	Ej tillämpligt
efterutlösare	Sträng. Identifierare för en post-trigger-funktion som är registrerad i cosmos DB-containern.	Nej	Ej tillämpligt

delete-request-element

Name	beskrivning	Obligatoriskt
id	Identifierare för objektet som ska tas bort i containern.	Ja
partitionsnyckel	En partitionsnyckel för platsen för objektet i containern.	Nej
etag	Entitetstagg för objektet i containern, som används för optimistisk samtidighetskontroll.	Nej

attribut för skrivbegäran

Attribut	beskrivning	Obligatoriskt	Standardvärde
type	Typ av skrivbegäran: `insert`, `replace`eller `upsert`.	Nej	`upsert`
konsekvensnivå	Sträng. Anger Cosmos DB-konsekvensnivån för skrivbegäran.	Nej	Ej tillämpligt
indexeringsdirektiv	Indexeringsprincipen som avgör hur containerns objekt ska indexeras.	Nej	`default`
pre-trigger	Sträng. Identifierare för en pre-trigger-funktion som är registrerad i Cosmos DB-containern.	Nej	Ej tillämpligt
efterutlösare	Sträng. Identifierare för en post-trigger-funktion som är registrerad i cosmos DB-containern.	Nej	Ej tillämpligt

element för skrivbegäran

Name	beskrivning	Obligatoriskt
id	Identifierare för objektet i containern.	Ja när `type` är `replace`.
etag	Entitetstagg för objektet i containern, som används för optimistisk samtidighetskontroll.	Nej
set-body	Anger brödtexten i skrivbegäran. Om det inte anges mappar nyttolasten för begäran argument till JSON-format.	Nej

svarselement

Name	beskrivning	Obligatoriskt
set-body	Anger brödtexten i matcharens svar. Om det inte anges och den returnerade JSON:n innehåller fältnamn som matchar fälten i GraphQL-schemat mappas fälten automatiskt.	Nej
publish-event	Publicerar en händelse till en eller flera prenumerationer som anges i GraphQL API-schemat.	Nej

partitionsnyckelattribut

Attribut	beskrivning	Obligatoriskt	Standardvärde
datatyp	Datatypen för partitionsnyckeln: `string`, `number`, `bool`, `none`eller `null`.	Nej	`string`
mall	Används för att ange inställningsläget för partitionsnyckeln. För närvarande är det enda värde som stöds: - `liquid` – partitionsnyckeln använder motorn för flytande templating	Nej	Ej tillämpligt

etag-attribut

Attribut	beskrivning	Obligatoriskt	Standardvärde
type	Sträng. Ett av följande värden: - `match` – värdet `etag` måste matcha den systemgenererade entitetstaggen för objektet - `no-match` – värdet `etag` krävs inte för att matcha den systemgenererade entitetstaggen för objektet	Nej	`match`
mall	Används för att ange inställningsläget för etag. För närvarande är det enda värde som stöds: - `liquid` - etag använder vätskeberäkningsmotorn	Nej	Ej tillämpligt

Förbrukning

Principomfattningar: GraphQL-matchare
Gatewayer: klassisk, v2

Användningsanteckningar

Information om hur du konfigurerar och hanterar en lösning med den här principen finns i Konfigurera en GraphQL-matchare.
Den här principen anropas endast när du löser ett enda fält i en matchande åtgärdstyp i schemat.

Konfigurera integrering av hanterad identitet med Cosmos DB

Du kan konfigurera en API Management-systemtilldelad hanterad identitet för åtkomst till ett Cosmos DB-konto i stället för att ange en kontonyckel i anslutningssträng.

Följ de här stegen för att använda Azure CLI för att konfigurera den hanterade identiteten.

Förutsättningar

Aktivera en systemtilldelad hanterad identitet i din API Management-instans. Observera objekt-ID:t (huvudnamn) för den hanterade identiteten i portalen.
- Använd Bash-miljön i Azure Cloud Shell. Mer information finns i Snabbstart för Bash i Azure Cloud Shell.
- Om du föredrar att köra CLI-referenskommandon lokalt installerar du Azure CLI. Om du kör i Windows eller macOS kan du köra Azure CLI i en Docker-container. Mer information finns i Så här kör du Azure CLI i en Docker-container.
  - Om du använder en lokal installation loggar du in på Azure CLI med hjälp av kommandot az login. Slutför autentiseringsprocessen genom att följa stegen som visas i terminalen. Andra inloggningsalternativ finns i Logga in med Azure CLI.
  - När du uppmanas att installera Azure CLI-tillägget vid första användningen. Mer information om tillägg finns i Använda tillägg med Azure CLI.
  - Kör az version om du vill hitta versionen och de beroende bibliotek som är installerade. Om du vill uppgradera till den senaste versionen kör du az upgrade.

Azure CLI-skript för att konfigurera den hanterade identiteten

# 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

Exempel

Cosmos DB-frågebegäran

I följande exempel matchas en GraphQL-fråga med hjälp av en SQL-fråga till en Cosmos DB-container.

<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-läsbegäran

I följande exempel matchas en GraphQL-fråga med hjälp av en punktläsningsbegäran till en Cosmos DB-container. Anslutningen till Cosmos DB-kontot använder API Management-instansens systemtilldelade hanterade identitet. Identiteten måste konfigureras för åtkomst till Cosmos DB-containern.

Och id partition-key används för läsbegäran skickas som frågeparametrar och används med hjälp av context.GraphQL.Arguments["id"] kontextvariabeln.

<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-borttagningsbegäran

I följande exempel löses en GraphQL-mutation genom en borttagningsbegäran till en Cosmos DB-container. Och id partition-key som används för borttagningsbegäran skickas som frågeparametrar och används med hjälp av context.GraphQL.Arguments["id"] kontextvariabeln.

<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-skrivbegäran

I följande exempel löses en GraphQL-mutation genom en upsert-begäran till en Cosmos DB-container. Anslutningen till Cosmos DB-kontot använder API Management-instansens systemtilldelade hanterade identitet. Identiteten måste konfigureras för åtkomst till Cosmos DB-containern.

Den partition-key som används för skrivbegäran skickas som en frågeparameter och används med hjälp av context.GraphQL.Arguments["id"] kontextvariabeln. Upsert-begäran har en förutlösare med namnet "validateInput". Begärandetexten mappas med hjälp av en flytande mall.

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

Skapa parameterindata för Cosmos DB-fråga

I följande exempel visas olika sätt att konstruera cosmos DB-parametriserade frågor med hjälp av principuttryck. Välj en metod baserat på formen på dina parameterindata.

Exemplen baseras på följande GraphQL-exempelschema och genererar motsvarande Cosmos DB-parametriserade fråga.

Exempel på GraphQL-schema

input personInput {
  id: String!
  firstName: String
}

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

Exempel på Cosmos DB-fråga

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

Skicka JSON-objekt (JObject) från uttryck

Exempelprincip

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

Skicka .NET-indatatyp (sträng, int, decimal, bool) från uttryck

Exempelprincip

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

Skicka JSON-värde (JValue) från uttryck

Exempelprincip

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

Mer information om hur du arbetar med principer finns i:

Självstudie: Transformera och skydda ditt API
Principreferens för en fullständig lista över principinstruktioner och deras inställningar
Principuttryck
Ange eller redigera principer
Återanvända principkonfigurationer
Lagringsplats för principfragment
Skapa principer med Microsoft Copilot i Azure

Dela via

Cosmos DB-datakälla för en lösning

Principuttryck

Element

connection-info-element

anslutningssträngsattribut

attribut för frågebegäran

frågebegärandeelement

parameterattribut

sidindelningselement

attributet max-item-count

attributet continuation-token

read-request-element

attribut för delete-request

delete-request-element

attribut för skrivbegäran

element för skrivbegäran

svarselement

partitionsnyckelattribut

etag-attribut

Förbrukning

Användningsanteckningar

Konfigurera integrering av hanterad identitet med Cosmos DB

Förutsättningar

Azure CLI-skript för att konfigurera den hanterade identiteten

Exempel

Cosmos DB-frågebegäran

Cosmos DB-läsbegäran

Cosmos DB-borttagningsbegäran

Cosmos DB-skrivbegäran

Skapa parameterindata för Cosmos DB-fråga

Skicka JSON-objekt (JObject) från uttryck

Skicka .NET-indatatyp (sträng, int, decimal, bool) från uttryck

Skicka JSON-värde (JValue) från uttryck

Feedback

Ytterligare resurser

Dela via

Cosmos DB-datakälla för en lösning

Principuttryck

Element

connection-info-element

anslutningssträngsattribut

attribut för frågebegäran

frågebegärandeelement

parameterattribut

sidindelningselement

attributet max-item-count

attributet continuation-token

read-request-element

attribut för delete-request

delete-request-element

attribut för skrivbegäran

element för skrivbegäran

svarselement

partitionsnyckelattribut

etag-attribut

Förbrukning

Användningsanteckningar

Konfigurera integrering av hanterad identitet med Cosmos DB

Förutsättningar

Azure CLI-skript för att konfigurera den hanterade identiteten

Exempel

Cosmos DB-frågebegäran

Cosmos DB-läsbegäran

Cosmos DB-borttagningsbegäran

Cosmos DB-skrivbegäran

Skapa parameterindata för Cosmos DB-fråga

Skicka JSON-objekt (JObject) från uttryck

Skicka .NET-indatatyp (sträng, int, decimal, bool) från uttryck

Skicka JSON-värde (JValue) från uttryck

Relaterade principer

Relaterat innehåll

Feedback

Ytterligare resurser