Azure Functions 2.x 以降のAzure Cosmos DB トリガー

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

Python v1 プログラミング モデルでは、関数フォルダー内の別の function.json ファイルにバインドを定義する必要があります。 詳細については、Python 開発者ガイドを参照してください。

分離ワーカー プロセス クラス ライブラリでコンパイルされた C# 関数は、ランタイムから分離されたプロセスで実行されます。

インプロセス クラス ライブラリは、Functions ランタイムと同じプロセスで実行されるコンパイル済みの C# 関数です。

Azure Cosmos DB拡張機能バージョン 4.x 以降を使用するアプリでは、異なる属性プロパティが使用されます。 このセクションでは、これらのプロパティを示します。 この例では、アプリ設定の参照を使用し、エラー処理が含まれています。

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

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

namespace CosmosDBSamplesV2
{
    public static class CosmosTrigger
    {
        [FunctionName("CosmosTrigger")]
        public static void Run([CosmosDBTrigger(
            databaseName: "%COSMOS_DATABASE_NAME%",
            containerName: "%COSMOS_CONTAINER_NAME%",
            Connection = "COSMOS_CONNECTION",
            LeaseContainerName = "leases",
            CreateLeaseContainerIfNotExists = true)]IReadOnlyList<ToDoItem> documents, ILogger log)
        {
            if (documents != null && documents.Count > 0)
            {
                log.LogInformation("Documents modified: {count}", documents.Count);
                foreach (var doc in documents)
                {
                    try
                    {
                        log.LogInformation("Processing document Id: {id}", doc.id);
                        // Add your business logic here
                    }
                    catch (Exception ex)
                    {
                        log.LogError(ex, "Error processing document {id}", doc.id);
                        // Continue processing remaining documents
                    }
                }
            }
        }

        [FunctionName("health")]
        public static IActionResult HealthCheck(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "health")] HttpRequest req)
        {
            return new OkResult();
        }
    }
}

前の例では、ハードコードされた値ではなく、アプリ設定の参照 (%VAR_NAME%) を使用しています。

アプリの設定

ID ベースの接続用に次のアプリケーション設定を構成します。

ローカル開発

ローカル開発の場合は、 local.settings.json ファイルを作成します。

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet",
        "COSMOS_DATABASE_NAME": "my-database",
        "COSMOS_CONTAINER_NAME": "my-container",
        "COSMOS_CONNECTION__accountEndpoint": "https://mycosmosdb.documents.azure.com:443/"
    }
}

ローカル開発の前提条件:

• Azure CLIaz login 完了
• Azurite ストレージ エミュレーター の実行 (azurite --silent)

次の例は、指定したデータベースとコレクションで挿入または更新が行われるときに実行される C# 関数 を示しています。

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

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

この例では、アプリ設定の参照を使用し、エラー処理を含めます。 まず、モデルの種類を定義します。

public class ToDoItem
{
    public string? Id { get; set; }
    public string? Description { get; set; }
}

次の関数は、指定したデータベースとコンテナーで挿入または更新が行われるときに実行されます。

[Function("CosmosTrigger")]
public void Run([CosmosDBTrigger(
    databaseName: "%COSMOS_DATABASE_NAME%",
    containerName: "%COSMOS_CONTAINER_NAME%",
    Connection = "COSMOS_CONNECTION",
    LeaseContainerName = "leases",
    CreateLeaseContainerIfNotExists = true)] IReadOnlyList<ToDoItem> documents,
    FunctionContext context)
{
    if (documents is not null && documents.Any())
    {
        _logger.LogInformation("Documents modified: {count}", documents.Count);
        foreach (var doc in documents)
        {
            try
            {
                _logger.LogInformation("Processing document Id: {id}", doc.Id);
                // Add your business logic here
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error processing document {id}", doc.Id);
                // Continue processing remaining documents
            }
        }
    }
}

[Function("health")]
public IActionResult HealthCheck([HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "health")] HttpRequest req)
{
    return new OkResult();
}

前の例では、ハードコードされた値ではなく、アプリ設定の参照 (%VAR_NAME%) を使用しています。 構成の詳細については、インプロセス タブのアプリ設定とローカル開発ガイダンスを参照してください。

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

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

    public string? Text { get; set; }

    public int Number { get; set; }

    public bool Boolean { get; set; }
}

次の例では、Azure Cosmos DB トリガー バインド パラメーターとして IReadOnlyList<T> を使用します。

[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;
}

この例には、次の using ステートメントが必要です。

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

Azure Cosmos DB SDK でスキーマが変更されたため、Azure Cosmos DB拡張機能のバージョン 4.x には、Java関数の azure-functions-java-library V3.0.0 が必要です。

    @FunctionName("CosmosDBTriggerFunction")
    public void run(
        @CosmosDBTrigger(
            name = "items",
            databaseName = "ToDoList",
            containerName = "Items",
            leaseContainerName="leases",
            connection = "AzureCosmosDBConnection",
            createLeaseContainerIfNotExists = true
        )
        Object inputItem,
        final ExecutionContext context
    ) {
        context.getLogger().info("Items modified: " + inputItems.size());
    }

    @FunctionName("cosmosDBMonitor")
    public void cosmosDbProcessor(
        @CosmosDBTrigger(name = "items",
            databaseName = "ToDoList",
            collectionName = "Items",
            leaseCollectionName = "leases",
            createLeaseCollectionIfNotExists = true,
            connectionStringSetting = "AzureCosmosDBConnection") String[] items,
            final ExecutionContext context ) {
                context.getLogger().info(items.length + "item(s) is/are changed.");
            }

次の例は、Azure Cosmos DB トリガー TypeScript 関数を示しています。 この関数は、Azure Cosmos DBレコードが追加または変更されたときにログ メッセージを書き込みます。

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

export async function cosmosDBTrigger1(documents: unknown[], context: InvocationContext): Promise<void> {
    context.log(`Cosmos DB function processed ${documents.length} documents`);
}

app.cosmosDB('cosmosDBTrigger1', {
    connection: '<connection-app-setting>',
    databaseName: 'Tasks',
    containerName: 'Items',
    createLeaseContainerIfNotExists: true,
    handler: cosmosDBTrigger1,
});

TypeScript のサンプルは、モデル v3 については記載されていません。

次の例は、Azure Cosmos DB トリガー JavaScript 関数を示しています。 この関数は、Azure Cosmos DBレコードが追加または変更されたときにログ メッセージを書き込みます。

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

app.cosmosDB('cosmosDBTrigger1', {
    connection: '<connection-app-setting>',
    databaseName: 'Tasks',
    containerName: 'Items',
    createLeaseContainerIfNotExists: true,
    handler: (documents, context) => {
        context.log(`Cosmos DB function processed ${documents.length} documents`);
    },
});

次の例は、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
}

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseContainerName": "leases",
    "connection": "<connection-app-setting>",
    "databaseName": "Tasks",
    "containerName": "Items",
    "createLeaseContainerIfNotExists": true
}

バインド属性名の一部は、Azure Cosmos DB拡張機能のバージョン 4.x で変更されていることに注意してください。

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

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

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

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseContainerName": "leases",
    "connection": "<connection-app-setting>",
    "databaseName": "Tasks",
    "containerName": "Items",
    "createLeaseContainerIfNotExists": true
}

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="CosmosDBTrigger")
@app.cosmos_db_trigger(arg_name="documents", 
                       database_name="%COSMOS_DATABASE_NAME%", 
                       container_name="%COSMOS_CONTAINER_NAME%",
                       connection="COSMOS_CONNECTION",
                       lease_container_name="leases",
                       create_lease_container_if_not_exists="true")
def cosmos_trigger(documents: func.DocumentList) -> str:
    if documents:
        for doc in documents:
            try:
                logging.info('Processing document id: %s', doc['id'])
                # Add your business logic here
            except Exception as e:
                logging.error('Error processing document %s: %s', doc.get('id', 'unknown'), str(e))
                # Continue processing remaining documents

@app.function_name(name="health")
@app.route(route="health", methods=["GET"])
def health_check(req: func.HttpRequest) -> func.HttpResponse:
    """Health check endpoint for monitoring."""
    return func.HttpResponse("OK", status_code=200)

前の例では、ハードコードされた値ではなく、アプリ設定の参照 (%VAR_NAME%) を使用しています。

アプリの設定

ID ベースの接続用に次のアプリケーション設定を構成します。

ローカル開発

ローカル開発の場合は、 local.settings.json ファイルを作成します。

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "python",
        "COSMOS_DATABASE_NAME": "my-database",
        "COSMOS_CONTAINER_NAME": "my-container",
        "COSMOS_CONNECTION__accountEndpoint": "https://mycosmosdb.documents.azure.com:443/"
    }
}

ローカル開発の前提条件:

• Azure CLIaz login 完了
• Azurite ストレージ エミュレーター の実行 (azurite --silent)

この関数は、Azure Cosmos DBレコードが変更されたときにログ メッセージを書き込みます。 function.json ファイルのバインディング データを次に示します。

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

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseContainerName": "leases",
    "connection": "<connection-app-setting>",
    "databaseName": "Tasks",
    "containerName": "Items",
    "createLeaseContainerIfNotExists": true
}

バインド属性名の一部は、Azure Cosmos DB拡張機能のバージョン 4.x で変更されていることに注意してください。

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

    import logging
    import azure.functions as func


    def main(documents: func.DocumentList) -> str:
        if documents:
            logging.info('First document Id modified: %s', documents[0]['id'])

インプロセス ライブラリでは、Microsoft.Azure.WebJobs 名前空間の CosmosDBTriggerAttribute を使用します。これにより、次のプロパティが定義されます。

インプロセス ライブラリでは、Microsoft.Azure.WebJobs 名前空間の CosmosDBTriggerAttribute を使用します。これにより、次のプロパティが定義されます。

分離されたワーカー プロセス ライブラリでは、Microsoft.Azure.Functions.Worker 名前空間の CosmosDBTriggerAttribute を使用します。これらのプロパティは次のとおりです。

分離されたワーカー プロセス ライブラリでは、Microsoft.Azure.Functions.Worker 名前空間の CosmosDBTriggerAttribute を使用します。これらのプロパティは次のとおりです。

Azure Cosmos DB SDK でスキーマが変更されたため、Azure Cosmos DB拡張機能のバージョン 4.x には、Java関数の azure-functions-java-library V3.0.0 が必要です。

Azure Cosmos DBからデータを読み取るパラメーターには、@CosmosDBTrigger注釈を使用します。 この注釈では、次のプロパティがサポートされます。

Java関数ランタイム ライブラリから、Azure Cosmos DBからデータを読み取るパラメーターに対して @CosmosDBTrigger 注釈を使用します。 この注釈では、次のプロパティがサポートされます。

• name
• connectionStringSetting
• databaseName
• collectionName
• leaseConnectionStringSetting
• leaseDatabaseName
• leaseCollectionName
• createLeaseCollectionIfNotExists
• leasesCollectionThroughput
• leaseCollectionPrefix
• feedPollDelay
• leaseAcquireInterval
• leaseExpirationInterval
• leaseRenewInterval
• checkpointInterval
• checkpointDocumentCount
• maxItemsPerInvocation
• startFromBeginning
• preferredLocations

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

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

サポートされる型の一覧については、「バインドの種類」を参照してください。

サポートされている型の一覧については、「 バインディング型」を参照してください。

関数で 1 つのドキュメントを処理するとき、Cosmos DB トリガーは次の型にバインドできます。

関数でドキュメントのバッチを処理するとき、Cosmos DB トリガーは次の型にバインドできます。

サポートされている型の一覧については、「 バインディング型」を参照してください。