Źródło danych usługi Cosmos DB dla narzędzia rozpoznawania nazw

DOTYCZY: Developer | Podstawowa | Podstawowa wersja 2 | Standardowa | Standardowa, wersja 2 | Premium

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-requestelementów , read-request, delete-requestlub write-request
żądanie odczytu Określa ustawienia dla żądania odczytu do kontenera usługi Cosmos DB. Konfigurowanie jednego z query-requestelementów , read-request, delete-requestlub write-request
żądanie usunięcia Określa ustawienia żądania usunięcia do kontenera usługi Cosmos DB. Konfigurowanie jednego z query-requestelementów , read-request, delete-requestlub write-request
żądanie zapisu Określa ustawienia żądania zapisu w kontenerze usługi Cosmos DB. Konfigurowanie jednego z query-requestelementów , read-request, delete-requestlub write-request
Odpowiedzi 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 Ciąg. Nazwa bazy danych usługi Cosmos DB. Tak
nazwa_kontenera Ciąg. 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.
Stronicowania Określa ustawienia podziału wyników zapytania na wiele stron. Nie.

atrybuty parametrów

Atrybut opis Wymagani Wartość domyślna
name Ciąg. 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:

- liquidmax-item-count- będzie używać 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 będzie 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 Ciąg. Ustawia poziom spójności usługi Cosmos DB żądania usuwania. Nie. Nie dotyczy
wyzwalacz wstępny Ciąg. Identyfikator funkcji wyzwalacza wstępnego zarejestrowanej w kontenerze usługi Cosmos DB. Nie. Nie dotyczy
wyzwalacz po wyzwoleniu Ciąg. 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, replacelub upsert. Nie. upsert
poziom spójności Ciąg. 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 Ciąg. Identyfikator funkcji wyzwalacza wstępnego zarejestrowanej w kontenerze usługi Cosmos DB. Nie. Nie dotyczy
wyzwalacz po wyzwoleniu Ciąg. 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 podany, ładunek żądania zamapuje 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, , numberbool, nonelub 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 będzie używać aparatu do tworzenia szablonów cieczy
Nie. Nie dotyczy

Atrybut etag

Atrybut opis Wymagani Wartość domyślna
type Ciąg. 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 będzie używać silnika do tworzenia szablonów cieczy
Nie. Nie dotyczy

Użycie

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

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

Aby uzyskać więcej informacji na temat pracy z zasadami, zobacz: