Condividi tramite

Origine dati di Cosmos DB per un resolver

  • Articolo

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

Il criterio resolver cosmosdb-data-source 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 di Cosmos DB.

Nota

Questo criterio è in anteprima. Attualmente, i criteri non sono supportati nel livello a consumo di API Management.

Nota

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

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-request o write-request
read-request Specifica le impostazioni per una richiesta di lettura al contenitore Cosmos DB. Configurare uno di query-request, read-request, delete-request o write-request
delete-request Specifica le impostazioni per una richiesta di eliminazione al contenitore Cosmos DB. Configurare uno di query-request, read-request, delete-request o write-request
write-request Specifica le impostazioni per una richiesta di scrittura al contenitore Cosmos DB. Configurare uno di query-request, read-request, delete-request o write-request
response Facoltativamente, specifica i criteri figlio per configurare la risposta del resolver. Se non specificato, la risposta viene restituita da Cosmos DB come JSON. No

elementi connection-info

Nome Descrizione Richiesto
connection-string Specifica la stringa di connessione per un account Cosmos DB. Se è configurata un'identità gestita di 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 connection-string

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

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

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
partition-key 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 del parametro

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 ogni esecuzione di query. Sì
continuation-token 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 è:

- liquid: max-item-count userà il motore di creazione di modelli Liquid.		 No N/D

attributo continuation-token

Attributo Descrizione Richiesto Valore predefinito
annidato Utilizzato per 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 di modelli Liquid.		 No N/D

elementi read-request

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

attributi delete-request

Attributo Descrizione Richiesto Valore predefinito
consistency-level 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ì
partition-key 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 Il tipo di richiesta di scrittura: insert, replace o upsert. No upsert
consistency-level String. Imposta il livello di coerenza di Cosmos DB della richiesta di scrittura. No N/D
indexing-directive 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 fornito, il payload della richiesta eseguirà il mapping degli argomenti in formato JSON. No

elementi della risposta

Nome Descrizione Richiesto
set-body Imposta il corpo nella risposta del resolver. Se non fornito 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

partition-key attributes

Attributo Descrizione Richiesto Valore predefinito
data-type Tipo di dati della chiave di partizione: string, number, bool, none o null. No string
annidato Utilizzato per 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 creazione di modelli Liquid		 No N/D

attributo etag

Attributo Descrizione Richiesto Valore predefinito
type String. Uno dei valori seguenti:

- match: il valore etag deve corrispondere al tag di entità generato dal sistema per l'elemento

- no-match: il valore etag non deve necessariamente 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 creazione di modelli Liquid		 No N/D

Utilizzo

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 dell'identità gestita con Cosmos DB

È possibile configurare un'identità gestita assegnata dal sistema di 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

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

Nell'esempio seguente viene risolta 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 di punti in 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.

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

<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 con una richiesta di eliminazione in un contenitore Cosmos DB. id e partition-key usati per la richiesta di eliminazione vengono passati come parametri di query a cui si accede usando la variabile di contesto context.GraphQL.Arguments["id"].

<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 con una richiesta di upsert in 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 a cui si accede usando la variabile di contesto context.GraphQL.Arguments["id"]. La richiesta di upsert ha un'operazione pre-trigger denominata "validateInput". Il corpo della richiesta viene mappato usando un modello Liquid.

<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 sul seguente schema GraphQL di esempio 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) dall'espressione

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

Contenuto correlato

Per ulteriori informazioni sull'utilizzo dei criteri, vedere: