Freigeben über


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

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

Weitere Informationen zum Arbeiten mit Richtlinien finden Sie hier: