Cosmos DB-Datenquelle für einen Auflöser

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

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.

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

connection-info-Elemente

Attribute von „connection-string“

Attribute von „query-request“

Elemente von „query-request“

Parameterattribute

Pagingelemente

Attribut „max-item-count“

Attribut „continuation-token“

Elemente von „read-request“

Attribute von „delete-request“

Elemente von „delete-request“

Attribute von „write-request“

Elemente von „write-request“

Elemente von „response“

Attribute von „partition-key“

Attribut „etag“

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
• Azure API Management-Richtlinientoolkit
• Erstellen von Richtlinien mit Microsoft Copilot in Azure