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

Статья
03/18/2024

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

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

Примечание.

Эта политика доступна в предварительной версии. В настоящее время политика не поддерживается на уровне потребления Управление API.

Примечание.

Задайте элементы политики и дочерние элементы в порядке, указанном в правиле политики. Узнайте, как устанавливать или изменять политики службы управления API.

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

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

Элементы

Имя	Описание	Обязательное поле
connection-info	Указывает подключение к контейнеру в базе данных Cosmos DB.	Да
запрос-запрос	Задает параметры для запроса к контейнеру Cosmos DB.	Настройка одного из `query-request`, `read-requestdelete-request`или`write-request`
read-request	Задает параметры для запроса чтения в контейнер Cosmos DB.	Настройка одного из `query-request`, `read-requestdelete-request`или`write-request`
delete-request	Задает параметры для запроса на удаление контейнера Cosmos DB.	Настройка одного из `query-request`, `read-requestdelete-request`или`write-request`
запрос на запись	Задает параметры для запроса на запись в контейнер Cosmos DB.	Настройка одного из `query-request`, `read-requestdelete-request`или`write-request`
response	При необходимости указывает дочерние политики для настройки ответа сопоставителя. Если это не указано, ответ возвращается из Cosmos DB в формате JSON.	No

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

Имя	Описание	Обязательное поле
connection-string	Указывает строка подключения для учетной записи Cosmos DB. Если настроено Управление API управляемое удостоверение, опустите ключ учетной записи.	Да
database-name	Строка. Имя базы данных Cosmos DB.	Да
имя_контейнера	Строка. Имя контейнера в базе данных Cosmos DB.	Да

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

Атрибут	Description	Обязательное поле	По умолчанию.
use-managed-identity	Логическое значение. Указывает, следует ли использовать управляемое удостоверение, назначаемое системой Управление API, для подключения к учетной записи Cosmos DB вместо ключа учетной записи в строка подключения. Удостоверение должно быть настроено для доступа к контейнеру Cosmos DB.	No	`false`

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

Атрибут	Description	Обязательное поле	По умолчанию.
enable-low-precision-order-by	Логическое значение. Указывает, следует ли включить свойство запроса EnableLowPrecisionOrderBy в службе Cosmos DB.	No	Н/П

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

Имя	Описание	Обязательное поле
инструкция sql-	Инструкция SQL для запроса.	No
parameters	Список параметров запроса в подэлементах параметров для запроса.	No
ключ секции	Ключ секции Cosmos DB для маршрутизации запроса в расположение в контейнере.	No
paging	Задает параметры для разделения результатов запроса на несколько страниц.	No

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

Атрибут	Description	Обязательное поле	По умолчанию.
name	Строка. Имя параметра в нотации @.	Да	Н/П

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

Имя	Описание	Обязательное поле
max-item-count	Указывает максимальное количество элементов , возвращаемых запросом. Установите значение -1, если вы не хотите поместить ограничение на количество результатов для каждого выполнения запроса.	Да
токен продолжения	Указывает маркер продолжения для подключения к запросу, чтобы получить следующий набор результатов.	Да

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

Атрибут	Description	Обязательное поле	По умолчанию.
JSON	Используется для задания режима шаблонов.`max-item-count` В настоящее время поддерживается только одно значение: - `liquidmax-item-count`— будет использоваться модуль ликвидного шаблонирования.	No	Н/П

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

Атрибут	Description	Обязательное поле	По умолчанию.
JSON	Используется для задания режима шаблонов для маркера продолжения. В настоящее время поддерживается только одно значение: - `liquid` — маркер продолжения будет использовать обработчик шаблонов жидкости.	No	Н/П

Элементы read-request

Имя	Описание	Обязательное поле
id	Идентификатор элемента для чтения в контейнере.	Да
ключ секции	Ключ секции для расположения элемента в контейнере. Если указано с `id`помощью, включает быстрый считывания (поиск ключа или значения) элемента в контейнере.	No

Атрибуты delete-request

Атрибут	Description	Обязательное поле	По умолчанию.
Уровень согласованности	Строка. Задает уровень согласованности Cosmos DB запроса на удаление.	No	Н/П
предварительная активация	Строка. Идентификатор функции предварительного триггера, зарегистрированной в контейнере Cosmos DB.	No	Н/П
после триггера	Строка. Идентификатор функции после триггера, зарегистрированной в контейнере Cosmos DB.	No	Н/П

Элементы delete-request

Имя	Описание	Обязательное поле
id	Идентификатор элемента, который нужно удалить в контейнере.	Да
ключ секции	Ключ секции для расположения элемента в контейнере.	No
etag	Тег сущности для элемента в контейнере, используемый для управления оптимистическим параллелизмом.	No

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

Атрибут	Description	Обязательное поле	По умолчанию.
type	Тип запроса на запись: `insert`, `replace`или `upsert`.	No	`upsert`
Уровень согласованности	Строка. Задает уровень согласованности Cosmos DB запроса на запись.	No	Н/П
Директива indexing-	Политика индексирования, которая определяет, как следует индексировать элементы контейнера.	No	`default`
предварительная активация	Строка. Идентификатор функции предварительного триггера, зарегистрированной в контейнере Cosmos DB.	No	Н/П
после триггера	Строка. Идентификатор функции после триггера, зарегистрированной в контейнере Cosmos DB.	No	Н/П

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

Имя	Описание	Обязательное поле
id	Идентификатор элемента в контейнере.	Да, когда `type` есть `replace`.
etag	Тег сущности для элемента в контейнере, используемый для управления оптимистическим параллелизмом.	No
set-body	Задает текст в запросе на запись. Если это не указано, полезные данные запроса сопоставляют аргументы в формате JSON.	No

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

Имя	Описание	Обязательное поле
set-body	Задает текст в ответе сопоставителя. Если не указано и возвращаемый JSON содержит имена полей, соответствующие полям в схеме GraphQL, поля автоматически сопоставляются.	No
publish-event	Публикует событие в одну или несколько подписок, указанных в схеме API GraphQL.	No

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

Атрибут	Description	Обязательное поле	По умолчанию.
тип данных	Тип данных ключа секции: `string`, `number`, `bool`, `none`или `null`.	No	`string`
JSON	Используется для задания режима шаблонов для ключа секции. В настоящее время поддерживается только одно значение: - `liquid` — ключ секции будет использовать обработчик шаблонов жидкости	No	Н/П

Атрибут etag

Атрибут	Description	Обязательное поле	По умолчанию.
type	Строка. Одно из следующих значений: - `matchetag`— значение должно соответствовать тегу сущности, созданному системой для элемента. - `no-matchetag`— значение не требуется для сопоставления тега сущности, созданного системой для элемента.	No	`match`
JSON	Используется для задания режима шаблонов для etag. В настоящее время поддерживается только одно значение: - `liquid` — etag будет использовать модуль ликвидной шаблонной шаблоны	No	Н/П

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

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

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

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

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

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

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

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

Включите назначаемое системой управляемое удостоверение в экземпляре управления API. На портале обратите внимание на идентификатор объекта (субъекта) управляемого удостоверения.
- Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см . в кратком руководстве по Bash в Azure Cloud Shell.
- Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.
  - Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других возможностях, доступных при входе, см. в статье Вход с помощью 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.

partition-key Запрос id на чтение передается в качестве параметров запроса и обращается к ней с помощью контекстной переменной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 =@param.id</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
Полный перечень операторов политик и их параметров см. в справочнике по политикам.
Выражения политики
Настройка или изменение политик
Повторное использование конфигураций политик
Репозиторий фрагментов политик
Создание политик с помощью Microsoft Copilot для Azure

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

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

Элементы

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

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

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

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

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

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

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

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

Элементы read-request

Атрибуты delete-request

Элементы delete-request

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

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

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

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

Атрибут etag

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

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

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

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

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

Примеры

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

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

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

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

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

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

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

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

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

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

Дополнительные ресурсы