Cosmos DB-Datenquelle für einen Auflöser

GILT FÜR: Entwickler | Basic | Basic v2 | Standard | Standard v2 | Premium

Die Resolverrichtlinie „cosmosdb-data-source“ löst Daten für einen Objekttyp und ein Feld in einem GraphQL Schema mithilfe einer Cosmos DB-Datenquelle auf. Das Schema muss als GraphQL-API in API Management importiert werden.

Verwenden Sie die Richtlinie, um eine einzelne Abfrageanforderung, eine Leseanforderung, eine Löschanforderung oder eine Schreibanforderung sowie eine optionale Antwort von der Cosmos DB-Datenquelle zu konfigurieren.

Hinweis

Diese Richtlinie befindet sich in der Vorschau. Derzeit wird die Richtlinie auf der Verbrauchsebene von API Management nicht unterstützt.

Hinweis

Legen Sie die Elemente und untergeordneten Elemente einer Richtlinie in der Reihenfolge fest, die in der Richtlinienanweisung angegeben ist. Erfahren Sie mehr darüber, wie Sie API Management-Richtlinien festlegen oder bearbeiten.

Richtlinienanweisung

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

Elemente

Name	BESCHREIBUNG	Erforderlich
connection-info	Gibt die Verbindung mit dem Container in der Cosmos DB-Datenbank an.	Ja
query-request	Gibt Einstellungen für eine Abfrageanforderung an den Cosmos DB-Container an.	Konfigurieren von „query-request“, „read-request“, „delete-request“oder „write-request“
read-request	Gibt Einstellungen für eine Leseanforderung an den Cosmos DB-Container an.	Konfigurieren von „query-request“, „read-request“, „delete-request“oder „write-request“
delete-request	Gibt Einstellungen für eine Löschanforderung an den Cosmos DB-Container an.	Konfigurieren von „query-request“, „read-request“, „delete-request“oder „write-request“
write-request	Gibt Einstellungen für eine Schreibanforderung an den Cosmos DB-Container an.	Konfigurieren von „query-request“, „read-request“, „delete-request“oder „write-request“
response	Gibt optional untergeordnete Richtlinien an, um die Antwort des Resolvers zu konfigurieren. Wenn Sie nichts anderes angegeben, wird die Antwort von Cosmos DB als JSON zurückgegeben.	Nein

connection-info-Elemente

Name	BESCHREIBUNG	Erforderlich
connection-string	Gibt die Verbindungszeichenfolge für das Cosmos DB-Konto an. Wenn eine von API Management verwaltete Identität konfiguriert ist, lassen Sie den Kontoschlüssel weg.	Ja
database-name	Zeichenfolge. Name der Cosmos DB-Datenbank.	Ja
container-name	Zeichenfolge. Name des Containers in der Cosmos DB-Datenbank.	Ja

Attribute von „connection-string“

attribute	BESCHREIBUNG	Erforderlich	Standard
use-managed-identity	Boolesch. Gibt an, ob die systemseitig zugewiesene verwaltete Identität der API Management-Instanz anstelle eines Kontoschlüssels in der Verbindungszeichenfolge für die Verbindung mit dem Cosmos DB-Konto verwendet werden soll. Die Identität muss für den Zugriff auf den Cosmos DB-Container konfiguriert werden.	Nein	false

Attribute von „query-request“

attribute	BESCHREIBUNG	Erforderlich	Standard
enable-low-precision-order-by	Boolesch. Gibt an, ob die Eigenschaft EnableLowPrecisionOrderBy der Abfrageanforderung im Cosmos DB-Dienst aktiviert werden soll.	Nein	–

Elemente von „query-request“

Name	BESCHREIBUNG	Erforderlich
sql-statement	Eine SQL-Anweisung für die Abfrageanforderung.	Nein
parameters	Eine Liste von Abfrageparametern in Unterelementen der Parameter für die Abfrageanforderung.	Nein
partition-key	Ein Cosmos DB-Partitionsschlüssel zum Weiterleiten der Abfrage an den Speicherort im Container.	Nein
paging	Gibt Einstellungen zum Aufteilen von Abfrageergebnissen auf mehrere Seiten an.	Nein

Parameterattribute

attribute	BESCHREIBUNG	Erforderlich	Standard
name	Eine Zeichenfolge. Name des Parameters in der @-Notation.	Ja	–

Pagingelemente

Name	BESCHREIBUNG	Erforderlich
max-item-count	Gibt die maximale Anzahl von Elementen an, die von der Abfrage zurückgegeben werden. Legen Sie diesen Wert auf „-1“ fest, wenn Sie keine Beschränkung für die Anzahl der Ergebnisse pro Abfrageausführung festlegen möchten.	Ja
continuation-token	Gibt das Fortsetzungstoken an, das an die Abfrage angefügt werden soll, um den nächsten Satz von Ergebnissen abzurufen.	Ja

Attribut „max-item-count“

attribute	BESCHREIBUNG	Erforderlich	Standard
Vorlage	Wird verwendet, um den Vorlagenmodus für „max-item-count“ festzulegen. Der einzige derzeit unterstützte Wert ist: - liquid – max-item-count verwendet die Liquid-Vorlagen-Engine.	Nein	–

Attribut „continuation-token“

attribute	BESCHREIBUNG	Erforderlich	Standard
Vorlage	Wird verwendet, um den Vorlagenmodus für das Fortsetzungstoken festzulegen. Der einzige derzeit unterstützte Wert ist: - liquid – das Fortsetzungstoken verwendet die Liquid-Vorlagen-Engine.	Nein	–

Elemente von „read-request“

Name	BESCHREIBUNG	Erforderlich
id	Bezeichner des Elements, das im Container gelesen werden soll.	Ja
Partitionsschlüssel	Ein Partitionsschlüssel für den Speicherort des Elements im Container. Wenn Sie „id“ angegeben, wird dadurch ein schnelles Punktlesen (Schlüssel-Wert-Suche) des Elements im Container aktiviert.	Nein

Attribute von „delete-request“

attribute	BESCHREIBUNG	Erforderlich	Standard
consistency-level	Zeichenfolge. Legt die Cosmos DB-Konsistenzebene der Löschanforderung fest.	Nein	–
pre-trigger	Eine Zeichenfolge. Bezeichner einer Pre-Trigger-Funktion, die in Ihrem Cosmos DB-Container registriert ist.	Nein	–
post-trigger	Eine Zeichenfolge. Bezeichner einer Post-Trigger-Funktion, die in Ihrem Cosmos DB-Container registriert ist.	Nein	–

Elemente von „delete-request“

Name	BESCHREIBUNG	Erforderlich
id	Bezeichner des Elements, das im Container gelöscht werden soll.	Ja
Partitionsschlüssel	Ein Partitionsschlüssel für den Speicherort des Elements im Container.	Nein
etag	Entitätstag für das Element im Container, das für die Steuerung der optimistischen Nebenläufigkeit verwendet wird.	Nein

Attribute von „write-request“

attribute	BESCHREIBUNG	Erforderlich	Standard
type	Der Typ der Schreibanforderung: insert, replaceoder upsert.	Nein	upsert
consistency-level	Eine Zeichenfolge. Legt die Cosmos DB-Konsistenzebene der Schreibanforderung fest.	Nein	–
indexing-directive	Die Indizierungsrichtlinie, die bestimmt, wie die Elemente des Containers indiziert werden sollen.	Nein	default
pre-trigger	Eine Zeichenfolge. Bezeichner einer Pre-Trigger-Funktion, die in Ihrem Cosmos DB-Container registriert ist.	Nein	–
post-trigger	Eine Zeichenfolge. Bezeichner einer Post-Trigger-Funktion, die in Ihrem Cosmos DB-Container registriert ist.	Nein	–

Elemente von „write-request“

Name	BESCHREIBUNG	Erforderlich
id	Bezeichner des Elements im Container.	Ja, wenn „type“ „replace“ entspricht.
etag	Entitätstag für das Element im Container, das für die Steuerung der optimistischen Nebenläufigkeit verwendet wird.	Nein
set-body	Legt den Text in der Schreibanforderung fest. Wenn Sie keinen angeben, wird die Nutzlast der Anforderung Argumente im JSON-Format zuordnen.	Nein

Elemente von „response“

Name	BESCHREIBUNG	Erforderlich
set-body	Legt den Text in der Antwort des Auflösers fest. Wenn Sie keinen angeben und der zurückgegebene JSON-Code Feldnamen enthält, werden die im GraphQL-Schema übereinstimmenden Felder automatisch zugeordnet.	Nein
publish-event	Veröffentlicht ein Ereignis für ein oder mehrere Abonnements, die im GraphQL-API-Schema angegeben sind.	Nein

Attribute von „partition-key“

attribute	BESCHREIBUNG	Erforderlich	Standard
data-type	Der Datentyp des Partitionsschlüssels: string, number, bool, noneoder null.	Nein	string
Vorlage	Wird verwendet, um den Vorlagenmodus für den Partitionsschlüssel festzulegen. Der einzige derzeit unterstützte Wert ist: - liquid – Der Partitionsschlüssel verwendet die Liquid-Vorlagen-Engine.	Nein	–

Attribut „etag“

attribute	BESCHREIBUNG	Erforderlich	Standard
type	Eine Zeichenfolge. Einer der folgenden Werte: - match – Der Wert von „etag“ muss mit dem vom System generierten Entitätstag für das Element übereinstimmen. - no-match – Der Wert von „etag“ muss nicht mit dem vom System generierten Entitätstag für das Element übereinstimmen.	Nein	match
Vorlage	Wird verwendet, um den Vorlagenmodus für das „etag“ festzulegen. Der einzige derzeit unterstützte Wert ist: - liquid – Das „etag“ verwendet die Liquid-Vorlagen-Engine.	Nein	–

Verwendung

• Richtlinienbereiche: GraphQL-Auflöser
• Gateways: klassisch, v2

Hinweise zur Verwendung

• Informationen zum Konfigurieren und Verwalten eines Resolvers mit dieser Richtlinie finden Sie unter Konfigurieren eines GraphQL-Resolvers.
• Diese Richtlinie wird nur aufgerufen, wenn ein einzelnes Feld in einem übereinstimmenden Vorgangstyp im Schema aufgelöst wird.

Konfigurieren der Integration verwalteter Identitäten mit Cosmos DB

Sie können eine durch API Management systemseitig zugewiesene verwaltete Identität für den Zugriff auf ein Cosmos DB-Konto konfigurieren, anstatt einen Kontoschlüssel in der Verbindungszeichenfolge bereitzustellen.

Führen Sie die folgenden Schritte aus, um die verwaltete Identität mithilfe von Azure CLI zu konfigurieren.

Voraussetzungen

• Aktivieren Sie eine systemseitig zugewiesene verwaltete Identität in Ihrer API Management-Instanz. Notieren Sie sich im Portal die Objekt-ID (Prinzipal) der verwalteten Identität.

• • Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.

    

  • Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.

    • Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.

    • Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.

    • Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.

Azure CLI-Skript zum Konfigurieren der verwalteten Identität

# 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    

Beispiele

Cosmos DB-Abfrageanforderung

Im folgenden Beispiel wird eine GraphQL-Abfrage mithilfe einer SQL-Abfrage in einen Cosmos DB-Container aufgelöst.

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

Im folgenden Beispiel wird eine GraphQL-Abfrage mithilfe einer Punktleseanforderung in einen Cosmos DB-Container aufgelöst. Die Verbindung mit dem Cosmos DB-Konto verwendet die systemseitig zugewiesene verwaltete Identität der API Management-Instanz. Die Identität muss für den Zugriff auf den Cosmos DB-Container konfiguriert werden.

Die für die Leseanforderung verwendeten „id“ und „partition-key“ werden als Abfrageparameter übergeben und mithilfe der Kontextvariablen „context.GraphQL.Arguments["id"]“ aufgerufen.

<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-Löschanforderung

Im folgenden Beispiel wird eine GraphQL-Mutation durch eine Löschanforderung an einen Cosmos DB-Container aufgelöst. Die für die Löschanforderung verwendeten „id“ und „partition-key“ werden als Abfrageparameter übergeben und mithilfe der Kontextvariablen „context.GraphQL.Arguments["id"]“ aufgerufen.

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

Im folgenden Beispiel wird eine GraphQL-Mutation durch eine Upsert-Anforderung an einen Cosmos DB-Container aufgelöst. Die Verbindung mit dem Cosmos DB-Konto verwendet die systemseitig zugewiesene verwaltete Identität der API Management-Instanz. Die Identität muss für den Zugriff auf den Cosmos DB-Container konfiguriert werden.

Die für die Schreibanforderung verwendete „partition-key“ wird als Abfrageparameter übergeben, und der Zugriff erfolgt über die Kontextvariable „context.GraphQL.Arguments["id"]“ aufgerufen. Die Upsert-Anforderung verfügt über einen Pre-Triggervorgang namens „validateInput“. Der Anforderungstext wird mithilfe einer Liquid-Vorlage zugeordnet.

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

Erstellen von Parametereingaben für eine Cosmos DB-Abfrage

Die folgenden Beispiele zeigen Möglichkeiten zum Erstellen parametrisierter Cosmos DB-Abfragen mithilfe von Richtlinienausdrücken. Wählen Sie basierend auf der Form Ihrer Parametereingabe eine Methode aus.

Die Beispiele basieren auf dem folgenden beispielhaften GraphQL-Schema und generieren die entsprechende parametrisierte Cosmos DB-Abfrage.

GraphQL-Beispielschema

input personInput {
  id: String!
  firstName: String
}

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

Cosmos DB-Beispielabfrage

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

Übergeben des JSON-Objekts (JObject) aus dem Ausdruck

Beispielrichtlinie

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

Übergeben des .NET-Eingabetyps (String, Integer, Dezimal, Bool) aus dem Ausdruck

Beispielrichtlinie

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

Übergeben des JSON-Werts (JValue) aus dem Ausdruck

Beispielrichtlinie

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

Verwandte Richtlinien

• GraphQL-Resolver

Zugehöriger Inhalt

Weitere Informationen zum Arbeiten mit Richtlinien finden Sie hier:

• Tutorial: Transformieren und Schützen Ihrer API
• Unter Richtlinien für die API-Verwaltung finden Sie eine komplette Liste der Richtlinienanweisungen und der zugehörigen Einstellungen.
• Richtlinienausdrücke
• Festlegen oder Bearbeiten von Richtlinien
• Wiederverwenden von Richtlinienkonfigurationen
• Repository für Richtliniencodeausschnitte
• Erstellen von Richtlinien mit Microsoft Copilot für Azure