Azure Functions 2.x 以降に対する Azure Cosmos DB の出力バインド

Azure Cosmos DB 出力バインドを使用すると、SQL API を使って Azure Cosmos DB データベースに新しいドキュメントを記述できます。

セットアップと構成の詳細については、概要に関するページをご覧ください。

このセクションには、次の例が含まれています。

例では、次のようなシンプルな ToDoItem タイプを参照します。

namespace CosmosDBSamplesV2
{
    public class ToDoItem
    {
        public string Id { get; set; }
        public string Description { get; set; }
    }
}

キュー トリガー、1 つのドキュメントの書き込み

次の例は、キュー ストレージからのメッセージで提供されるデータを使用して、ドキュメントをデータベースに追加する C# 関数を示しています。

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using System;

namespace CosmosDBSamplesV2
{
    public static class WriteOneDoc
    {
        [FunctionName("WriteOneDoc")]
        public static void Run(
            [QueueTrigger("todoqueueforwrite")] string queueMessage,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]out dynamic document,
            ILogger log)
        {
            document = new { Description = queueMessage, id = Guid.NewGuid() };

            log.LogInformation($"C# Queue trigger function inserted one row");
            log.LogInformation($"Description={queueMessage}");
        }
    }
}

キュー トリガー、IAsyncCollector を使用したドキュメントの書き込み

次の例は、キュー メッセージ JSON で提供されるデータを使用して、ドキュメントのコレクションをデータベースに追加する C# 関数を示しています。

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class WriteDocsIAsyncCollector
    {
        [FunctionName("WriteDocsIAsyncCollector")]
        public static async Task Run(
            [QueueTrigger("todoqueueforwritemulti")] ToDoItem[] toDoItemsIn,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]
                IAsyncCollector<ToDoItem> toDoItemsOut,
            ILogger log)
        {
            log.LogInformation($"C# Queue trigger function processed {toDoItemsIn?.Length} items");

            foreach (ToDoItem toDoItem in toDoItemsIn)
            {
                log.LogInformation($"Description={toDoItem.Description}");
                await toDoItemsOut.AddAsync(toDoItem);
            }
        }
    }
}

属性と注釈

C# クラス ライブラリでは、CosmosDB 属性を使用します。

この属性のコンストラクターにはデータベース名とコレクションを指定します。 これらの設定や構成できる他のプロパティについて詳しくは、「出力 - 構成」をご覧ください。 メソッド シグネチャでの CosmosDB 属性の例を次に示します。

    [FunctionName("QueueToDocDB")]
    public static void Run(
        [QueueTrigger("myqueue-items", Connection = "AzureWebJobsStorage")] string myQueueItem,
        [CosmosDB("ToDoList", "Items", Id = "id", ConnectionStringSetting = "myCosmosDB")] out dynamic document)
    {
        ...
    }

構成

次の表は、function.json ファイルと CosmosDB 属性で設定したバインド構成のプロパティを説明しています。

function.json のプロパティ 属性のプロパティ 説明
type 該当なし cosmosDB に設定する必要があります。
direction 該当なし out に設定する必要があります。
name 該当なし 関数のドキュメントを表すバインド パラメーターの名前。
databaseName DatabaseName ドキュメントが作成されたコレクションを含むデータベース。
collectionName CollectionName ドキュメントが作成されたコレクションの名前。
createIfNotExists CreateIfNotExists コレクションが存在しないときに作成するかどうかを示すブール値。 既定値は false です。新しいコレクションは予約済みのスループットで作成され、これが価格に影響を及ぼすためです。 詳細については、 価格に関するページを参照してください。
partitionKey PartitionKey CreateIfNotExists が true の場合に、作成されるコレクションのパーティション キー パスを定義します。
collectionThroughput CollectionThroughput CreateIfNotExists が true の場合に、作成されるコレクションのスループットを定義します。
connectionStringSetting ConnectionStringSetting Azure Cosmos DB 接続文字列を含むアプリ設定の名前。
preferredLocations PreferredLocations (省略可能) Azure Cosmos DB サービスの geo レプリケートされたデータベース アカウントの優先される場所 (リージョン) を定義します。 複数の値はコンマで区切る必要があります。 たとえば、"East US,South Central US,North Europe" などです。
useMultipleWriteLocations UseMultipleWriteLocations (省略可能) PreferredLocations と共に true に設定すると、Azure Cosmos DB サービスでマルチ リージョン書き込みを利用できます。

ローカルで開発している場合、アプリ設定は local.settings.json ファイルに保存されます。

使用法

既定では、関数の出力パラメーターに書き込むと、ドキュメントがデータベースに作成されます。 このドキュメントには、自動的に生成された GUID がドキュメント ID として割り当てられます。 出力ドキュメントのドキュメント ID を指定するには、出力パラメーターに渡された JSON オブジェクトで id プロパティを指定します。

注意

既存のドキュメントの ID を指定した場合、既存のドキュメントは新しい出力ドキュメントによって上書きされます。

例外とリターン コード

バインド リファレンス
Cosmos DB CosmosDB のエラー コード

host.json 設定

このセクションでは、バージョン 2.x でこのバインディングに使用可能なグローバル構成設定について説明します。 バージョン 2.x でのグローバル構成設定の詳細については、Azure Functions バージョン 2.x の host.json のリファレンスを参照してください。

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "protocol": "Https",
            "leaseOptions": {
                "leasePrefix": "prefix1"
            }
        }
    }
}
プロパティ Default 説明
GatewayMode Gateway Azure Cosmos DB サービスに接続する際に関数で使用される接続モード。 オプションは DirectGateway です
Protocol Https Azure Cosmos DB サービスに接続する際に関数で使用される接続プロトコル。 両方のモードの説明についてはこちらを参照してください
leasePrefix 該当なし アプリ内のすべての関数で使用するプレフィックスをリースします。

次のステップ