Origine dati di Cosmos DB per un sistema di risoluzione

SI APPLICA A: Sviluppatore | Basic | Basic v2 | Standard | Standard v2 | Premium

Il cosmosdb-data-source criterio resolver risolve i dati per un tipo di oggetto e un campo in uno schema GraphQL usando un'origine dati Cosmos DB . Lo schema deve essere importato in Gestione API come API GraphQL.

Usare i criteri per configurare una singola richiesta di query, una richiesta di lettura, una richiesta di eliminazione o una richiesta di scrittura e una risposta facoltativa dall'origine dati cosmos DB.

Nota

Questo criterio è in anteprima. Attualmente, il criterio non è supportato nel livello Consumo di Gestione API.

Nota

Impostare gli elementi e gli elementi figlio del criterio nell'ordine specificato nell'istruzione dei criteri. Altre informazioni su come impostare o modificare i criteri di Gestione API.

Istruzione del criterio

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

Elementi

Nome	Descrizione	Richiesto
connection-info	Specifica la connessione al contenitore nel database Cosmos DB.	Sì
query-request	Specifica le impostazioni per una richiesta di query al contenitore Cosmos DB.	Configurare uno di query-request, read-request, delete-requesto write-request
read-request	Specifica le impostazioni per una richiesta di lettura al contenitore Cosmos DB.	Configurare uno di query-request, read-request, delete-requesto write-request
delete-request	Specifica le impostazioni per una richiesta di eliminazione al contenitore Cosmos DB.	Configurare uno di query-request, read-request, delete-requesto write-request
write-request	Specifica le impostazioni per una richiesta di scrittura nel contenitore Cosmos DB.	Configurare uno di query-request, read-request, delete-requesto write-request
Risposta	Facoltativamente, specifica i criteri figlio per configurare la risposta del sistema di risoluzione. Se non specificato, la risposta viene restituita da Cosmos DB come JSON.	No

elementi di connection-info

Nome	Descrizione	Richiesto
connection-string	Specifica il stringa di connessione per l'account Cosmos DB. Se è configurata un'identità gestita Gestione API, omettere la chiave dell'account.	Sì
database-name	String. Nome del database Cosmos DB.	Sì
container-name	String. Nome del contenitore nel database Cosmos DB.	Sì

attributi della stringa di connessione

Attributo	Descrizione	Richiesto	Valore predefinito
use-managed-identity	Booleano. Specifica se usare l'identità gestita assegnata dal sistema dell'istanza di Gestione API per la connessione all'account Cosmos DB al posto di una chiave dell'account nella stringa di connessione. L'identità deve essere configurata per accedere al contenitore Cosmos DB.	No	false

Attributi della richiesta di query

Attributo	Descrizione	Richiesto	Valore predefinito
enable-low-precision-order-by	Booleano. Specifica se abilitare la proprietà della richiesta di query EnableLowPrecisionOrderBy nel servizio Cosmos DB.	No	N/D

elementi della richiesta di query

Nome	Descrizione	Richiesto
sql-statement	Istruzione SQL per la richiesta di query.	No
parameters	Elenco di parametri di query, nei sottoelementi dei parametri , per la richiesta di query.	No
chiave di partizione	Una chiave di partizione di Cosmos DB per indirizzare la query alla posizione nel contenitore.	No
Paging	Specifica le impostazioni per suddividere i risultati delle query in più pagine.	No

attributi dei parametri

Attributo	Descrizione	Richiesto	Valore predefinito
name	String. Nome del parametro in notazione @.	Sì	N/D

elementi di paging

Nome	Descrizione	Richiesto
max-item-count	Specifica il numero massimo di elementi restituiti dalla query. Impostare su -1 se non si vuole applicare un limite al numero di risultati per esecuzione di query.	Sì
token di continuazione	Specifica il token di continuazione da associare alla query per ottenere il set di risultati successivo.	Sì

attributo max-item-count

Attributo	Descrizione	Richiesto	Valore predefinito
annidato	Utilizzato per impostare la modalità di creazione modelli per .max-item-count Al momento, l'unico valore supportato è: - liquidmax-item-count- userà il motore di templating liquido.	No	N/D

attributo del token di continuazione

Attributo	Descrizione	Richiesto	Valore predefinito
annidato	Consente di impostare la modalità di creazione modelli per il token di continuazione. Al momento, l'unico valore supportato è: - liquid : il token di continuazione userà il motore di creazione modelli liquida.	No	N/D

elementi read-request

Nome	Descrizione	Richiesto
id	Identificatore dell'elemento da leggere nel contenitore.	Sì
chiave di partizione	Chiave di partizione per la posizione dell'elemento nel contenitore. Se specificato con id, abilita una rapida lettura punto (ricerca chiave/valore) dell'elemento nel contenitore.	No

attributi delete-request

Attributo	Descrizione	Richiesto	Valore predefinito
livello di coerenza	String. Imposta il livello di coerenza di Cosmos DB della richiesta di eliminazione.	No	N/D
pre-trigger	String. Identificatore di una funzione pre-trigger registrata nel contenitore Cosmos DB.	No	N/D
post-trigger	String. Identificatore di una funzione post-trigger registrata nel contenitore Cosmos DB.	No	N/D

elementi delete-request

Nome	Descrizione	Richiesto
id	Identificatore dell'elemento da eliminare nel contenitore.	Sì
chiave di partizione	Chiave di partizione per la posizione dell'elemento nel contenitore.	No
etag	Tag di entità per l'elemento nel contenitore, usato per il controllo della concorrenza ottimistica.	No

attributi write-request

Attributo	Descrizione	Richiesto	Valore predefinito
type	Tipo di richiesta di scrittura: insert, replaceo upsert.	No	upsert
livello di coerenza	String. Imposta il livello di coerenza di Cosmos DB della richiesta di scrittura.	No	N/D
direttiva di indicizzazione	Criteri di indicizzazione che determinano la modalità di indicizzazione degli elementi del contenitore.	No	default
pre-trigger	String. Identificatore di una funzione pre-trigger registrata nel contenitore Cosmos DB.	No	N/D
post-trigger	String. Identificatore di una funzione post-trigger registrata nel contenitore Cosmos DB.	No	N/D

elementi write-request

Nome	Descrizione	Richiesto
id	Identificatore dell'elemento nel contenitore.	Sì quando type è replace.
etag	Tag di entità per l'elemento nel contenitore, usato per il controllo della concorrenza ottimistica.	No
set-body	Imposta il corpo nella richiesta di scrittura. Se non specificato, il payload della richiesta eseguirà il mapping degli argomenti in formato JSON.	No

elementi di risposta

Nome	Descrizione	Richiesto
set-body	Imposta il corpo nella risposta del sistema di risoluzione. Se non specificato e il codice JSON restituito contiene i nomi di campo corrispondenti ai campi nello schema GraphQL, i campi vengono mappati automaticamente.	No
publish-event	Pubblica un evento in una o più sottoscrizioni specificate nello schema dell'API GraphQL.	No

Attributi della chiave di partizione

Attributo	Descrizione	Richiesto	Valore predefinito
tipo di dati	Tipo di dati della chiave di partizione: string, number, bool, noneo null.	No	string
annidato	Consente di impostare la modalità di creazione modelli per la chiave di partizione. Al momento, l'unico valore supportato è: - liquid - La chiave di partizione userà il motore di templating liquido	No	N/D

Attributo etag

Attributo	Descrizione	Richiesto	Valore predefinito
type	String. Uno dei valori seguenti: - match : il etag valore deve corrispondere al tag di entità generato dal sistema per l'elemento - no-match - Il etag valore non deve corrispondere al tag di entità generato dal sistema per l'elemento	No	match
annidato	Utilizzato per impostare la modalità di creazione modelli per l'etag. Al momento, l'unico valore supportato è: - liquid - l'etag userà il motore di templating liquido	No	N/D

Utilizzo

• Ambiti dei criteri: resolver GraphQL
• Gateway: versione classica, v2

Note sull'utilizzo

• Per configurare e gestire un resolver con questo criterio, vedere Configurare un resolver GraphQL.
• Questo criterio viene richiamato solo quando si risolve un singolo campo in un tipo di operazione corrispondente nello schema.

Configurare l'integrazione delle identità gestite con Cosmos DB

È possibile configurare un'identità gestita assegnata dal sistema Gestione API per accedere a un account Cosmos DB, anziché fornire una chiave dell'account nella stringa di connessione.

Seguire questa procedura per usare l'interfaccia della riga di comando di Azure per configurare l'identità gestita.

Prerequisiti

• Abilitare un'identità gestita assegnata dal sistema nell'istanza di Gestione API. Nel portale prendere nota dell'ID dell'oggetto (entità) dell'identità gestita.

• • Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere la Avvio rapido di Bash in Azure Cloud Shell.

    

  • Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.

    • Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Accedere tramite l'interfaccia della riga di comando di Azure.

    • Quando richiesto, al primo utilizzo installare l'estensione dell'interfaccia della riga di comando di Azure. Per altre informazioni sulle estensioni, vedere Usare le estensioni con l'interfaccia della riga di comando di Azure.

    • Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.

Script dell'interfaccia della riga di comando di Azure per configurare l'identità gestita

# 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    

Esempi

Richiesta di query di Cosmos DB

L'esempio seguente risolve una query GraphQL usando una query SQL in un contenitore 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>

Richiesta di lettura di Cosmos DB

Nell'esempio seguente viene risolta una query GraphQL usando una richiesta di lettura punto a un contenitore Cosmos DB. La connessione all'account Cosmos DB usa l'identità gestita assegnata dal sistema dell'istanza di Gestione API. L'identità deve essere configurata per accedere al contenitore Cosmos DB.

E idpartition-key usati per la richiesta di lettura vengono passati come parametri di query e a cui si accede usando la variabile di context.GraphQL.Arguments["id"] contesto.

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

Richiesta di eliminazione di Cosmos DB

Nell'esempio seguente viene risolta una mutazione GraphQL da una richiesta di eliminazione a un contenitore Cosmos DB. partition-key E id usati per la richiesta di eliminazione vengono passati come parametri di query e a cui si accede usando la variabile di context.GraphQL.Arguments["id"] contesto.

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

Richiesta di scrittura di Cosmos DB

Nell'esempio seguente viene risolta una mutazione GraphQL da una richiesta upsert a un contenitore Cosmos DB. La connessione all'account Cosmos DB usa l'identità gestita assegnata dal sistema dell'istanza di Gestione API. L'identità deve essere configurata per accedere al contenitore Cosmos DB.

L'oggetto partition-key usato per la richiesta di scrittura viene passato come parametro di query e accessibile usando la variabile di context.GraphQL.Arguments["id"] contesto. La richiesta upsert ha un'operazione di pre-trigger denominata "validateInput". Il corpo della richiesta viene mappato usando un modello liquido.

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

Costruire l'input del parametro per la query di Cosmos DB

Gli esempi seguenti illustrano i modi per costruire query con parametri di Cosmos DB usando espressioni di criteri. Scegliere un metodo in base al formato dell'input del parametro.

Gli esempi sono basati sullo schema GraphQL di esempio seguente e generano la query con parametri di Cosmos DB corrispondente.

Schema GraphQL di esempio

input personInput {
  id: String!
  firstName: String
}

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

Query cosmos DB di esempio

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

Passare l'oggetto JSON (JObject) dall'espressione

Criteri di esempio

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

Passare il tipo di input .NET (string, int, decimal, bool) da expression

Criteri di esempio

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

Passare il valore JSON (JValue) dall'espressione

Criteri di esempio

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

Criteri correlati

• Resolver GraphQL

Contenuto correlato

Per ulteriori informazioni sull'utilizzo dei criteri, vedere:

• Esercitazione: Trasformare e proteggere l'API
• Informazioni di riferimento sui criteri per un elenco completo delle istruzioni dei criteri e delle relative impostazioni
• Espressioni di criteri
• Impostare o modificare criteri
• Riutilizzare le configurazioni dei criteri
• Repository dei frammenti di criteri
• Creare criteri con Microsoft Copilot per Azure