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 , replace oder 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 , none oder 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
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 in Azure