リゾルバーの Cosmos DB データソース

[アーティクル]
03/18/2024

cosmosdb-data-source リゾルバーポリシーは、Cosmos DB データソースを使用して、GraphQL スキーマ内のオブジェクトの種類とフィールドのデータを解決します。スキーマは API Management に GraphQL API としてインポートする必要があります。

ポリシーを使用して、単一のクエリ要求、読み取り要求、削除要求、または書き込み要求、および Cosmos DB データソースからのオプションの応答を構成します。

注意

このポリシーはプレビュー段階です。現時点では、ポリシーは API Management の従量課金レベルではサポートされていません。

Note

ポリシーの要素と子要素を、ポリシーステートメントで指定された順序で設定します。 API Management ポリシーを設定または編集する方法について説明します。

ポリシーステートメント

<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 データベース内のコンテナーへの接続を指定します。	はい
query-request	Cosmos DB コンテナーに対するクエリ要求の設定を指定します。	`query-request`、`read-request`、`delete-request`、または `write-request` のいずれかを構成します。
read-request	Cosmos DB コンテナーに対する読み取り要求の設定を指定します。	`query-request`、`read-request`、`delete-request`、または `write-request` のいずれかを構成します。
delete-request	Cosmos DB コンテナーに対する削除要求の設定を指定します。	`query-request`、`read-request`、`delete-request`、または `write-request` のいずれかを構成します。
write-request	Cosmos DB コンテナーに対する書き込み要求の設定を指定します。	`query-request`、`read-request`、`delete-request`、または `write-request` のいずれかを構成します。
response	必要に応じて、リゾルバーの応答を構成する子ポリシーを指定します。指定しない場合、応答は JSON として Cosmos DB から返されます。	いいえ

connection-info 要素

Name	説明	必須
connection-string	Cosmos DB アカウントの接続文字列を指定します。 API Management マネージド ID が構成されている場合は、アカウントキーを省略します。	はい
database-name	文字列。 Cosmos DB のデータベースの名前。	はい
container-name	文字列。 Cosmos DB データベース内のコンテナーの名前。	はい

接続文字列属性

属性	説明	必要	Default
use-managed-identity	ブール型。接続文字列内のアカウントキーの代わりに、API Management インスタンスのシステム割り当てマネージド ID を Cosmos DB アカウントへの接続に使用するかどうかを指定します。 Cosmos DB コンテナーにアクセスするように ID を構成する必要があります。	いいえ	`false`

query-request 属性

属性	説明	必要	Default
enable-low-precision-order-by	ブール型。 Cosmos DB サービスで EnableLowPrecisionOrderBy クエリ要求プロパティを有効にするかどうかを指定します。	いいえ	該当なし

query-request 要素

Name	説明	必須
sql-statement	クエリ要求の SQL ステートメント。	いいえ
parameters	パラメーターサブ要素内の、クエリ要求のクエリパラメーターの一覧。	いいえ
partition-key	クエリをコンテナー内の場所にルーティングする Cosmos DB のパーティションキー。	いいえ
paging	クエリ結果を複数のページに分割する設定を指定します。	いいえ

パラメーター属性

属性	説明	必要	Default
name	文字列をオンにします。 @ 表記でのパラメーターの名前。	はい	該当なし

paging 要素

Name	説明	必須
max-item-count	クエリによって返されるアイテムの最大数を指定します。クエリ実行ごとの結果数を制限しない場合は、-1 に設定します。	はい
continuation-token	クエリにアタッチして次の結果セットを取得する継続トークンを指定します。	はい

max-item-count 属性

属性	説明	必要	Default
template	`max-item-count` のテンプレート作成モードを設定するために使用します。現在サポートされている値: - `liquid` - `max-item-count` では、Liquid テンプレート作成エンジンが使用されます。	いいえ	該当なし

continuation-token 属性

属性	説明	必要	Default
template	継続トークンにテンプレート作成モードを設定するために使用します。現在サポートされている値: - `liquid` - 継続トークンでは、Liquid テンプレート作成エンジンが使用されます。	いいえ	該当なし

read-request 要素

Name	説明	必須
id	コンテナー内で読み取る項目の識別子。	はい
パーティションキー	コンテナー内の項目の場所のパーティションキー。 `id` で指定された場合、コンテナー内の項目のクイックポイント読み取り (キー/値の参照) が有効になります。	いいえ

delete-request 属性

属性	説明	必要	Default
consistency-level	文字列をオンにします。削除要求の Cosmos DB 整合性レベルを設定します。	いいえ	該当なし
pre-trigger	文字列をオンにします。 Cosmos DB コンテナーに登録されている pre-trigger 関数の識別子。	いいえ	該当なし
post-trigger	文字列をオンにします。 Cosmos DB コンテナーに登録されている post-trigger 関数の識別子。	いいえ	該当なし

delete-request 要素

名前	説明	必須
id	コンテナー内の削除する項目の識別子。	はい
パーティションキー	コンテナー内の項目の場所のパーティションキー。	いいえ
etag	オプティミスティック同時実行制御に使用される、コンテナー内の項目のエンティティタグ。	いいえ

write-request 属性

属性	説明	必要	Default
type	書き込み要求の種類: `insert`、`replace`、または `upsert`。	いいえ	`upsert`
consistency-level	文字列をオンにします。書き込み要求の Cosmos DB 整合性レベルを設定します。	いいえ	該当なし
indexing-directive	コンテナーの項目のインデックス作成方法を決定するインデックス作成ポリシー。	いいえ	`default`
pre-trigger	文字列をオンにします。 Cosmos DB コンテナーに登録されている pre-trigger 関数の識別子。	いいえ	該当なし
post-trigger	文字列をオンにします。 Cosmos DB コンテナーに登録されている post-trigger 関数の識別子。	いいえ	該当なし

write-request 要素

Name	説明	必須
id	コンテナー内の項目の識別子。	`type` が `replace` の場合、はい。
etag	オプティミスティック同時実行制御に使用される、コンテナー内の項目のエンティティタグ。	No
set-body	書き込み要求の本文を設定します。指定しない場合、要求ペイロードにより引数は JSON 形式にマップされます。	いいえ

response 要素

Name	説明	必須
set-body	リゾルバーの応答の本文を設定します。指定されておらず、返された JSON に GraphQL スキーマ内のフィールドと一致するフィールド名が含まれている場合、フィールドは自動的にマップされます。	No
publish-event	GraphQL API スキーマで指定された 1 つ以上のサブスクリプションにイベントを発行します。	いいえ

partition-key 属性

属性	説明	必要	Default
data-type	パーティションキーのデータ型 (`string`、`number`、`bool`、`none`、または `null`)。	いいえ	`string`
template	パーティションキーにテンプレート作成モードを設定するために使用します。現在サポートされている値: - `liquid` - パーティションキーでは、Liquid テンプレート作成エンジンが使用されます	いいえ	該当なし

etag 属性

属性	説明	必要	Default
type	文字列。次のいずれかの値です。 - `match` - `etag` 値は、システムによって生成された項目のエンティティタグと一致している必要があります - `no-match` - `etag` 値は、システムによって生成された項目のエンティティタグと一致している必要はありません	いいえ	`match`
template	etag のテンプレート作成モードを設定するために使用します。現在サポートされている値: - `liquid` - etag では、Liquid テンプレート作成エンジンが使用されます。	いいえ	該当なし

使用法

ポリシースコープ: GraphQL リゾルバー
ゲートウェイ: クラシック、v2

使用上の注意

このポリシーを使用してリゾルバーを構成および管理するには、「GraphQL リゾルバーの構成」を参照してください。
このポリシーは、スキーマ内の一致する操作の種類の中の 1 つのフィールドを解決する場合にのみ呼び出されます。

Cosmos DB のマネージド ID 統合を構成する

接続文字列にアカウントキーを指定する代わりに、Cosmos DB アカウントにアクセスするように、API Management システム割り当てマネージド ID を構成できます。

Azure CLI を使用してマネージド ID を構成するには、次の手順に従います。

前提条件

API Management インスタンスで、システム割り当てマネージド ID を有効にします。ポータルで、マネージド ID のオブジェクト (プリンシパル) ID をメモします。
- Azure Cloud Shell で Bash 環境を使用します。詳細については、「Azure Cloud Shell の Bash のクイックスタート」を参照してください。
- CLI リファレンスコマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。
  - ローカルインストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。認証プロセスを完了するには、ターミナルに表示される手順に従います。その他のサインインオプションについては、Azure CLI でのサインインに関するページを参照してください。
  - 初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。拡張機能の詳細については、Azure CLI で拡張機能を使用する方法に関するページを参照してください。
  - az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。最新バージョンにアップグレードするには、az upgrade を実行します。

マネージド ID を構成するための 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 クエリ要求

次の例では、Cosmos DB コンテナーへの SQL クエリを使用して GraphQL クエリを解決します。

<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 の読み取り要求

次の例では、Cosmos DB コンテナーへのポイント読み取り要求を使用して GraphQL クエリを解決します。 Cosmos DB アカウントへの接続では、API Management インスタンスのシステム割り当てマネージド ID が使用されます。 Cosmos DB コンテナーにアクセスするように ID を構成する必要があります。

読み取り要求に使用される 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 の削除要求

次の例では、Cosmos DB コンテナーへの削除要求によって、GraphQL の Mutation を解決します。削除要求に使用される 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 書き込み要求

次の例では、Cosmos DB コンテナーへのアップサート要求によって、GraphQL の Mutation を解決します。 Cosmos DB アカウントへの接続では、API Management インスタンスのシステム割り当てマネージド ID が使用されます。 Cosmos DB コンテナーにアクセスするように ID を構成する必要があります。

書き込み要求に使用される partition-key は、クエリパラメーターとして渡され、context.GraphQL.Arguments["id"] コンテキスト変数を使用してアクセスされます。アップサート要求には、"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 の入力の型 (string、int、decimal、bool) を渡す

サンプルポリシー

[...]
<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 for Azure を使用してポリシーを作成する

リゾルバーの Cosmos DB データ ソース

ポリシー ステートメント

要素

connection-info 要素

接続文字列属性

query-request 属性

query-request 要素

パラメーター属性

paging 要素

max-item-count 属性

continuation-token 属性

read-request 要素

delete-request 属性

delete-request 要素

write-request 属性

write-request 要素

response 要素

partition-key 属性

etag 属性

使用法

使用上の注意

Cosmos DB のマネージド ID 統合を構成する

前提条件

マネージド ID を構成するための Azure CLI スクリプト

例

Cosmos DB クエリ要求

Cosmos DB の読み取り要求

Cosmos DB の削除要求

Cosmos DB 書き込み要求

Cosmos DB クエリのパラメーター入力を構築する

式から JSON オブジェクト (JObject) を渡す

式から .NET の入力の型 (string、int、decimal、bool) を渡す

式から JSON 値 (JValue) を渡す

関連ポリシー

関連するコンテンツ

その他のリソース

リゾルバーの Cosmos DB データソース

ポリシーステートメント