Źródło danych usługi Cosmos DB dla narzędzia rozpoznawania nazw
DOTYCZY: Developer | Podstawowa | Podstawowa wersja 2 | Standardowa | Standardowa, wersja 2 | Premium | Premium, wersja 2
Zasady rozpoznawania cosmosdb-data-source
rozpoznawania rozpoznają dane dla typu obiektu i pola w schemacie GraphQL przy użyciu źródła danych usługi Cosmos DB . Schemat należy zaimportować do usługi API Management jako interfejs API GraphQL.
Użyj zasad, aby skonfigurować pojedyncze żądanie zapytania, żądanie odczytu, żądanie usunięcia lub żądanie zapisu oraz opcjonalną odpowiedź ze źródła danych usługi Cosmos DB.
Uwaga
Te zasady są w wersji zapoznawczej. Obecnie zasady nie są obsługiwane w warstwie Zużycie usługi API Management.
Uwaga
Ustaw elementy zasad i elementy podrzędne w kolejności podanej w instrukcji zasad. Dowiedz się więcej na temat ustawiania lub edytowania zasad usługi API Management.
Instrukcja zasad
<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
Nazwa/nazwisko | opis | Wymagania |
---|---|---|
connection-info | Określa połączenie z kontenerem w bazie danych Cosmos DB. | Tak |
żądanie zapytania | Określa ustawienia dla żądania zapytania do kontenera usługi Cosmos DB. | Konfigurowanie jednego z query-request elementów , read-request , delete-request lub write-request |
żądanie odczytu | Określa ustawienia dla żądania odczytu do kontenera usługi Cosmos DB. | Konfigurowanie jednego z query-request elementów , read-request , delete-request lub write-request |
żądanie usunięcia | Określa ustawienia żądania usunięcia do kontenera usługi Cosmos DB. | Konfigurowanie jednego z query-request elementów , read-request , delete-request lub write-request |
żądanie zapisu | Określa ustawienia żądania zapisu w kontenerze usługi Cosmos DB. | Konfigurowanie jednego z query-request elementów , read-request , delete-request lub write-request |
odpowiedź | Opcjonalnie określa zasady podrzędne, aby skonfigurować odpowiedź narzędzia rozpoznawania. Jeśli nie zostanie określona, odpowiedź zostanie zwrócona z usługi Cosmos DB jako kod JSON. | Nie. |
Elementy informacji o połączeniu
Nazwa/nazwisko | opis | Wymagania |
---|---|---|
connection-string | Określa parametry połączenia dla konta usługi Cosmos DB. Jeśli skonfigurowano tożsamość zarządzaną usługi API Management, pomiń klucz konta. | Tak |
nazwa bazy danych | Struna. Nazwa bazy danych usługi Cosmos DB. | Tak |
nazwa_kontenera | Struna. Nazwa kontenera w bazie danych usługi Cosmos DB. | Tak |
atrybuty parametrów połączenia
Atrybut | opis | Wymagani | Wartość domyślna |
---|---|---|---|
use-managed-identity | Wartość logiczna. Określa, czy używać przypisanej przez system tożsamości zarządzanej wystąpienia usługi API Management do połączenia z kontem usługi Cosmos DB zamiast klucza konta w parametry połączenia. Tożsamość musi być skonfigurowana w celu uzyskania dostępu do kontenera usługi Cosmos DB. | Nie. | false |
atrybuty żądania zapytania
Atrybut | opis | Wymagani | Wartość domyślna |
---|---|---|---|
enable-low-precision-order-by | Wartość logiczna. Określa, czy włączyć właściwość żądania kwerendy EnableLowPrecisionOrderBy w usłudze Cosmos DB. | Nie. | Nie dotyczy |
Elementy żądania zapytania
Nazwa/nazwisko | opis | Wymagania |
---|---|---|
sql-statement | Instrukcja SQL dla żądania zapytania. | Nie. |
parameters | Lista parametrów zapytania w podelementach parametrów dla żądania zapytania. | Nie. |
klucz partycji | Klucz partycji usługi Cosmos DB do kierowania zapytania do lokalizacji w kontenerze. | Nie. |
stronicowanie | Określa ustawienia podziału wyników zapytania na wiele stron. | Nie. |
atrybuty parametrów
Atrybut | opis | Wymagani | Wartość domyślna |
---|---|---|---|
name | Struna. Nazwa parametru w notacji @. | Tak | Nie dotyczy |
stronicowanie elementów
Nazwa/nazwisko | opis | Wymagania |
---|---|---|
max-item-count | Określa maksymalną liczbę elementów zwracanych przez zapytanie. Ustaw wartość -1, jeśli nie chcesz umieszczać limitu liczby wyników na wykonanie zapytania. | Tak |
token kontynuacji | Określa token kontynuacji, który ma zostać dołączony do zapytania, aby uzyskać następny zestaw wyników. | Tak |
atrybut max-item-count
Atrybut | opis | Wymagani | Wartość domyślna |
---|---|---|---|
sieci Web | Służy do ustawiania trybu tworzenia szablonów dla elementu max-item-count . Obecnie jedyną obsługiwaną wartością jest:- liquid - używa max-item-count silnika do tworzenia szablonów cieczy. |
Nie. | Nie dotyczy |
atrybut tokenu kontynuacji
Atrybut | opis | Wymagani | Wartość domyślna |
---|---|---|---|
sieci Web | Służy do ustawiania trybu tworzenia szablonów dla tokenu kontynuacji. Obecnie jedyną obsługiwaną wartością jest: - liquid - token kontynuacji używa aparatu do tworzenia szablonów cieczy. |
Nie. | Nie dotyczy |
Elementy żądania odczytu
Nazwa/nazwisko | opis | Wymagania |
---|---|---|
identyfikator | Identyfikator elementu do odczytania w kontenerze. | Tak |
klucz partycji | Klucz partycji lokalizacji elementu w kontenerze. Jeśli określono parametr z parametrem id , włącza szybki odczyt punktu (wyszukiwanie klucza/wartości) elementu w kontenerze. |
Nie. |
atrybuty żądania usuwania
Atrybut | opis | Wymagani | Wartość domyślna |
---|---|---|---|
poziom spójności | Struna. Ustawia poziom spójności usługi Cosmos DB żądania usuwania. | Nie. | Nie dotyczy |
wyzwalacz wstępny | Struna. Identyfikator funkcji wyzwalacza wstępnego zarejestrowanej w kontenerze usługi Cosmos DB. | Nie. | Nie dotyczy |
wyzwalacz po wyzwoleniu | Struna. Identyfikator funkcji po wyzwoleniu zarejestrowanej w kontenerze usługi Cosmos DB. | Nie. | Nie dotyczy |
Elementy żądania usuwania
Nazwa/nazwisko | opis | Wymagania |
---|---|---|
identyfikator | Identyfikator elementu do usunięcia w kontenerze. | Tak |
klucz partycji | Klucz partycji lokalizacji elementu w kontenerze. | Nie. |
etag | Tag jednostki dla elementu w kontenerze używany do optymistycznej kontroli współbieżności. | Nie. |
atrybuty żądania zapisu
Atrybut | opis | Wymagani | Wartość domyślna |
---|---|---|---|
type | Typ żądania zapisu: insert , replace lub upsert . |
Nie. | upsert |
poziom spójności | Struna. Ustawia poziom spójności usługi Cosmos DB żądania zapisu. | Nie. | Nie dotyczy |
dyrektywa indeksowania | Zasady indeksowania określające sposób indeksowania elementów kontenera. | Nie. | default |
wyzwalacz wstępny | Struna. Identyfikator funkcji wyzwalacza wstępnego zarejestrowanej w kontenerze usługi Cosmos DB. | Nie. | Nie dotyczy |
wyzwalacz po wyzwoleniu | Struna. Identyfikator funkcji po wyzwoleniu zarejestrowanej w kontenerze usługi Cosmos DB. | Nie. | Nie dotyczy |
Elementy żądania zapisu
Nazwa/nazwisko | opis | Wymagania |
---|---|---|
identyfikator | Identyfikator elementu w kontenerze. | Tak, gdy type ma wartość replace . |
etag | Tag jednostki dla elementu w kontenerze używany do optymistycznej kontroli współbieżności. | Nie. |
set-body | Ustawia treść w żądaniu zapisu. Jeśli nie zostanie podana, ładunek żądania mapuje argumenty na format JSON. | Nie. |
elementy odpowiedzi
Nazwa/nazwisko | opis | Wymagania |
---|---|---|
set-body | Ustawia treść w odpowiedzi narzędzia rozpoznawania. Jeśli nie podano wartości i zwrócony kod JSON zawiera nazwy pól pasujących do pól w schemacie GraphQL, pola są automatycznie mapowane. | Nie. |
zdarzenie publikowania | Publikuje zdarzenie w co najmniej jednej subskrypcji określonej w schemacie interfejsu API GraphQL. | Nie. |
atrybuty klucza partycji
Atrybut | opis | Wymagani | Wartość domyślna |
---|---|---|---|
typ danych | Typ danych klucza partycji: string , , number bool , none lub null . |
Nie. | string |
sieci Web | Służy do ustawiania trybu tworzenia szablonów dla klucza partycji. Obecnie jedyną obsługiwaną wartością jest: - liquid - klucz partycji używa aparatu do tworzenia szablonów cieczy |
Nie. | Nie dotyczy |
Atrybut etag
Atrybut | opis | Wymagani | Wartość domyślna |
---|---|---|---|
type | Struna. Jedna z następujących wartości: - match — wartość musi być zgodna etag z tagiem jednostki wygenerowanej przez system dla elementu- no-match — wartość nie jest wymagana etag do dopasowania tagu jednostki wygenerowanej przez system dla elementu |
Nie. | match |
sieci Web | Służy do ustawiania trybu tworzenia szablonów dla elementu etag. Obecnie jedyną obsługiwaną wartością jest: - liquid - etag używa aparatu do tworzenia szablonów cieczy |
Nie. | Nie dotyczy |
Użycie
- Zakresy zasad: program GraphQL resolver
- Bramy: klasyczne, wersja 2
Uwagi dotyczące użycia
- Aby skonfigurować program rozpoznawania nazw i zarządzać nim za pomocą tych zasad, zobacz Konfigurowanie narzędzia rozpoznawania języka GraphQL.
- Te zasady są wywoływane tylko w przypadku rozpoznawania pojedynczego pola w pasującym typie operacji w schemacie.
Konfigurowanie integracji tożsamości zarządzanej z usługą Cosmos DB
Tożsamość zarządzaną przypisaną przez system usługi API Management można skonfigurować w celu uzyskania dostępu do konta usługi Cosmos DB zamiast podawania klucza konta w parametry połączenia.
Wykonaj następujące kroki, aby skonfigurować tożsamość zarządzaną przy użyciu interfejsu wiersza polecenia platformy Azure.
Wymagania wstępne
Włącz tożsamość zarządzaną przypisaną przez system w wystąpieniu usługi API Management. W portalu zanotuj identyfikator obiektu (podmiot zabezpieczeń) tożsamości zarządzanej.
-
Użyj środowiska powłoki Bash w usłudze Azure Cloud Shell. Aby uzyskać więcej informacji, zobacz Szybki start dotyczący powłoki Bash w usłudze Azure Cloud Shell.
Jeśli wolisz uruchamiać polecenia referencyjne interfejsu wiersza polecenia lokalnie, zainstaluj interfejs wiersza polecenia platformy Azure. Jeśli korzystasz z systemu Windows lub macOS, rozważ uruchomienie interfejsu wiersza polecenia platformy Azure w kontenerze Docker. Aby uzyskać więcej informacji, zobacz Jak uruchomić interfejs wiersza polecenia platformy Azure w kontenerze platformy Docker.
Jeśli korzystasz z instalacji lokalnej, zaloguj się do interfejsu wiersza polecenia platformy Azure za pomocą polecenia az login. Aby ukończyć proces uwierzytelniania, wykonaj kroki wyświetlane w terminalu. Aby uzyskać inne opcje logowania, zobacz Logowanie się przy użyciu interfejsu wiersza polecenia platformy Azure.
Po wyświetleniu monitu zainstaluj rozszerzenie interfejsu wiersza polecenia platformy Azure podczas pierwszego użycia. Aby uzyskać więcej informacji na temat rozszerzeń, zobacz Korzystanie z rozszerzeń w interfejsie wiersza polecenia platformy Azure.
Uruchom polecenie az version, aby znaleźć zainstalowane wersje i biblioteki zależne. Aby uaktualnić do najnowszej wersji, uruchom polecenie az upgrade.
Skrypt interfejsu wiersza polecenia platformy Azure do konfigurowania tożsamości zarządzanej
# 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
Przykłady
Żądanie zapytania usługi Cosmos DB
Poniższy przykład rozwiązuje zapytanie GraphQL przy użyciu zapytania SQL do kontenera usługi 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>
Żądanie odczytu usługi Cosmos DB
Poniższy przykład rozwiązuje zapytanie GraphQL przy użyciu żądania odczytu punktu do kontenera usługi Cosmos DB. Połączenie z kontem usługi Cosmos DB używa przypisanej przez system tożsamości zarządzanej wystąpienia usługi API Management. Tożsamość musi być skonfigurowana w celu uzyskania dostępu do kontenera usługi Cosmos DB.
Wartości id
i partition-key
używane dla żądania odczytu są przekazywane jako parametry zapytania i uzyskiwane do niej dostęp przy użyciu zmiennej kontekstowej context.GraphQL.Arguments["id"]
.
<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>
Żądanie usunięcia usługi Cosmos DB
Poniższy przykład rozwiązuje mutację GraphQL przez żądanie usunięcia do kontenera usługi Cosmos DB. Element id
i partition-key
używany do żądania usuwania jest przekazywany jako parametry zapytania i uzyskiwany do niej dostęp przy użyciu zmiennej kontekstowej context.GraphQL.Arguments["id"]
.
<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>
Żądanie zapisu usługi Cosmos DB
Poniższy przykład rozwiązuje mutację GraphQL przez żądanie upsert do kontenera usługi Cosmos DB. Połączenie z kontem usługi Cosmos DB używa przypisanej przez system tożsamości zarządzanej wystąpienia usługi API Management. Tożsamość musi być skonfigurowana w celu uzyskania dostępu do kontenera usługi Cosmos DB.
Używany partition-key
dla żądania zapisu jest przekazywany jako parametr zapytania i uzyskiwany do niej dostęp przy użyciu zmiennej kontekstowej context.GraphQL.Arguments["id"]
. Żądanie upsert ma operację wyzwalacza wstępnego o nazwie "validateInput". Treść żądania jest mapowana przy użyciu szablonu 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>
Konstruowanie danych wejściowych parametrów dla zapytania usługi Cosmos DB
W poniższych przykładach pokazano sposoby konstruowania sparametryzowanych zapytań usługi Cosmos DB przy użyciu wyrażeń zasad. Wybierz metodę na podstawie formularza danych wejściowych parametru.
Przykłady są oparte na poniższym przykładowym schemacie GraphQL i generują odpowiednie zapytanie sparametryzowane usługi Cosmos DB.
Przykładowy schemat GraphQL
input personInput {
id: String!
firstName: String
}
type Query {
personsStringParam(stringInput: String): personsConnection
personsPersonParam(input: personInput): personsConnection
}
Przykładowe zapytanie usługi Cosmos DB
{
"query": "query {
personsPersonParam(input: { id: \"3\" } {
items { id firstName lastName }
}
}"
}
Przekazywanie obiektu JSON (JObject) z wyrażenia
Przykładowe zasady
[...]
<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>
[...]
Przekazywanie typu danych wejściowych platformy .NET (ciąg, int, dziesiętny, bool) z wyrażenia
Przykładowe zasady
[...]
<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>
[...]
Przekazywanie wartości JSON (JValue) z wyrażenia
Przykładowe zasady
[...]
<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>
[...]
Powiązane zasady
Powiązana zawartość
Aby uzyskać więcej informacji na temat pracy z zasadami, zobacz:
- Samouczek: przekształcanie i ochrona interfejsu API
- Dokumentacja zasad dla pełnej listy instrukcji zasad i ich ustawień
- Wyrażenia zasad
- Ustawianie lub edytowanie zasad
- Ponowne używanie konfiguracji zasad
- Repozytorium fragmentów zasad
- Tworzenie zasad przy użyciu rozwiązania Microsoft Copilot na platformie Azure