Zdroj dat Cosmos DB pro překladač

Článek
03/18/2024

Zásada cosmosdb-data-source překladače řeší data pro typ objektu a pole ve schématu GraphQL pomocí zdroje dat Cosmos DB . Schéma se musí importovat do služby API Management jako rozhraní GraphQL API.

Pomocí zásad můžete nakonfigurovat jeden požadavek dotazu, požadavek na čtení, požadavek na odstranění nebo požadavek na zápis a volitelnou odpověď ze zdroje dat Cosmos DB.

Poznámka:

Tato zásada je ve verzi Preview. V současné době se zásady nepodporují ve vrstvě Consumption služby API Management.

Poznámka:

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady služby API Management.

Prohlášení o zásadách

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

Elementy

Název	Popis	Povinní účastníci
connection-info	Určuje připojení ke kontejneru v databázi Cosmos DB.	Ano
query-request	Určuje nastavení pro požadavek dotazu na kontejner Cosmos DB.	Nakonfigurujte jednu z možností `query-request`, `read-request`nebo `delete-requestwrite-request`
read-request	Určuje nastavení požadavku na čtení pro kontejner Cosmos DB.	Nakonfigurujte jednu z možností `query-request`, `read-request`nebo `delete-requestwrite-request`
delete-request	Určuje nastavení požadavku na odstranění kontejneru Cosmos DB.	Nakonfigurujte jednu z možností `query-request`, `read-request`nebo `delete-requestwrite-request`
write-request	Určuje nastavení pro požadavek na zápis do kontejneru Cosmos DB.	Nakonfigurujte jednu z možností `query-request`, `read-request`nebo `delete-requestwrite-request`
Reakce	Volitelně můžete určit podřízené zásady pro konfiguraci odpovědi překladače. Pokud není zadána, odpověď se vrátí ze služby Cosmos DB jako JSON.	No

prvky connection-info

Název	Popis	Povinní účastníci
connection-string	Určuje připojovací řetězec pro účet služby Cosmos DB. Pokud je nakonfigurovaná spravovaná identita služby API Management, vynecháte klíč účtu.	Ano
název databáze	Řetězec. Název databáze Cosmos DB	Ano
název_kontejneru	Řetězec. Název kontejneru v databázi Cosmos DB	Ano

atributy připojovacího řetězce

Atribut	Popis	Požaduje se	Výchozí
use-managed-identity	Logický. Určuje, jestli se má použít spravovaná identita přiřazená systémem instance služby API Management pro připojení k účtu Cosmos DB místo klíče účtu v připojovací řetězec. Identita musí být nakonfigurovaná pro přístup ke kontejneru Cosmos DB.	No	`false`

atributy požadavku dotazu

Atribut	Popis	Požaduje se	Výchozí
enable-low-precision-order-by	Logický. Určuje, zda povolit EnableLowPrecisionOrderBy vlastnost požadavku na dotaz ve službě Cosmos DB.	No	–

Elementy požadavku dotazu

Název	Popis	Povinní účastníci
příkaz sql	Příkaz SQL pro požadavek dotazu.	No
parametry	Seznam parametrů dotazu v dílčích poplatcích parametru pro požadavek dotazu.	No
partition-key	Klíč oddílu Cosmos DB pro směrování dotazu do umístění v kontejneru.	No
Stránkování	Určuje nastavení pro rozdělení výsledků dotazu na více stránek.	No

atributy parametru

Atribut	Popis	Požaduje se	Výchozí
name	Řetězec. Název parametru v zápisu @	Yes	–

stránkovací prvky

Název	Popis	Povinní účastníci
max-item-count	Určuje maximální počet položek vrácených dotazem. Pokud nechcete omezit počet výsledků na provádění dotazu, nastavte hodnotu -1.	Ano
pokračovací token	Určuje token pro pokračování, který se má připojit k dotazu, aby se získala další sada výsledků.	Ano

max-item-count – atribut

Atribut	Popis	Požaduje se	Výchozí
šablona	Slouží k nastavení režimu šablonování pro .`max-item-count` V současné době je jediná podporovaná hodnota: - `liquidmax-item-count`- bude používat kapalinový modul šablony.	No	–

atribut pokračovací token

Atribut	Popis	Požaduje se	Výchozí
šablona	Slouží k nastavení režimu šablon pro token pokračování. V současné době je jediná podporovaná hodnota: - `liquid` - token pro pokračování bude používat modul templating kapaliny.	No	–

Elementy read-request

Název	Popis	Povinní účastníci
ID	Identifikátor položky, která se má přečíst v kontejneru.	Ano
partition-key	Klíč oddílu pro umístění položky v kontejneru. Pokud je zadaný parametrem `id`, povolí rychlé čtení (vyhledávání klíč/hodnota) položky v kontejneru.	No

atributy delete-request

Atribut	Popis	Požaduje se	Výchozí
úroveň konzistence	Řetězec. Nastaví úroveň konzistence cosmos DB požadavku na odstranění.	No	–
pre-trigger	Řetězec. Identifikátor funkce před triggerem, která je zaregistrovaná v kontejneru Cosmos DB.	No	–
post-trigger	Řetězec. Identifikátor funkce po aktivaci, která je zaregistrovaná v kontejneru Cosmos DB.	No	–

delete-request elements

Název	Popis	Povinní účastníci
ID	Identifikátor položky, kterou chcete odstranit v kontejneru.	Ano
partition-key	Klíč oddílu pro umístění položky v kontejneru.	No
Etag	Značka entity pro položku v kontejneru, která se používá k řízení optimistické souběžnosti.	No

atributy write-request

Atribut	Popis	Požaduje se	Výchozí
type	Typ žádosti o zápis: `insert`, `replace`nebo `upsert`.	No	`upsert`
úroveň konzistence	Řetězec. Nastaví úroveň konzistence služby Cosmos DB požadavku na zápis.	No	–
indexing-direktiva	Zásady indexování, které určují, jak se mají položky kontejneru indexovat.	No	`default`
pre-trigger	Řetězec. Identifikátor funkce před triggerem, která je zaregistrovaná v kontejneru Cosmos DB.	No	–
post-trigger	Řetězec. Identifikátor funkce po aktivaci, která je zaregistrovaná v kontejneru Cosmos DB.	No	–

Elementy pro zápis-požadavek

Název	Popis	Povinní účastníci
ID	Identifikátor položky v kontejneru	Ano, když `type` je `replace`.
Etag	Značka entity pro položku v kontejneru, která se používá k řízení optimistické souběžnosti.	No
set-body	Nastaví tělo v požadavku na zápis. Pokud není zadaný, datová část požadavku namapuje argumenty do formátu JSON.	No

elementy odpovědi

Název	Popis	Povinní účastníci
set-body	Nastaví tělo v odpovědi překladače. Pokud není zadaný a vrácený JSON obsahuje názvy polí odpovídajících polím ve schématu GraphQL, pole se automaticky mapují.	No
publish-event	Publikuje událost do jednoho nebo více odběrů zadaných ve schématu rozhraní GraphQL API.	No

Atributy klíče oddílu

Atribut	Popis	Požaduje se	Výchozí
datový typ	Datový typ klíče oddílu: `string`, `number`, `bool`, `none`nebo `null`.	No	`string`
šablona	Slouží k nastavení režimu šablonování klíče oddílu. V současné době je jediná podporovaná hodnota: - `liquid` - klíč oddílu bude používat modul šablon liquid	No	–

Atribut etag

Atribut	Popis	Požaduje se	Výchozí
type	Řetězec. Jedna z následujících hodnot: - `matchetag`– hodnota se musí shodovat se značkou entity vygenerovanou systémem pro položku. - `no-matchetag`– hodnota se nevyžaduje, aby odpovídala systémové značce entity vygenerované pro danou položku.	No	`match`
šablona	Slouží k nastavení režimu šablony pro etag. V současné době je jediná podporovaná hodnota: - `liquid` - etag bude používat modul templating kapaliny	No	–

Využití

Obory zásad: Překladač GraphQL
Brány: Classic, v2

Poznámky k využití

Informace o konfiguraci a správě překladače pomocí této zásady najdete v tématu Konfigurace překladače GraphQL.
Tato zásada se vyvolá pouze při překladu jednoho pole v odpovídajícím typu operace ve schématu.

Konfigurace integrace spravované identity se službou Cosmos DB

Spravovanou identitu přiřazenou systémem služby API Management můžete nakonfigurovat tak, aby přistupovala k účtu služby Cosmos DB, a nemusíte v připojovací řetězec zařazovat klíč účtu.

Pomocí tohoto postupu nakonfigurujte spravovanou identitu pomocí Azure CLI.

Požadavky

Povolte spravovanou identitu přiřazenou systémem ve vaší instanci služby API Management. Na portálu si poznamenejte ID objektu (objektu zabezpečení) spravované identity.
- Použijte prostředí Bash v Azure Cloud Shellu. Další informace najdete v tématu Rychlý start pro Bash v Azure Cloud Shellu.
- Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, nainstalujte Azure CLI. Pokud používáte Windows nebo macOS, zvažte spuštění Azure CLI v kontejneru Docker. Další informace najdete v tématu Jak spustit Azure CLI v kontejneru Dockeru.
  - Pokud používáte místní instalaci, přihlaste se k Azure CLI pomocí příkazu az login. Pokud chcete dokončit proces ověřování, postupujte podle kroků zobrazených na terminálu. Další možnosti přihlášení najdete v tématu Přihlášení pomocí Azure CLI.
  - Po zobrazení výzvy nainstalujte rozšíření Azure CLI při prvním použití. Další informace o rozšířeních najdete v tématu Využití rozšíření v Azure CLI.
  - Spuštěním příkazu az version zjistěte verzi a závislé knihovny, které jsou nainstalované. Pokud chcete upgradovat na nejnovější verzi, spusťte az upgrade.

Skript Azure CLI pro konfiguraci spravované identity

# 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říklady

Žádost o dotaz cosmos DB

Následující příklad přeloží dotaz GraphQL pomocí dotazu SQL na kontejner 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>

Žádost o čtení ve službě Cosmos DB

Následující příklad přeloží dotaz GraphQL pomocí požadavku na čtení bodu do kontejneru Cosmos DB. Připojení k účtu Cosmos DB používá spravovanou identitu přiřazenou systémem přiřazenou instancí služby API Management. Identita musí být nakonfigurovaná pro přístup ke kontejneru Cosmos DB.

Požadavek id pro čtení se partition-key předává jako parametry dotazu a přistupuje se k němu pomocí context.GraphQL.Arguments["id"] kontextové proměnné.

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

Žádost o odstranění služby Cosmos DB

Následující příklad vyřeší grafQL mutací odstraněním požadavku na kontejner Cosmos DB. Požadavek id na odstranění se partition-key předá jako parametry dotazu a použije se k němu pomocí kontextové context.GraphQL.Arguments["id"] proměnné.

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

Požadavek na zápis do služby Cosmos DB

Následující příklad přeloží mutaci GraphQL požadavkem upsert na kontejner Cosmos DB. Připojení k účtu Cosmos DB používá spravovanou identitu přiřazenou systémem přiřazenou instancí služby API Management. Identita musí být nakonfigurovaná pro přístup ke kontejneru Cosmos DB.

Použití partition-key pro požadavek zápisu se předává jako parametr dotazu a přistupuje k němu pomocí kontextové context.GraphQL.Arguments["id"] proměnné. Požadavek upsert má operaci předběžné aktivační události s názvem "validateInput". Tělo požadavku se mapuje pomocí šablony 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>

Vytvoření vstupu parametrů pro dotaz Cosmos DB

Následující příklady ukazují způsoby vytváření parametrizovaných dotazů Cosmos DB pomocí výrazů zásad. Zvolte metodu založenou na formě vstupu parametru.

Příklady jsou založené na následujícím ukázkovém schématu GraphQL a vygenerují odpovídající parametrizovaný dotaz Cosmos DB.

Příklad schématu GraphQL

input personInput {
  id: String!
  firstName: String
}

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

Příklad dotazu Cosmos DB

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

Předání objektu JSON (JObject) z výrazu

Ukázková zásada

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

Předání vstupního typu .NET (řetězec, int, decimal, bool) z výrazu

Ukázková zásada

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

Předání hodnoty JSON (JValue) z výrazu

Ukázková zásada

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

Překladače GraphQL

Další informace o práci se zásadami najdete v tématech:

Kurz: Transformace a ochrana rozhraní API
Referenční informace o zásadách pro úplný seznam prohlášení o zásadách a jejich nastavení
Výrazy zásad
Nastavení nebo úprava zásad
Opakované použití konfigurací zásad
Úložiště fragmentů zásad
Vytváření zásad pomocí Microsoft Copilotu pro Azure

Zdroj dat Cosmos DB pro překladač

Prohlášení o zásadách

Elementy

prvky connection-info

atributy připojovacího řetězce

atributy požadavku dotazu

Elementy požadavku dotazu

atributy parametru

stránkovací prvky

max-item-count – atribut

atribut pokračovací token

Elementy read-request

atributy delete-request

delete-request elements

atributy write-request

Elementy pro zápis-požadavek

elementy odpovědi

Atributy klíče oddílu

Atribut etag

Využití

Poznámky k využití

Konfigurace integrace spravované identity se službou Cosmos DB

Požadavky

Skript Azure CLI pro konfiguraci spravované identity

Příklady

Žádost o dotaz cosmos DB

Žádost o čtení ve službě Cosmos DB

Žádost o odstranění služby Cosmos DB

Požadavek na zápis do služby Cosmos DB

Vytvoření vstupu parametrů pro dotaz Cosmos DB

Předání objektu JSON (JObject) z výrazu

Předání vstupního typu .NET (řetězec, int, decimal, bool) z výrazu

Předání hodnoty JSON (JValue) z výrazu

Související zásady

Související obsah

Další materiály