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

適用対象: Developer | Basic | Basic v2 | Standard | Standard v2 | Premium | Premium v2

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

ポリシーを使用して、単一のクエリ要求、読み取り要求、削除要求、または書き込み要求、および 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> 

要素

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

使用法

• ポリシー スコープ: 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 を変換および保護する
• ポリシー ステートメントとその設定の一覧に関するポリシー リファレンス
• ポリシー式
• ポリシーの設定または編集
• ポリシー構成を再利用する
• ポリシー スニペットのリポジトリ
• Azure API Management ポリシー ツールキット
• Azure で Microsoft Copilot を使用してポリシーを作成する