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

  • [アーティクル]

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

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

重要

この記事では、タブを使用して、Node.js プログラミング モデルの複数のバージョンに対応しています。 v4 モデルは一般提供されており、JavaScript と TypeScript の開発者にとって、より柔軟で直感的なエクスペリエンスが得られるように設計されています。 v4 モデルの動作の詳細については、Azure Functions Node.js 開発者ガイドを参照してください。 v3 と v4 の違いの詳細については、移行ガイドを参照してください。

Azure Functions では、Python の 2 つのプログラミング モデルがサポートされています。 バインドを定義する方法は、選択したプログラミング モデルによって異なります。

Python v2 プログラミング モデルでは、Python 関数コードでデコレーターを使用してバインドを直接定義できます。 詳細については、「Python 開発者ガイド」を参照してください。

この記事は、両方のプログラミング モデルをサポートしています。

A C# 関数は、次の C# モードのいずれかを使用して作成できます。

  • 分離されたワーカー モデル: ランタイムから分離されたワーカー プロセスで実行されるコンパイル済みの C# 関数。 分離ワーカー プロセスは、LTS および 非 LTS バージョンの .NET および .NET Framework で実行されている C# 関数をサポートするために必要です。 分離ワーカー プロセス関数の拡張機能では、Microsoft.Azure.Functions.Worker.Extensions.* 名前空間が使用されます。
  • インプロセス モデル: Functions ランタイムと同じプロセスで実行されるコンパイル済みの C# 関数。 このモデルの一部では、主に C# ポータルの編集のためにサポートされている C# スクリプトを使用して Functions を実行できます。 インプロセス関数の拡張機能では、Microsoft.Azure.WebJobs.Extensions.* 名前空間が使用されます。

重要

インプロセス モデルのサポートは 2026 年 11 月 10 日に終了します。 完全なサポートのために、アプリを分離ワーカー モデルに移行することを強くお勧めします。

例

特に記載がない限り、この記事の例は Azure Cosmos DB 拡張機能のバージョン 3.x を対象としています。 拡張機能バージョン 4.x で使用するには、プロパティ名と属性名containerconnection_string_settingconnectionの文字列collectionを .

次のコードでは、MyDocument 型を定義しています。

public class MyDocument
{
    public string Id { get; set; }

    public string Text { get; set; }

    public int Number { get; set; }

    public bool Boolean { get; set; }
}

次の例では、戻り値の型は IReadOnlyList<T> です。これは、トリガー バインディング パラメーターからのドキュメントの変更された一覧です。

using System.Collections.Generic;
using System.Linq;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace SampleApp
{
    public class CosmosDBFunction
    {
        private readonly ILogger<CosmosDBFunction> _logger;

        public CosmosDBFunction(ILogger<CosmosDBFunction> logger)
        {
            _logger = logger;
        }

        //<docsnippet_exponential_backoff_retry_example>
        [Function(nameof(CosmosDBFunction))]
        [ExponentialBackoffRetry(5, "00:00:04", "00:15:00")]
        [CosmosDBOutput("%CosmosDb%", "%CosmosContainerOut%", Connection = "CosmosDBConnection", CreateIfNotExists = true)]
        public object Run(
            [CosmosDBTrigger(
                "%CosmosDb%",
                "%CosmosContainerIn%",
                Connection = "CosmosDBConnection",
                LeaseContainerName = "leases",
                CreateLeaseContainerIfNotExists = true)] IReadOnlyList<MyDocument> input,
            FunctionContext context)
        {
            if (input != null && input.Any())
            {
                foreach (var doc in input)
                {
                    _logger.LogInformation("Doc Id: {id}", doc.Id);
                }

                // Cosmos Output
                return input.Select(p => new { id = p.Id });
            }

            return null;
        }
        //</docsnippet_exponential_backoff_retry_example>
    }

キュー トリガー、戻り値を使用したメッセージのデータベースへの保存

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

@FunctionName("getItem")
@CosmosDBOutput(name = "database",
  databaseName = "ToDoList",
  collectionName = "Items",
  connectionStringSetting = "AzureCosmosDBConnection")
public String cosmosDbQueryById(
    @QueueTrigger(name = "msg",
      queueName = "myqueue-items",
      connection = "AzureWebJobsStorage")
    String message,
    final ExecutionContext context)  {
     return "{ id: \"" + System.currentTimeMillis() + "\", Description: " + message + " }";
   }

HTTP トリガー、戻り値を使用した 1 つのドキュメントのデータベースへの保存

次の例は、シグネチャに @CosmosDBOutput の注釈が付けられ、型 String の戻り値を持つ Java 関数を示しています。 この関数によって返された JSON ドキュメントは、対応する Azure Cosmos DB コレクションに自動的に書き込まれます。

    @FunctionName("WriteOneDoc")
    @CosmosDBOutput(name = "database",
      databaseName = "ToDoList",
      collectionName = "Items",
      connectionStringSetting = "Cosmos_DB_Connection_String")
    public String run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        return jsonDocument;
    }

HTTP トリガー、OutputBinding を使用した 1 つのドキュメントのデータベースへの保存

次の例は、OutputBinding<T> 出力パラメーターを使用して Azure Cosmos DB にドキュメントを書き込む Java 関数を示しています。 この例では、outputItem パラメーターに関数シグネチャではなく @CosmosDBOutput の注釈を付ける必要があります。 OutputBinding<T> を使用すると、関数で Azure Cosmos DB にドキュメントを書き込むためのバインディングを利用しながら、関数の呼び出し元に JSON または XML ドキュメントなどの異なる値を返すこともできるようになります。

    @FunctionName("WriteOneDocOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<String> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        // Set outputItem's value to the JSON document to be saved
        outputItem.setValue(jsonDocument);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Document created successfully.")
                      .build();
    }

HTTP トリガー、OutputBinding を使用した複数のドキュメントのデータベースへの保存

次の例は、OutputBinding<T> 出力パラメーターを使用して Azure Cosmos DB に複数のドキュメントを書き込む Java 関数を示しています。 この例では、outputItem パラメーターには関数シグネチャではなく @CosmosDBOutput の注釈が付けられています。 出力パラメーター outputItem には、そのテンプレート パラメーターの型として ToDoItem オブジェクトの一覧が含まれています。 OutputBinding<T> を使用すると、関数で Azure Cosmos DB にドキュメントを書き込むためのバインディングを利用しながら、関数の呼び出し元に JSON または XML ドキュメントなどの異なる値を返すこともできるようになります。

    @FunctionName("WriteMultipleDocsOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<List<ToDoItem>> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate documents
        List<ToDoItem> items = new ArrayList<>();

        for (int i = 0; i < 5; i ++) {
          // Generate random ID
          final int id = Math.abs(new Random().nextInt());

          // Create ToDoItem
          ToDoItem item = new ToDoItem(String.valueOf(id), name);

          items.add(item);
        }

        // Set outputItem's value to the list of POJOs to be saved
        outputItem.setValue(items);
        context.getLogger().info("Document to be saved: " + items);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Documents created successfully.")
                      .build();
    }

Java 関数ランタイム ライブラリで、Azure Cosmos DB に書き込まれるパラメーター上で @CosmosDBOutput 注釈を使用します。 注釈パラメーターの型は OutputBinding<T> にするようにします。ここで、T は Java のネイティブ型または POJO のどちらかです。

次の例は、次の形式で JSON を受信するキューの、ストレージ キューによってトリガーされる TypeScript 関数を示しています。

{
    "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"
}

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

import { app, InvocationContext, output } from '@azure/functions';

interface MyQueueItem {
    name: string;
    employeeId: string;
    address: string;
}

interface MyCosmosItem {
    id: string;
    name: string;
    employeeId: string;
    address: string;
}

export async function storageQueueTrigger1(queueItem: MyQueueItem, context: InvocationContext): Promise<MyCosmosItem> {
    return {
        id: `${queueItem.name}-${queueItem.employeeId}`,
        name: queueItem.name,
        employeeId: queueItem.employeeId,
        address: queueItem.address,
    };
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'inputqueue',
    connection: 'MyStorageConnectionAppSetting',
    return: output.cosmosDB({
        databaseName: 'MyDatabase',
        collectionName: 'MyCollection',
        createIfNotExists: true,
        connectionStringSetting: 'MyAccount_COSMOSDB',
    }),
    handler: storageQueueTrigger1,
});

複数のドキュメントを出力するには、1 つのオブジェクトではなく配列を返します。 次に例を示します。

return [
    {
        id: 'John Henry-123456',
        name: 'John Henry',
        employeeId: '123456',
        address: 'A town nearby',
    },
    {
        id: 'John Doe-123457',
        name: 'John Doe',
        employeeId: '123457',
        address: 'A town far away',
    },
];

次の例は、次の形式で JSON を受信するキューの、ストレージ キューによってトリガーされる JavaScript 関数を示しています。

{
    "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"
}

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

const { app, output } = require('@azure/functions');

const cosmosOutput = output.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    createIfNotExists: true,
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'inputqueue',
    connection: 'MyStorageConnectionAppSetting',
    return: cosmosOutput,
    handler: (queueItem, context) => {
        return {
            id: `${queueItem.name}-${queueItem.employeeId}`,
            name: queueItem.name,
            employeeId: queueItem.employeeId,
            address: queueItem.address,
        };
    },
});

複数のドキュメントを出力するには、1 つのオブジェクトではなく配列を返します。 次に例を示します。

return [
    {
        id: 'John Henry-123456',
        name: 'John Henry',
        employeeId: '123456',
        address: 'A town nearby',
    },
    {
        id: 'John Doe-123457',
        name: 'John Doe',
        employeeId: '123457',
        address: 'A town far away',
    },
];

次の例は、出力バインドを使用して Azure Cosmos DB にデータを書き込む方法を示しています。 バインドは、関数の構成ファイル (functions.json) で宣言され、キュー メッセージからデータを取得して Azure Cosmos DB ドキュメントに書き込みます。

{ 
  "name": "EmployeeDocument",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "createIfNotExists": true,
  "connectionStringSetting": "MyStorageConnectionAppSetting",
  "direction": "out" 
}

run.ps1 ファイルで、関数から返されるオブジェクトは、データベース内で保持されている EmployeeDocument オブジェクトにマップされます。

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name EmployeeDocument -Value @{ 
    id = $QueueItem.name + '-' + $QueueItem.employeeId 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
}

次の例は、関数の出力としてドキュメントを Azure Cosmos DB データベースに書き込む方法を示しています。 この例は、v1 と v2 のどちらの Python プログラミング モデルを使用するかによって異なります。

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route()
@app.cosmos_db_output(arg_name="documents", 
                      database_name="DB_NAME",
                      collection_name="COLLECTION_NAME",
                      create_if_not_exists=True,
                      connection_string_setting="CONNECTION_SETTING")
def main(req: func.HttpRequest, documents: func.Out[func.Document]) -> func.HttpResponse:
    request_body = req.get_body()
    documents.set(func.Document.from_json(request_body))
    return 'OK'

属性

インプロセスと分離ワーカー プロセスの C# ライブラリの両方で、属性を使って関数を定義します。 C# スクリプトでは、C# スクリプト ガイドで説明されているように、代わりに function.json 構成ファイルを使用します。

属性のプロパティ 説明
接続 監視対象の Azure Cosmos DB アカウントへの接続方法を指定するアプリの設定または設定のコレクションの名前。 詳細については、「接続」を参照してください。
DatabaseName 監視対象のコンテナーを含む Azure Cosmos DB データベースの名前。
ContainerName 監視対象のコンテナーの名前。
CreateIfNotExists コンテナーが存在しない場合に作成するかどうかを示すブール値。 新しいコンテナーは予約されたスループットで作成され、それがコストに影響を与えるため、既定値は false です。 詳細については、 価格に関するページを参照してください。
PartitionKey CreateIfNotExists が true の場合は、作成されるコンテナーのパーティション キーのパスを定義します。 バインディング パラメーターを含めることもできます。
ContainerThroughput CreateIfNotExists が true の場合は、作成されるコンテナーのスループットを定義します。
PreferredLocations (省略可能) Azure Cosmos DB サービスの geo レプリケートされたデータベース アカウントの優先される場所 (リージョン) を定義します。 複数の値はコンマで区切る必要があります。 たとえば、East US,South Central US,North Europe のようにします。

デコレータ

Python v2 プログラミング モデルにのみ適用されます。

デコレータを使用して定義された Python v2 関数の場合、cosmos_db_output に次のプロパティがあります。

プロパティ 説明
arg_name 変更されるドキュメントの一覧を表す、関数コードで使用する変数の名前。
database_name 監視されているコレクションを使用する Azure Cosmos DB データベースの名前。
collection_name 監視対象の Azure Cosmos DB コレクションの名前。
create_if_not_exists データベースとコレクションが存在しない場合に作成する必要があるかどうかを示すブール値。
connection_string_setting 監視対象の Azure Cosmos DB の接続文字列。

function.json を使用して定義された Python 関数については、「構成」セクションを参照してください。

注釈

Java 関数ランタイム ライブラリから、Azure Cosmos DB に書き込むパラメーターで @CosmosDBOutput 注釈を使用します。 この注釈では、次のプロパティがサポートされます。

構成

"Python v1 プログラミング モデルにのみ適用されます。"

次の表では、output.cosmosDB() メソッドに渡される options オブジェクトに対して設定できるプロパティについて説明します。 type、direction、name の各プロパティは v4 モデルには適用されません。

次の表では、function.json ファイルで設定するバインド構成のプロパティについて説明します。これらのプロパティは、拡張機能バージョンによって異なります。

function.json のプロパティ 説明
connection 監視対象の Azure Cosmos DB アカウントへの接続方法を指定するアプリの設定または設定のコレクションの名前。 詳細については、「接続」を参照してください。
databaseName 監視対象のコンテナーを含む Azure Cosmos DB データベースの名前。
containerName 監視対象のコンテナーの名前。
createIfNotExists コンテナーが存在しない場合に作成するかどうかを示すブール値。 新しいコンテナーは予約されたスループットで作成され、それがコストに影響を与えるため、既定値は false です。 詳細については、 価格に関するページを参照してください。
partitionKey createIfNotExists が true の場合は、作成されるコンテナーのパーティション キーのパスを定義します。 バインディング パラメーターを含めることもできます。
containerThroughput createIfNotExists が true の場合は、作成されるコンテナーのスループットを定義します。
preferredLocations (省略可能) Azure Cosmos DB サービスの geo レプリケートされたデータベース アカウントの優先される場所 (リージョン) を定義します。 複数の値はコンマで区切る必要があります。 たとえば、「 East US,South Central US,North Europe 」のように入力します。

完全な例については、セクションの例を参照してください。

使用法

既定では、関数の出力パラメーターに書き込むと、ドキュメントがデータベースに作成されます。 出力パラメーターに渡される JSON オブジェクトで id プロパティを指定することにより、出力ドキュメントのドキュメント ID を指定する必要があります。

Note

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

Cosmos DB 出力バインドでサポートされるパラメーターの型は、Functions ランタイムのバージョン、拡張機能パッケージのバージョン、使用される C# のモダリティによって異なります。

関数で 1 つのドキュメントに書き込む場合、Cosmos DB の出力バインドは次の型にバインドできます。

Type 説明
JSON シリアル化可能な型 ドキュメントの JSON コンテンツを表すオブジェクト。 Functions は、単純な従来の CLR オブジェクト (POCO) 型を JSON データにシリアル化しようとします。

関数で複数のドキュメントに書き込む場合、Cosmos DB の出力バインドは次の型にバインドできます。

Type 説明
T[] (T は JSON シリアル化可能な型) 複数のドキュメントを含む配列。 各エントリは 1 つのドキュメントを表します。

その他の出力シナリオでは、Microsoft.Azure.Cosmos から直接型を作成して使用します。

接続

connectionStringSetting/connection プロパティと leaseConnectionStringSetting/leaseConnection プロパティは、アプリを Azure Cosmos DB に接続する方法を指定する環境構成への参照です。 以下を指定できます。

  • 接続文字列を含むアプリケーション設定の名前。
  • まとめて ID ベースの接続を定義する、複数のアプリケーション設定の共有プレフィックスの名前。 このオプションは、connectionの connection および leaseConnection バージョンでのみ使用できます。

構成された値が、1 つの設定に完全一致し、プレフィックスがその他の設定とも一致する場合は、完全一致が使用されます。

接続文字列

お使いのデータベース アカウントの接続文字列を、バインディング構成の接続プロパティで指定した値と同じ名前のアプリケーション設定に格納する必要があります。

ID ベースの接続

バージョン 4.x 以降の拡張機能をお使いの場合は、シークレットを含む接続文字列を使う代わりに、アプリで Microsoft Entra ID を使用できます。 これを行うには、トリガーおよびバインディング構成の接続プロパティにマップされる共通のプレフィックスに設定を定義します。

このモードでは、拡張機能に次のプロパティが必要です。

プロパティ 環境変数テンプレート 説明 値の例
アカウント エンドポイント <CONNECTION_NAME_PREFIX>__accountEndpoint Azure Cosmos DB アカウント エンドポイント URI。 https://<database_account_name>.documents.azure.com:443/

接続をカスタマイズするには、プロパティを追加設定します。 「ID ベース接続に共通のプロパティ」を参照してください。

Azure Functions サービスでホストされている場合、ID ベースの接続では、マネージド ID が使用されます。 ユーザー割り当て ID を credential および clientID プロパティで指定できますが、システム割り当て ID が既定で使用されます。 リソース ID を使用したユーザー割り当て ID の構成はサポートされていないことに注意してください。 ローカル開発などの他のコンテキストで実行する場合は、代わりに開発者 ID が使用されますが、カスタマイズすることもできます。 ID ベースの接続によるローカル開発に関するページをご覧ください。

ID にアクセス許可を付与する

使用されている ID が何であれ、目的のアクションを実行するためのアクセス許可が必要です。 ほとんどの Azure では、これはそれらのアクセス許可を提供する組み込みロールまたはカスタム ロールを使って、Azure RBAC でロールを割り当てる必要があることを意味します。

重要

すべてのコンテキストに必要ではない一部のアクセス許可がターゲット サービスによって公開される場合があります。 可能であれば、最小限の特権の原則に従い、必要な特権だけを ID に付与します。 たとえば、アプリがデータ ソースからの読み取りのみを行う必要がある場合は、読み取りアクセス許可のみを持つロールを使用します。 サービスへの書き込みも可能なロールを割り当てることは、読み取り操作に対するアクセス許可が過剰になるため、不適切です。 同様に、ロールの割り当てが、読み取る必要のあるリソースだけに限定されていることを確認する必要があります。

Cosmos DB では、データ操作に Azure RBAC は使われません。 代わりに、同様の概念に基づいて構築された Cosmos DB の組み込み RBAC システムが使われます。 実行時にデータベース アカウントへのアクセスを提供するロールの割り当てを作成する必要があります。 所有者のような Azure RBAC 管理ロールでは十分ではありません。 次の表は、通常の操作で Azure Cosmos DB の拡張機能を使用するときに推奨される組み込みのロールを示しています。 アプリケーションでは、記述したコードに基づいて追加のアクセス許可が必要になる場合があります。

[バインドの種類] 組み込みロールの例 1
トリガー 2 Cosmos DB 組み込みデータ共同作成者
入力バインド Cosmos DB 組み込みデータ リーダー
出力バインド Cosmos DB 組み込みデータ共同作成者

1 これらのロールは、Azure RBAC ロールの割り当てでは使用できません。 これらのロールの割り当て方法について詳しくは、Cosmos DB の組み込み RBAC システムに関するドキュメントをご覧ください。

2 ID を使うと、Cosmos DB はコンテナーの作成を管理操作として扱います。 トリガーのデータ プレーン操作としては使用できません。 関数を設定する前に、トリガーで必要なコンテナー (リース コンテナーを含む) を作成する必要があります。

例外とリターン コード

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

次のステップ