Cosmos DB-gegevensbron voor een resolver

VAN TOEPASSING OP: Ontwikkelaar | Basic | Basic v2 | Standaard | Standard v2 | Premium

Met cosmosdb-data-source het beleid voor resolver worden gegevens voor een objecttype en veld in een GraphQL-schema omgezet met behulp van een Cosmos DB-gegevensbron . Het schema moet als GraphQL-API worden geïmporteerd in API Management.

Gebruik het beleid voor het configureren van één queryaanvraag, leesaanvraag, verwijderaanvraag of schrijfaanvraag en een optioneel antwoord van de Cosmos DB-gegevensbron.

Notitie

Dit beleid is in preview. Het beleid wordt momenteel niet ondersteund in de verbruikslaag van API Management.

Notitie

Stel de elementen en onderliggende elementen van het beleid in de volgorde in die in de beleidsverklaring is opgegeven. Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsinstructie

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

Elementen

Name	Beschrijving	Vereist
connection-info	Hiermee geeft u verbinding met container in Cosmos DB-database.	Ja
query-aanvraag	Hiermee geeft u instellingen voor een queryaanvraag naar Cosmos DB-container.	Configureer een vanquery-request, read-request, of delete-requestwrite-request
read-request	Hiermee geeft u instellingen voor een leesaanvraag voor Cosmos DB-container.	Configureer een vanquery-request, read-request, of delete-requestwrite-request
delete-request	Hiermee geeft u instellingen voor een verwijderaanvraag naar Cosmos DB-container.	Configureer een vanquery-request, read-request, of delete-requestwrite-request
write-request	Hiermee geeft u instellingen voor een schrijfaanvraag naar Cosmos DB-container.	Configureer een vanquery-request, read-request, of delete-requestwrite-request
Reactie	Optioneel geeft u onderliggend beleid op om het antwoord van de resolver te configureren. Als dit niet is opgegeven, wordt het antwoord geretourneerd vanuit Cosmos DB als JSON.	Nee

verbindings-info-elementen

Name	Beschrijving	Vereist
connection-string	Hiermee geeft u de verbindingsreeks voor Cosmos DB-account. Als een door API Management beheerde identiteit is geconfigureerd, laat u de accountsleutel weg.	Ja
databasenaam	Tekenreeks. Naam van Cosmos DB-database.	Ja
container-name	Tekenreeks. Naam van container in Cosmos DB-database.	Ja

verbindingsreekskenmerken

Kenmerk	Beschrijving	Vereist	Standaardinstelling
use-managed-identity	Booleaans. Hiermee geeft u op of de door het systeem toegewezen beheerde identiteit van het API Management-exemplaar moet worden gebruikt voor verbinding met het Cosmos DB-account in plaats van een accountsleutel in de verbindingsreeks. De identiteit moet worden geconfigureerd voor toegang tot de Cosmos DB-container.	Nee	false

query-aanvraagkenmerken

Kenmerk	Beschrijving	Vereist	Standaardinstelling
lage precisievolgorde inschakelen op	Booleaans. Hiermee geeft u op of de eigenschap EnableLowPrecisionOrderBy-queryaanvraag moet worden ingeschakeld in de Cosmos DB-service.	Nee	N.v.t.

query-aanvraagelementen

Name	Beschrijving	Vereist
sql-statement	Een SQL-instructie voor de queryaanvraag.	Nee
parameters	Een lijst met queryparameters, in parametersubelementen , voor de queryaanvraag.	Nee
partitiesleutel	Een Cosmos DB-partitiesleutel om de query naar de locatie in de container te routeren.	Nee
Paging	Hiermee geeft u instellingen voor het splitsen van queryresultaten in meerdere pagina's.	Nee

parameterkenmerken

Kenmerk	Beschrijving	Vereist	Standaardinstelling
naam	Tekenreeks. Naam van de parameter in @notatie.	Ja	N.v.t.

paging-elementen

Name	Beschrijving	Vereist
max-item-count	Hiermee geeft u het maximum aantal items op dat door de query wordt geretourneerd. Ingesteld op -1 als u geen limiet wilt instellen voor het aantal resultaten per query-uitvoering.	Ja
vervolgtoken	Hiermee geeft u het vervolgtoken op dat moet worden gekoppeld aan de query om de volgende set resultaten op te halen.	Ja

kenmerk max-item-count

Kenmerk	Beschrijving	Vereist	Standaardinstelling
sjabloon	Wordt gebruikt voor het instellen van de tempatiemodus voor de max-item-count. Momenteel is de enige ondersteunde waarde: - liquid - de max-item-count zal het gebruik van de vloeistof verleiden motor.	Nee	N.v.t.

vervolgtokenkenmerk

Kenmerk	Beschrijving	Vereist	Standaardinstelling
sjabloon	Wordt gebruikt om de verleidmodus voor het vervolgtoken in te stellen. Momenteel is de enige ondersteunde waarde: - liquid - het vervolgtoken zal de vloeistofverleidingsmotor gebruiken.	Nee	N.v.t.

lees-aanvraagelementen

Name	Beschrijving	Vereist
id	Id van het item dat moet worden gelezen in de container.	Ja
partitiesleutel	Een partitiesleutel voor de locatie van het item in de container. Indien opgegeven met id, schakelt u een snel punt lezen (sleutel/waarde opzoeken) van het item in de container in.	Nee

kenmerken van delete-request

Kenmerk	Beschrijving	Vereist	Standaardinstelling
consistentieniveau	Tekenreeks. Hiermee stelt u het consistentieniveau van Cosmos DB van de verwijderaanvraag in.	Nee	N.v.t.
pre-trigger	Tekenreeks. Id van een vooraf geactiveerde functie die is geregistreerd in uw Cosmos DB-container.	Nee	N.v.t.
post-trigger	Tekenreeks. Id van een functie na trigger die is geregistreerd in uw Cosmos DB-container.	Nee	N.v.t.

verwijder-aanvraagelementen

Name	Beschrijving	Vereist
id	Id van het item dat u in de container wilt verwijderen.	Ja
partitiesleutel	Een partitiesleutel voor de locatie van het item in de container.	Nee
etag	Entiteitstag voor het item in de container, gebruikt voor optimistisch gelijktijdigheidsbeheer.	Nee

kenmerken voor write-request

Kenmerk	Beschrijving	Vereist	Standaardinstelling
type	Het type schrijfaanvraag: insert, replaceof upsert.	Nee	upsert
consistentieniveau	Tekenreeks. Hiermee stelt u het cosmos DB-consistentieniveau van de schrijfaanvraag in.	Nee	N.v.t.
indexeringsrichtlijn	Het indexeringsbeleid dat bepaalt hoe de items van de container moeten worden geïndexeerd.	Nee	default
pre-trigger	Tekenreeks. Id van een vooraf geactiveerde functie die is geregistreerd in uw Cosmos DB-container.	Nee	N.v.t.
post-trigger	Tekenreeks. Id van een functie na trigger die is geregistreerd in uw Cosmos DB-container.	Nee	N.v.t.

elementen voor write-request

Name	Beschrijving	Vereist
id	Id van het item in de container.	Ja wanneer type is replace.
etag	Entiteitstag voor het item in de container, gebruikt voor optimistisch gelijktijdigheidsbeheer.	Nee
set-body	Hiermee stelt u de hoofdtekst in de schrijfaanvraag in. Als deze niet is opgegeven, worden argumenten in JSON-indeling toegewezen door de nettolading van de aanvraag.	Nee

antwoordelementen

Name	Beschrijving	Vereist
set-body	Hiermee stelt u de hoofdtekst in het antwoord van de resolver in. Als dit niet is opgegeven en de geretourneerde JSON veldnamen bevat die overeenkomen met velden in het GraphQL-schema, worden de velden automatisch toegewezen.	Nee
publish-event	Hiermee publiceert u een gebeurtenis naar een of meer abonnementen die zijn opgegeven in het GraphQL API-schema.	Nee

partitiesleutelkenmerken

Kenmerk	Beschrijving	Vereist	Standaardinstelling
gegevenstype	Het gegevenstype van de partitiesleutel: string, number, bool, of nonenull.	Nee	string
sjabloon	Wordt gebruikt om de tempatiemodus voor de partitiesleutel in te stellen. Momenteel is de enige ondersteunde waarde: - liquid - de partitiesleutel gebruikt de vloeistofverleidingsengine	Nee	N.v.t.

etag-kenmerk

Kenmerk	Beschrijving	Vereist	Standaardinstelling
type	Tekenreeks. Een van de volgende waarden: - match - de etag waarde moet overeenkomen met de door het systeem gegenereerde entiteitstag voor het item - no-match - de etag waarde is niet vereist om overeen te komen met de door het systeem gegenereerde entiteitstag voor het item	Nee	match
sjabloon	Wordt gebruikt om de tempatiemodus voor de etag in te stellen. Momenteel is de enige ondersteunde waarde: - liquid - de etag gebruikt de vloeistofverleidingsmotor	Nee	N.v.t.

Gebruik

• Beleidsbereiken: GraphQL-resolver
• Gateways: klassiek, v2

Gebruiksnotities

• Als u een resolver met dit beleid wilt configureren en beheren, raadpleegt u Een GraphQL-resolver configureren.
• Dit beleid wordt alleen aangeroepen bij het omzetten van één veld in een overeenkomend bewerkingstype in het schema.

Integratie van beheerde identiteiten configureren met Cosmos DB

U kunt een door het API Management-systeem toegewezen beheerde identiteit configureren voor toegang tot een Cosmos DB-account in plaats van een accountsleutel op te geven in de verbindingsreeks.

Volg deze stappen om de Azure CLI te gebruiken om de beheerde identiteit te configureren.

Vereisten

• Schakel een door het systeem toegewezen beheerde identiteit in uw API Management-exemplaar in. Noteer in de portal de object-id (principal) van de beheerde identiteit.

• • Gebruik de Bash-omgeving in Azure Cloud Shell. Zie quickstart voor Bash in Azure Cloud Shell voor meer informatie.

    

  • Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren. Als u in Windows of macOS werkt, kunt u Azure CLI uitvoeren in een Docker-container. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.

    • Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met behulp van de opdracht az login. Volg de stappen die worden weergegeven in de terminal, om het verificatieproces te voltooien. Raadpleeg Aanmelden bij Azure CLI voor aanvullende aanmeldingsopties.

    • Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Raadpleeg Extensies gebruiken met Azure CLI voor meer informatie over extensies.

    • Voer az version uit om de geïnstalleerde versie en afhankelijke bibliotheken te vinden. Voer az upgrade uit om te upgraden naar de nieuwste versie.

Azure CLI-script voor het configureren van de beheerde identiteit

# 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    

Voorbeelden

Cosmos DB-queryaanvraag

In het volgende voorbeeld wordt een GraphQL-query met behulp van een SQL-query omgezet in een 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>

Leesaanvraag voor Cosmos DB

In het volgende voorbeeld wordt een GraphQL-query omgezet met behulp van een puntleesaanvraag voor een Cosmos DB-container. De verbinding met het Cosmos DB-account maakt gebruik van de door het systeem toegewezen beheerde identiteit van het API Management-exemplaar. De identiteit moet worden geconfigureerd voor toegang tot de Cosmos DB-container.

De id en partition-key die worden gebruikt voor de leesaanvraag worden doorgegeven als queryparameters en gebruikt met behulp van de context.GraphQL.Arguments["id"] contextvariabele.

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

In het volgende voorbeeld wordt een GraphQL-mutatie opgelost door een verwijderaanvraag voor een Cosmos DB-container. De id en partition-key die worden gebruikt voor de verwijderaanvraag worden doorgegeven als queryparameters en worden geopend met behulp van de context.GraphQL.Arguments["id"] contextvariabele.

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

In het volgende voorbeeld wordt een GraphQL-mutatie opgelost door een upsert-aanvraag voor een Cosmos DB-container. De verbinding met het Cosmos DB-account maakt gebruik van de door het systeem toegewezen beheerde identiteit van het API Management-exemplaar. De identiteit moet worden geconfigureerd voor toegang tot de Cosmos DB-container.

De partition-key gebruikte voor de schrijfaanvraag wordt doorgegeven als een queryparameter en wordt geopend met behulp van de context.GraphQL.Arguments["id"] contextvariabele. De upsert-aanvraag heeft een pre-triggerbewerking met de naam 'validateInput'. De hoofdtekst van de aanvraag wordt toegewezen met behulp van een vloeibare sjabloon.

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

Parameterinvoer maken voor Cosmos DB-query

In de volgende voorbeelden ziet u manieren om geparameteriseerde query's van Cosmos DB te maken met behulp van beleidsexpressies. Kies een methode op basis van de vorm van de parameterinvoer.

De voorbeelden zijn gebaseerd op het volgende GraphQL-voorbeeldschema en genereren de bijbehorende cosmos DB-geparameteriseerde query.

Voorbeeld van GraphQL-schema

input personInput {
  id: String!
  firstName: String
}

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

Voorbeeld van Cosmos DB-query

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

JSON-object (JObject) doorgeven vanuit expressie

Voorbeeldbeleid

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

Geef het .NET-invoertype (tekenreeks, int, decimaal, bool) van de expressie door

Voorbeeldbeleid

[...]
<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-waarde (JValue) doorgeven vanuit expressie

Voorbeeldbeleid

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

Gerelateerd beleid

• GraphQL-resolvers

Gerelateerde inhoud

Zie voor meer informatie over het werken met beleid:

• Zelfstudie: Uw API transformeren en beveiligen
• Beleidsreferentie voor een volledige lijst met beleidsinstructies en hun instellingen
• Beleidsexpressies
• Beleid instellen of bewerken
• Beleidsconfiguraties opnieuw gebruiken
• Beleidsfragmentenopslagplaats
• Beleid ontwerpen met Behulp van Microsoft Copilot voor Azure