Azure Functions 1.x の Azure Cosmos DB バインド

[アーティクル]
10/07/2023

重要

Azure Functions Runtime のバージョン 1.x のサポートは 2026 年 9 月 14 日に終了します。完全なサポートのために、アプリをバージョン 4.x に移行することを強くお勧めします。

この記事では、Azure Functions で Azure Cosmos DB のバインドを操作する方法について説明します。 Azure Functions は、Azure Cosmos DB のトリガー、入力、出力のバインドをサポートしています。

Note

この記事は、Azure Functions 1.x を対象としています。 Functions 2.x およびそれ以降で、これらのバインディングを使用する方法については、「Azure Functions 2.x バインド用の Microsoft Azure Cosmos DB」を参照してください。

このバインドの元の名称は DocumentDB でした。 Azure Functions バージョン 1.x では、トリガーのみが Azure Cosmos DB に名称が変更され、入力バインド、出力バインド、および NuGet パッケージは DocumentDB のままでした。

Note

Azure Cosmos DB のバインドは、SQL API で使用する場合にのみサポートされます。他のすべての Azure Cosmos DB API については、Azure Cosmos DB for MongoDB、Azure Cosmos DB for Apache Cassandra、Azure Cosmos DB for Apache Gremlin、Azure Cosmos DB for Table などの API 用の静的クライアントを使用して、関数からデータベースにアクセスする必要があります。

パッケージ - Functions 1.x

Functions バージョン 1.x の Azure Cosmos DB バインドは、Microsoft.Azure.WebJobs.Extensions.DocumentDB NuGet パッケージのバージョン 1.x で提供されています。バインドのソースコードは、azure-webjobs-sdk-extensions GitHub リポジトリにあります。

次の表に、各開発環境で出力バインドのサポートを追加する方法を示します。

開発環境	Functions 1.x でサポートを追加するには
ローカル開発: C# クラスライブラリ	パッケージをインストールする
ローカル開発: C# スクリプト、JavaScript、F#	自動
Portal 開発	自動

トリガー

Azure Cosmos DB のトリガーは Azure Cosmos DB 変更フィードを使用して、パーティション間の挿入と更新をリッスンします。変更フィードは、削除ではなく挿入と更新を発行します。

次の例では、指定したデータベースとコレクションで挿入または更新が発生すると呼び出されるインプロセス C# 関数を示します。

using Microsoft.Azure.Documents;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;

namespace CosmosDBSamplesV1
{
    public static class CosmosTrigger
    {
        [FunctionName("CosmosTrigger")]
        public static void Run([CosmosDBTrigger(
            databaseName: "ToDoItems",
            collectionName: "Items",
            ConnectionStringSetting = "CosmosDBConnection",
            LeaseCollectionName = "leases",
            CreateLeaseCollectionIfNotExists = true)]IReadOnlyList<Document> documents,
            TraceWriter log)
        {
            if (documents != null && documents.Count > 0)
            {
                log.Info($"Documents modified: {documents.Count}");
                log.Info($"First document Id: {documents[0].Id}");
            }
        }
    }
}

次の例は、function.json ファイルの Azure Cosmos DB トリガーバインドと、そのバインドが使用される JavaScript 関数を示しています。 Azure Cosmos DB レコードが変更されると、この関数によってログメッセージが書き込まれます。

function.json ファイルのバインディングデータを次に示します。

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

JavaScript コードを次に示します。

    module.exports = async function (context, documents) {
        context.log('First document Id modified : ', documents[0].id);
    }

トリガー - 属性

C#
JavaScript

インプロセス C# クラスライブラリの場合は、CosmosDBTrigger 属性を使います。

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

    [FunctionName("DocumentUpdates")]
    public static void Run(
        [CosmosDBTrigger("database", "collection", ConnectionStringSetting = "myCosmosDB")]
    IReadOnlyList<Document> documents,
        TraceWriter log)
    {
        ...
    }

完全な例については、「トリガー - C# の例」を参照してください。

トリガー - 構成

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

function.json のプロパティ	属性のプロパティ	説明
type	該当なし	`cosmosDBTrigger` に設定する必要があります。
direction	該当なし	`in` に設定する必要があります。このパラメーターは、Azure Portal でトリガーを作成するときに自動で設定されます。
name	該当なし	変更されるドキュメントの一覧を表す、関数コードで使用する変数の名前。
connectionStringSetting	ConnectionStringSetting	監視されている Azure Cosmos DB アカウントに接続するために使用される接続文字列を含めたアプリ設定の名前。
databaseName	DatabaseName	監視されているコレクションを使用する Azure Cosmos DB データベースの名前。
collectionName	CollectionName	監視されているコレクションの名前。
leaseConnectionStringSetting	LeaseConnectionStringSetting	(省略可能) リースコレクションを保持するサービスへの接続文字列を含むアプリ設定の名前。この値を設定しない場合、`connectionStringSetting` という値が使用されます。このパラメーターは、ポータルでバインドが作成されるときに自動で設定されます。リースコレクションの接続文字列には書き込み権限が必要です。
leaseDatabaseName	LeaseDatabaseName	(省略可能) リースの保存のために使用するコレクションを保持しているデータベースの名前。この値を設定しない場合、`databaseName` の設定の値が使用されます。このパラメーターは、ポータルでバインドが作成されるときに自動で設定されます。
leaseCollectionName	LeaseCollectionName	(省略可能) リースの保存のために使用するコレクションの名前。この値を設定しない場合、`leases` という値が使用されます。
createLeaseCollectionIfNotExists	CreateLeaseCollectionIfNotExists	(省略可能) `true` を設定すると、リースコレクションが存在していない場合に自動でリースコレクションを作成します。既定値は `false` です。
leasesCollectionThroughput	leasesCollectionThroughput	(省略可能) リースコレクションの作成に割り当てる要求ユニットの量を定義します。この設定は、`createLeaseCollectionIfNotExists` が `true` に設定されている場合のみ使用できます。このパラメーターは、ポータルを使用してバインドを作成するときに自動的に設定されます。
leaseCollectionPrefix	LeaseCollectionPrefix	(省略可能) 設定すると、この関数のリースコレクション内に作成されたリースにプレフィックスが追加され、2 つの独立した Azure Functions が、異なるプレフィックスを使用することで同じリースコレクションを効率的に共有できます。
feedPollDelay	FeedPollDelay	(省略可能) 設定すると、現在の変更がすべて排除された後、パーティションでフィードの新しい変更をポーリングするまでの遅延時間がミリ秒単位で定義されます。既定値は 5,000 (5 秒) です。
leaseAcquireInterval	LeaseAcquireInterval	(省略可能) 設定すると、パーティションが既知のホストインスタンス間で均等に分散されているかどうかを計算するタスクを開始する間隔がミリ秒単位で定義されます。既定値は 13,000 (13 秒) です。
leaseExpirationInterval	LeaseExpirationInterval	(省略可能) 設定すると、パーティションを表すリースでリースを取得する間隔がミリ秒単位で定義されます。この間隔内にリースが更新されない場合、リースは期限切れとなり、パーティションの所有権は別のインスタンスに移動します。既定値は 60,000 (60 秒) です。
leaseRenewInterval	LeaseRenewInterval	(省略可能) 設定すると、インスタンスが現在保持しているパーティションのすべてのリースの更新間隔がミリ秒単位で定義されます。既定値は 17,000 (17 秒) です。
checkpointFrequency	CheckpointFrequency	(省略可能) 設定すると、リースチェックポイントの間隔がミリ秒単位で定義されます。既定値は、常に各関数呼び出しの後です。
maxItemsPerInvocation	MaxItemsPerInvocation	(省略可能) 設定すると、関数呼び出しごとに受信するアイテムの最大量がカスタマイズされます。
startFromBeginning	StartFromBeginning	(省略可能) 設定すると、現在の時刻ではなく、コレクションの履歴の最初から変更の読み取りを開始するように、トリガーが指示されます。これは、初めてトリガーが起動される場合にのみ機能します。その後の実行では、チェックポイントが既に格納されているためです。既にリースが作成されているときにこれを `true` に設定しても効果はありません。

ローカルで開発する場合は、Values コレクション内の local.settings.json ファイルにアプリケーション設定を追加します。

トリガー - 使用方法

トリガーは、パーティションに リース を保存するために使用する 2 つ目のコレクションを必要とします。トリガーが機能するためには、監視されるコレクションと、リースを含むコレクションの両方が使用できる必要があります。

重要

複数の関数が同じコレクションの Azure Cosmos DB トリガーを使用するように構成している場合、各関数では専用のリースコレクションを使用するか、または各関数に対して異なる LeaseCollectionPrefix を指定する必要があります。専用のリースコレクションを使用していない場合は、関数のうちの 1 つしかトリガーされません。プレフィックスの詳細については、「構成」セクションを参照してください。

トリガーは、ドキュメントが更新または挿入されたかどうかを示すわけではなく、単にドキュメント自体を提供します。更新と挿入を別の方法で処理する必要がある場合は、挿入または更新のタイムスタンプを実装することでこれを実現できます。

入力

Azure Cosmos DB 入力バインドでは、SQL API を使用して 1 つ以上の Azure Cosmos DB ドキュメントを取得して関数の入力パラメーターに渡します。ドキュメント ID またはクエリパラメーターは、関数を呼び出したトリガーに基づいて決定することができます。

入力 - 例

C#
JavaScript

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

キュートリガー、JSON からの ID の検索
HTTP トリガー、クエリ文字列からの ID の検索
HTTP トリガー、ルートデータからの ID の検索
HTTP トリガー、SqlQuery を使用したルートデータからの ID の検索
HTTP トリガー、SqlQuery を使用した複数のドキュメントの取得
HTTP トリガー、DocumentClient を使用した複数のドキュメントの取得

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

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

キュートリガー、JSON からの ID の検索

次の例は、単一のドキュメントを取得する C# 関数を示しています。関数は、JSON オブジェクトを含むキューメッセージによってトリガーされます。キュートリガーは、検索する ID を含む ToDoItemLookup という名前のオブジェクトへの JSON を解析します。該当の ID は、指定されたデータベースとコレクションからの ToDoItem ドキュメントの取得に使用されます。

namespace CosmosDBSamplesV1
{
    public class ToDoItemLookup
    {
        public string ToDoItemId { get; set; }
    }
}

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromJSON
    {
        [FunctionName("DocByIdFromJSON")]
        public static void Run(
            [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{ToDoItemId}")]ToDoItem toDoItem,
            TraceWriter log)
        {
            log.Info($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId}");

            if (toDoItem == null)
            {
                log.Info($"ToDo item not found");
            }
            else
            {
                log.Info($"Found ToDo item, Description={toDoItem.Description}");
            }
        }
    }
}

HTTP トリガー、クエリ文字列からの ID の検索

次の例は、単一のドキュメントを取得する C# 関数を示しています。関数は、クエリ文字列を使用して検索のための ID を指定する HTTP 要求によってトリガーされます。該当の ID は、指定されたデータベースとコレクションからの ToDoItem ドキュメントの取得に使用されます。

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromQueryString
    {
        [FunctionName("DocByIdFromQueryString")]
        public static HttpResponseMessage Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{Query.id}")] ToDoItem toDoItem,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");
            if (toDoItem == null)
            {
                log.Info($"ToDo item not found");
            }
            else
            {
                log.Info($"Found ToDo item, Description={toDoItem.Description}");
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

HTTP トリガー、ルートデータからの ID の検索

次の例は、単一のドキュメントを取得する C# 関数を示しています。関数は、ルートデータを使用して検索のための ID を指定する HTTP 要求によってトリガーされます。該当の ID は、指定されたデータベースとコレクションからの ToDoItem ドキュメントの取得に使用されます。

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromRouteData
    {
        [FunctionName("DocByIdFromRouteData")]
        public static HttpResponseMessage Run(
            [HttpTrigger(
                AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems/{id}")]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{id}")] ToDoItem toDoItem,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");

            if (toDoItem == null)
            {
                log.Info($"ToDo item not found");
            }
            else
            {
                log.Info($"Found ToDo item, Description={toDoItem.Description}");
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

入力の例をスキップする

HTTP トリガー、SqlQuery を使用したルートデータからの ID の検索

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromRouteDataUsingSqlQuery
    {
        [FunctionName("DocByIdFromRouteDataUsingSqlQuery")]
        public static HttpResponseMessage Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems2/{id}")]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "select * from ToDoItems r where r.id = {id}")] IEnumerable<ToDoItem> toDoItems,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");
            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.Info(toDoItem.Description);
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

入力の例をスキップする

HTTP トリガー、SqlQuery を使用した複数のドキュメントの取得

次の例は、ドキュメントの一覧を取得する C# 関数を示しています。関数は、HTTP 要求によってトリガーされます。クエリは、SqlQuery 属性プロパティで指定されます。

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocsBySqlQuery
    {
        [FunctionName("DocsBySqlQuery")]
        public static HttpResponseMessage Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]
                HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "SELECT top 2 * FROM c order by c._ts desc")]
                IEnumerable<ToDoItem> toDoItems,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");
            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.Info(toDoItem.Description);
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

入力の例をスキップする

HTTP トリガー、DocumentClient を使用した複数のドキュメントの取得 (C#)

次の例は、ドキュメントの一覧を取得する C# 関数を示しています。関数は、HTTP 要求によってトリガーされます。コードでは、Azure Cosmos DB バインドによって提供される DocumentClient インスタンスを使用して、ドキュメントの一覧を読み取ります。また、DocumentClient インスタンスは、書き込み操作に使用できます。

using Microsoft.Azure.Documents.Client;
using Microsoft.Azure.Documents.Linq;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;

namespace CosmosDBSamplesV1
{
    public static class DocsByUsingDocumentClient
    {
        [FunctionName("DocsByUsingDocumentClient")]
        public static async Task<HttpResponseMessage> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")] DocumentClient client,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");

            Uri collectionUri = UriFactory.CreateDocumentCollectionUri("ToDoItems", "Items");
            string searchterm = req.GetQueryNameValuePairs()
                .FirstOrDefault(q => string.Compare(q.Key, "searchterm", true) == 0)
                .Value;

            if (searchterm == null)
            {
                return req.CreateResponse(HttpStatusCode.NotFound);
            }

            log.Info($"Searching for word: {searchterm} using Uri: {collectionUri.ToString()}");
            IDocumentQuery<ToDoItem> query = client.CreateDocumentQuery<ToDoItem>(collectionUri)
                .Where(p => p.Description.Contains(searchterm))
                .AsDocumentQuery();

            while (query.HasMoreResults)
            {
                foreach (ToDoItem result in await query.ExecuteNextAsync())
                {
                    log.Info(result.Description);
                }
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

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

キュートリガー、JSON からの ID の検索
HTTP トリガー、クエリ文字列からの ID の検索
HTTP トリガー、ルートデータからの ID の検索
キュートリガー、SqlQuery を使用した複数のドキュメントの取得

キュートリガー、JSON からの ID の検索

次の例は、function.json ファイルの Azure Cosmos DB 入力バインドと、そのバインドが使用される JavaScript 関数を示しています。この関数は、1 つのドキュメントを読み取って、そのドキュメントのテキスト値を更新します。

function.json ファイルのバインディングデータを次に示します。

{
    "name": "inputDocumentIn",
    "type": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger_payload_property}",
    "partitionKey": "{queueTrigger_payload_property}",
    "connection": "MyAccount_COSMOSDB",
    "direction": "in"
},
{
    "name": "inputDocumentOut",
    "type": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": false,
    "partitionKey": "{queueTrigger_payload_property}",
    "connection": "MyAccount_COSMOSDB",
    "direction": "out"
}

これらのプロパティについては、「構成」セクションを参照してください。

JavaScript コードを次に示します。

    // Change input document contents using Azure Cosmos DB input binding, using context.bindings.inputDocumentOut
    module.exports = async function (context) {
        context.bindings.inputDocumentOut = context.bindings.inputDocumentIn;
        context.bindings.inputDocumentOut.text = "This was updated!";
    };

HTTP トリガー、クエリ文字列からの ID の検索

次の例は、単一のドキュメントを取得する JavaScript 関数を示しています。関数は、クエリ文字列を使用して検索のための ID を指定する HTTP 要求によってトリガーされます。該当の ID は、指定されたデータベースとコレクションからの ToDoItem ドキュメントの取得に使用されます。

function.json ファイルを次に示します。

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "documentDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connection": "CosmosDBConnection",
      "direction": "in",
      "Id": "{Query.id}"
    }
  ],
  "disabled": true
}

JavaScript コードを次に示します。

module.exports = async function (context, req, toDoItem) {
    context.log('JavaScript queue trigger function processed work item');
    if (!toDoItem)
    {
        context.log("ToDo item not found");
    }
    else
    {
        context.log("Found ToDo item, Description=" + toDoItem.Description);
    }
};

HTTP トリガー、ルートデータからの ID の検索

function.json ファイルを次に示します。

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ],
      "route":"todoitems/{id}"
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "documentDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connection": "CosmosDBConnection",
      "direction": "in",
      "Id": "{id}"
    }
  ],
  "disabled": false
}

JavaScript コードを次に示します。

module.exports = async function (context, req, toDoItem) {
    context.log('JavaScript queue trigger function processed work item');
    if (!toDoItem)
    {
        context.log("ToDo item not found");
    }
    else
    {
        context.log("Found ToDo item, Description=" + toDoItem.Description);
    }
};

キュートリガー、SqlQuery を使用した複数のドキュメントの取得

次の例は、function.json ファイルの Azure Cosmos DB 入力バインドと、そのバインドが使用される JavaScript 関数を示しています。この関数は、SQL クエリで指定されている複数のドキュメントを、キュートリガーを使用してクエリパラメーターをカスタマイズすることで取得します。

キュートリガーがパラメーター departmentId を提供します。 { "departmentId" : "Finance" } のキューメッセージは、金融部門のすべてのレコードを返します。

function.json ファイルのバインディングデータを次に示します。

{
    "name": "documents",
    "type": "documentdb",
    "direction": "in",
    "databaseName": "MyDb",
    "collectionName": "MyCollection",
    "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}",
    "connection": "CosmosDBConnection"
}

これらのプロパティについては、「構成」セクションを参照してください。

JavaScript コードを次に示します。

    module.exports = async function (context, input) {
        var documents = context.bindings.documents;
        for (var i = 0; i < documents.length; i++) {
            var document = documents[i];
            // operate on each document
        }
    };

入力 - 属性

C#
JavaScript

インプロセス C# クラスライブラリでは、DocumentDB 属性を使います。

この属性のコンストラクターにはデータベース名とコレクションを指定します。これらの設定や構成できる他のプロパティについて詳しくは、この後の構成に関するセクションをご覧ください。

入力 - 構成

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

function.json のプロパティ	属性のプロパティ	説明
type	該当なし	`documentdb` に設定する必要があります。
direction	該当なし	`in` に設定する必要があります。
name	該当なし	関数のドキュメントを表すバインドパラメーターの名前。
databaseName	DatabaseName	ドキュメントを含むデータベース。
collectionName	CollectionName	ドキュメントを含むコレクションの名前。
id	Id	取得するドキュメントの ID。このプロパティは、バインド式をサポートしています。 id プロパティと sqlQuery プロパティの両方は設定しないでください。いずれも設定しない場合は、コレクション全体が取得されます。
sqlQuery	SqlQuery	複数のドキュメントを取得するときに使用する Azure Cosmos DB SQL クエリ。このプロパティは、次の例のように実行時のバインドをサポートします。`SELECT * FROM c where c.departmentId = {departmentId}` id プロパティと sqlQuery プロパティの両方は設定しないでください。いずれも設定しない場合は、コレクション全体が取得されます。
connection	ConnectionStringSetting	Azure Cosmos DB 接続文字列を含むアプリ設定の名前。
partitionKey	PartitionKey	参照用のパーティションキー値を指定します。バインディングパラメーターを含めることもできます。

ローカルで開発する場合は、Values コレクション内の local.settings.json ファイルにアプリケーション設定を追加します。

入力 - 使用方法

C#
JavaScript

関数が正常に終了したときに、名前付き入力パラメーターを介した入力ドキュメントへの変更がすべて自動的に保持されます。

Output

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

出力 - 例

C#
JavaScript

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

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

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

namespace CosmosDBSamplesV1
{
    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 System;

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

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

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

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

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

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

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

次の例は、function.json ファイルの Azure Cosmos DB 出力バインドと、そのバインドが使用される JavaScript 関数を示しています。この関数は、次の形式で JSON を受信するキューのキュー入力バインドを使用します。

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

この関数は、各レコードに対して次の形式の Azure Cosmos DB ドキュメントを作成します。

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

function.json ファイルのバインディングデータを次に示します。

{
    "name": "employeeDocument",
    "type": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": true,
    "connection": "MyAccount_COSMOSDB",
    "direction": "out"
}

これらのプロパティについては、「構成」セクションを参照してください。

JavaScript コードを次に示します。

    module.exports = async function (context) {

      context.bindings.employeeDocument = JSON.stringify({
        id: context.bindings.myQueueItem.name + "-" + context.bindings.myQueueItem.employeeId,
        name: context.bindings.myQueueItem.name,
        employeeId: context.bindings.myQueueItem.employeeId,
        address: context.bindings.myQueueItem.address
      });
    };

出力 - 属性

C#
JavaScript

インプロセス C# クラスライブラリでは、DocumentDB 属性を使います。

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

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

完全な例については、「出力」を参照してください。

出力 - 構成

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

function.json のプロパティ	属性のプロパティ	説明
type	該当なし	`documentdb` に設定する必要があります。
direction	該当なし	`out` に設定する必要があります。
name	該当なし	関数のドキュメントを表すバインドパラメーターの名前。
databaseName	DatabaseName	ドキュメントが作成されたコレクションを含むデータベース。
collectionName	CollectionName	ドキュメントが作成されたコレクションの名前。
createIfNotExists	CreateIfNotExists	コレクションが存在しないときに作成するかどうかを示すブール値。既定値は false です。新しいコレクションは予約済みのスループットで作成され、これが価格に影響を及ぼすためです。詳細については、価格に関するページを参照してください。
partitionKey	PartitionKey	`CreateIfNotExists` が true の場合に、作成されるコレクションのパーティションキーパスを定義します。
collectionThroughput	CollectionThroughput	`CreateIfNotExists` が true の場合に、作成されるコレクションのスループットを定義します。
connection	ConnectionStringSetting	Azure Cosmos DB 接続文字列を含むアプリ設定の名前。

ローカルで開発する場合は、Values コレクション内の local.settings.json ファイルにアプリケーション設定を追加します。

出力 - 使用方法

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

Note

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

例外とリターンコード

バインド	リファレンス
Azure Cosmos DB	Azure Cosmos DB の HTTP 状態コード

次の方法で共有

Azure Functions 1.x の Azure Cosmos DB バインド

パッケージ - Functions 1.x

トリガー

トリガー - 例

トリガー - 属性

トリガー - 構成

トリガー - 使用方法

入力

入力 - 例

キュートリガー、JSON からの ID の検索

HTTP トリガー、クエリ文字列からの ID の検索

HTTP トリガー、ルートデータからの ID の検索

HTTP トリガー、SqlQuery を使用したルートデータからの ID の検索

HTTP トリガー、SqlQuery を使用した複数のドキュメントの取得

HTTP トリガー、DocumentClient を使用した複数のドキュメントの取得 (C#)

キュートリガー、JSON からの ID の検索

HTTP トリガー、クエリ文字列からの ID の検索

HTTP トリガー、ルートデータからの ID の検索

キュートリガー、SqlQuery を使用した複数のドキュメントの取得

入力 - 属性

入力 - 構成

入力 - 使用方法

Output

出力 - 例

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

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

出力 - 属性

出力 - 構成

出力 - 使用方法

例外とリターンコード

次のステップ

フィードバック

その他のリソース

次の方法で共有

Azure Functions 1.x の Azure Cosmos DB バインド

パッケージ - Functions 1.x

トリガー

トリガー - 例

トリガー - 属性

トリガー - 構成

トリガー - 使用方法

入力

入力 - 例

キュー トリガー、JSON からの ID の検索

HTTP トリガー、クエリ文字列からの ID の検索

HTTP トリガー、ルート データからの ID の検索

HTTP トリガー、SqlQuery を使用したルート データからの ID の検索

HTTP トリガー、SqlQuery を使用した複数のドキュメントの取得

HTTP トリガー、DocumentClient を使用した複数のドキュメントの取得 (C#)

入力 - 属性

入力 - 構成

入力 - 使用方法

Output

出力 - 例

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

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

出力 - 属性

出力 - 構成

出力 - 使用方法

例外とリターン コード

次のステップ

フィードバック

その他のリソース

キュートリガー、JSON からの ID の検索

HTTP トリガー、ルートデータからの ID の検索

HTTP トリガー、SqlQuery を使用したルートデータからの ID の検索

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

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

例外とリターンコード