Источник данных Cosmos DB для сопоставителя

ОБЛАСТЬ ПРИМЕНЕНИЯ: Разработчик | Базовый | Базовая версия 2 | Стандартный | Standard v2 | Премиум | Премиум версии 2

Политика cosmosdb-data-source сопоставителя разрешает данные для типа объекта и поля в схеме GraphQL с помощью источника данных Cosmos DB . Схема должна быть импортирована в Управление API как API GraphQL.

Используйте политику для настройки одного запроса, запроса на чтение, удаление или запись запроса и необязательный ответ из источника данных Cosmos DB.

Правило политики

<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> 

Элементы

Элементы сведений о подключении

Атрибуты строки подключения

Атрибуты запроса-запроса

Элементы запроса-запроса

Атрибуты параметра

элементы разбиения по страницам

Атрибут max-item-count

Атрибут токена продолжения

Элементы read-request

Атрибуты delete-request

Элементы delete-request

Атрибуты запросов на запись

Элементы запроса на запись

Элементы ответа

Атрибуты ключа секции

Атрибут etag

Использование

• Области политики: сопоставитель GraphQL
• Шлюзы: классическая, версия 2

Примечания об использовании

• Сведения о настройке сопоставителя и управлении ими с помощью этой политики см. в разделе "Настройка сопоставителя GraphQL".
• Эта политика вызывается только при разрешении одного поля в типе операции сопоставления в схеме.

Настройка интеграции управляемых удостоверений с Cosmos DB

Управляемое удостоверение, назначаемое системой, можно настроить Управление API для доступа к учетной записи Cosmos DB вместо предоставления ключа учетной записи в строка подключения.

Выполните следующие действия, чтобы использовать Azure CLI для настройки управляемого удостоверения.

Необходимые компоненты

• Включите назначаемое системой управляемое удостоверение в экземпляре управления API. На портале обратите внимание на идентификатор объекта (субъекта) управляемого удостоверения.

• • Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см. в статье "Начало работы с Azure Cloud Shell".

    

  • Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.

    • Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других параметрах входа см. в статье "Проверка подлинности в Azure с помощью Azure CLI".

    • Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений и управление ими с помощью Azure CLI.

    • Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

Скрипт Azure CLI для настройки управляемого удостоверения

# 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    

Примеры

Запрос запроса Cosmos DB

В следующем примере выполняется разрешение запроса GraphQL с помощью SQL-запроса к контейнеру 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>

Запрос на чтение Cosmos DB

В следующем примере выполняется разрешение запроса GraphQL с помощью запроса на чтение точек в контейнер Cosmos DB. Подключение к учетной записи Cosmos DB использует управляемое удостоверение, назначаемое системой Управление API экземпляра. Удостоверение должно быть настроено для доступа к контейнеру Cosmos DB.

id Запрос partition-key на чтение передается в качестве параметров запроса и обращается к ней с помощью контекстной переменной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>

Запрос на удаление Cosmos DB

В следующем примере устранена мутация GraphQL путем запроса на удаление контейнера Cosmos DB. Запрос id удаления передается в partition-key качестве параметров запроса и обращается к ней с помощью контекстной переменной 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>

Запрос на запись Cosmos DB

В следующем примере устранена мутация GraphQL путем запроса upsert к контейнеру Cosmos DB. Подключение к учетной записи Cosmos DB использует управляемое удостоверение, назначаемое системой Управление API экземпляра. Удостоверение должно быть настроено для доступа к контейнеру Cosmos DB.

Используемый partition-key для запроса записи передается в качестве параметра запроса и обращается к ней с помощью контекстной переменной context.GraphQL.Arguments["id"] . Запрос upsert имеет операцию предварительного триггера с именем validateInput. Текст запроса сопоставляется с помощью шаблона 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>

Создание входных данных параметров для запроса Cosmos DB

В следующих примерах показаны способы создания параметризованных запросов Cosmos DB с помощью выражений политики. Выберите метод на основе формы входных данных параметра.

Примеры основаны на приведенной ниже схеме GraphQL и создают соответствующий параметризованный запрос Cosmos DB.

Пример схемы GraphQL

input personInput {
  id: String!
  firstName: String
}

type Query {
  personsStringParam(stringInput: String): personsConnection
  personsPersonParam(input: personInput): personsConnection
}

Пример запроса Cosmos DB

{
    "query": "query { 
        personsPersonParam(input: { id: \"3\" } { 
        items { id firstName lastName } 
        } 
    }"
}    

Передача объекта JSON (JObject) из выражения

Пример политики

[...]
<query-request>
    <sql-statement>SELECT * FROM c where c.familyId [email protected]</sql-statement>
    <parameters>
        <parameter name="@param">@(context.GraphQL.Arguments["input"])</parameter>
    </parameters>
    </query-request>
[...]

Передача входного типа .NET (строка, int, десятичная, логическое значение) из выражения

Пример политики

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

Передача значения JSON (JValue) из выражения

Пример политики

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

Связанные политики

• Сопоставители GraphQL

Связанный контент

Дополнительные сведения о работе с политиками см. в нижеуказанных статьях.

• Руководство. Преобразование и защита API
• Полный перечень операторов политик и их параметров см. в справочнике по политикам.
• Выражения политики
• Настройка или изменение политик
• Повторное использование конфигураций политик
• Репозиторий фрагментов политик
• Репозиторий игровой площадки политики
• Набор средств политики Управление API Azure
• Получите помощь Copilot для создания, объяснения и устранения неполадок в политике