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

  • [アーティクル]

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

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

Note

コレクションがパーティション分割されている場合、検索操作では、パーティション キーの値も指定する必要があります。

重要

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

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

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

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

例

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

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 日に終了します。 完全なサポートのために、アプリを分離ワーカー モデルに移行することを強くお勧めします。

このセクションでは、バージョン 3.x の Azure Cosmos DB 拡張機能と 5.x の Azure Storage 拡張機能を必要とする例について説明します。 関数アプリにない場合は、次の NuGet パッケージへの参照を追加します。

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

[Function(nameof(DocByIdFromJSON))]
public void DocByIdFromJSON(
    [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
    [CosmosDBInput(
        databaseName: "ToDoItems",
        containerName: "Items",
        Connection  = "CosmosDBConnection",
        Id = "{ToDoItemId}",
        PartitionKey = "{ToDoItemPartitionKeyValue}")] ToDoItem toDoItem)
{
    _logger.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

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

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

次の例は、単一のドキュメントを取得する関数を示しています。 この関数は、ストレージ キュー内の JSON メッセージによってトリガーされます。 キュー トリガーにより、取得する ID とパーティション キー値を含む、ToDoItemLookup 型のオブジェクトに JSON が解析されます。 その ID とパーティション キー値は、指定されたデータベースとコレクションから ToDoItem ドキュメントを返すために使用されます。

[Function(nameof(DocByIdFromJSON))]
public void DocByIdFromJSON(
    [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
    [CosmosDBInput(
        databaseName: "ToDoItems",
        containerName: "Items",
        Connection  = "CosmosDBConnection",
        Id = "{ToDoItemId}",
        PartitionKey = "{ToDoItemPartitionKeyValue}")] ToDoItem toDoItem)
{
    _logger.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

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

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

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

public class ToDoItem {

  private String id;
  private String description;

  public String getId() {
    return id;
  }

  public String getDescription() {
    return description;
  }

  @Override
  public String toString() {
    return "ToDoItem={id=" + id + ",description=" + description + "}";
  }
}

HTTP トリガー、クエリ文字列からの ID の検索 - String パラメーター

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

public class DocByIdFromQueryString {

    @FunctionName("DocByIdFromQueryString")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{Query.id}",
              partitionKey = "{Query.partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            Optional<String> item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));

        // Convert and display
        if (!item.isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            // return JSON from Cosmos. Alternatively, we can parse the JSON string
            // and return an enriched JSON object.
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item.get())
                          .build();
        }
    }
}

Java 関数ランタイム ライブラリで、その値が Azure Cosmos DB に由来する関数パラメーター上で @CosmosDBInput 注釈を使用します。 この注釈は、Java のネイティブ型、POJO、または Optional<T> を使用した null 許容値で使用できます。

HTTP トリガー、クエリ文字列からの ID の検索 - POJO パラメーター

次の例は、単一のドキュメントを取得する Java 関数を示しています。 関数は、クエリ文字列を使用して検索のための ID とパーティション キー値を指定する HTTP 要求によってトリガーされます。 その ID とパーティション キー値は、指定されたデータベースとコレクションからドキュメントを取得するために使用されます。 このドキュメントはその後、前に作成した ToDoItem POJO のインスタンスに変換され、引数として関数に渡されます。

public class DocByIdFromQueryStringPojo {

    @FunctionName("DocByIdFromQueryStringPojo")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{Query.id}",
              partitionKey = "{Query.partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Item from the database is " + item);

        // Convert and display
        if (item == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item)
                          .build();
        }
    }
}

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

次の例は、単一のドキュメントを取得する Java 関数を示しています。 関数は、ルート パラメーターを使用して検索のための ID とパーティション キー値を指定する HTTP 要求によってトリガーされます。 その ID とパーティション キー値は、指定されたデータベースとコレクションからドキュメントを取得し、Optional<String> として返すために使用されます。

public class DocByIdFromRoute {

    @FunctionName("DocByIdFromRoute")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems/{partitionKeyValue}/{id}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{id}",
              partitionKey = "{partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            Optional<String> item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));

        // Convert and display
        if (!item.isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            // return JSON from Cosmos. Alternatively, we can parse the JSON string
            // and return an enriched JSON object.
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item.get())
                          .build();
        }
    }
}

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

次の例は、単一のドキュメントを取得する Java 関数を示しています。 この関数は、ルート パラメーターを使用して検索する ID を指定する HTTP 要求によってトリガーされます。 クエリ条件によっては多数のドキュメントが返される可能性があるため、その ID は、指定されたデータベースとコレクションからドキュメントを取得し、結果セットを ToDoItem[] に変換するために使用されます。

Note

ID だけでクエリを実行する必要がある場合、前の例のように、参照を使用することをお勧めします。要求ユニットの消費が少なくなります。 ポイント読み取り操作 (GET) は ID によるクエリより効率性に優れています。

public class DocByIdFromRouteSqlQuery {

    @FunctionName("DocByIdFromRouteSqlQuery")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems2/{id}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              sqlQuery = "select * from Items r where r.id = {id}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem[] item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Items from the database are " + item);

        // Convert and display
        if (item == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item)
                          .build();
        }
    }
}

HTTP トリガー、ルート データからの複数のドキュメントの取得、SqlQuery を使用

次の例は、複数のドキュメントを取得する Java 関数を示しています。 この関数は、ルート パラメーター desc を使用して description フィールドで検索する文字列を指定する HTTP 要求によってトリガーされます。 この検索用語は、指定されたデータベースとコレクションからドキュメントのコレクションを取得し、結果セットを ToDoItem[] に変換して、それを引数として関数に渡すために使用されます。

public class DocsFromRouteSqlQuery {

    @FunctionName("DocsFromRouteSqlQuery")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems3/{desc}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              sqlQuery = "select * from Items r where contains(r.description, {desc})",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem[] items,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Number of items from the database is " + (items == null ? 0 : items.length));

        // Convert and display
        if (items == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("No documents found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(items)
                          .build();
        }
    }
}

このセクションには、次の例が含まれています。各例では、さまざまなソースから ID 値を指定して単一のドキュメントを読み取ります。

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

次の例は、単一のドキュメントを読み取り、そのドキュメントのテキスト値を更新する TypeScript 関数を示しています。

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    id: '{queueTrigger}',
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

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

interface MyDocument {
    text: string;
}

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    const doc = <MyDocument>context.extraInputs.get(cosmosInput);
    doc.text = 'This was updated!';
    context.extraOutputs.set(cosmosOutput, doc);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    extraOutputs: [cosmosOutput],
    handler: storageQueueTrigger1,
});

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

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

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{Query.id}',
    partitionKey: '{Query.partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface ToDoDocument {
    description: string;
}

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const toDoItem = <ToDoDocument>context.extraInputs.get(cosmosInput);
    if (!toDoItem) {
        return {
            status: 404,
            body: 'ToDo item not found',
        };
    } else {
        return {
            body: `Found ToDo item, Description=${toDoItem.description}`,
        };
    }
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [cosmosInput],
    handler: httpTrigger1,
});

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

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

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{id}',
    partitionKey: '{partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface ToDoDocument {
    description: string;
}

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const toDoItem = <ToDoDocument>context.extraInputs.get(cosmosInput);
    if (!toDoItem) {
        return {
            status: 404,
            body: 'ToDo item not found',
        };
    } else {
        return {
            body: `Found ToDo item, Description=${toDoItem.description}`,
        };
    }
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    route: 'todoitems/{partitionKeyValue}/{id}',
    extraInputs: [cosmosInput],
    handler: httpTrigger1,
});

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

次の例は、SQL クエリで指定されている複数のドキュメントを、キュー トリガーを使用してクエリ パラメーターをカスタマイズすることで取得する TypeScript 関数を示しています。

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

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDb',
    collectionName: 'MyCollection',
    sqlQuery: 'SELECT * from c where c.departmentId = {departmentId}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface MyDocument {}

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    const documents = <MyDocument[]>context.extraInputs.get(cosmosInput);
    for (const document of documents) {
        // operate on each document
    }
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    handler: storageQueueTrigger1,
});

このセクションには、次の例が含まれています。各例では、さまざまなソースから ID 値を指定して単一のドキュメントを読み取ります。

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

次の例は、単一のドキュメントを読み取り、そのドキュメントのテキスト値を更新する JavaScript 関数を示しています。

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    id: '{queueTrigger}',
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

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

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    extraOutputs: [cosmosOutput],
    handler: (queueItem, context) => {
        const doc = context.extraInputs.get(cosmosInput);
        doc.text = 'This was updated!';
        context.extraOutputs.set(cosmosOutput, doc);
    },
});

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

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

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{Query.id}',
    partitionKey: '{Query.partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [cosmosInput],
    handler: (request, context) => {
        const toDoItem = context.extraInputs.get(cosmosInput);
        if (!toDoItem) {
            return {
                status: 404,
                body: 'ToDo item not found',
            };
        } else {
            return {
                body: `Found ToDo item, Description=${toDoItem.Description}`,
            };
        }
    },
});

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

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

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{id}',
    partitionKey: '{partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    route: 'todoitems/{partitionKeyValue}/{id}',
    extraInputs: [cosmosInput],
    handler: (request, context) => {
        const toDoItem = context.extraInputs.get(cosmosInput);
        if (!toDoItem) {
            return {
                status: 404,
                body: 'ToDo item not found',
            };
        } else {
            return {
                body: `Found ToDo item, Description=${toDoItem.Description}`,
            };
        }
    },
});

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

次の例は、SQL クエリで指定されている複数のドキュメントを、キュー トリガーを使用してクエリ パラメーターをカスタマイズすることで取得する JavaScript 関数を示しています。

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

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDb',
    collectionName: 'MyCollection',
    sqlQuery: 'SELECT * from c where c.departmentId = {departmentId}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    handler: (queueItem, context) => {
        const documents = context.extraInputs.get(cosmosInput);
        for (const document of documents) {
            // operate on each document
        }
    },
});

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

次の例は、1 つの Azure Cosmos DB ドキュメントを読み取り、更新する方法を示しています。 ドキュメントの一意識別子は、キュー メッセージの JSON 値によって提供されます。

Azure Cosmos DB 入力バインドは、関数の構成ファイル (function.json) で見つかったバインドの一覧の先頭に表示されます。

{
  "name": "InputDocumentIn",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "id": "{queueTrigger_payload_property}",
  "partitionKey": "{queueTrigger_payload_property}",
  "connectionStringSetting": "CosmosDBConnection",
  "direction": "in"
},
{
  "name": "InputDocumentOut",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "createIfNotExists": false,
  "partitionKey": "{queueTrigger_payload_property}",
  "connectionStringSetting": "CosmosDBConnection",
  "direction": "out"
}

run.ps1 ファイルには、受信ドキュメントを読み取り、変更を出力する PowerShell コードが含まれます。

param($QueueItem, $InputDocumentIn, $TriggerMetadata)

$Document = $InputDocumentIn 
$Document.text = 'This was updated!'

Push-OutputBinding -Name InputDocumentOut -Value $Document

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

次の例は、Web API から 1 つの Azure Cosmos DB ドキュメントを読み取り、更新する方法を示しています。 ドキュメントの一意識別子は、バインドの "Id": "{Query.Id}" プロパティで定義されているように、HTTP 要求の querystring パラメーターを通じて提供されます。

Azure Cosmos DB 入力バインドは、関数の構成ファイル (function.json) で見つかったバインドの一覧の先頭に表示されます。

{ 
  "bindings": [ 
    { 
      "type": "cosmosDB", 
      "name": "ToDoItem", 
      "databaseName": "ToDoItems", 
      "collectionName": "Items", 
      "connectionStringSetting": "CosmosDBConnection", 
      "direction": "in", 
      "Id": "{Query.id}", 
      "PartitionKey": "{Query.partitionKeyValue}" 
    },
    { 
      "authLevel": "anonymous", 
      "name": "Request", 
      "type": "httpTrigger", 
      "direction": "in", 
      "methods": [ 
        "get", 
        "post" 
      ] 
    }, 
    { 
      "name": "Response", 
      "type": "http", 
      "direction": "out" 
    },
  ], 
  "disabled": false 
}

run.ps1 ファイルには、受信ドキュメントを読み取り、変更を出力する PowerShell コードが含まれます。

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

Write-Host 'PowerShell HTTP trigger function processed a request'

if (-not $ToDoItem) { 
    Write-Host 'ToDo item not found'

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::NotFound 
        Body = $ToDoItem.Description 
    })

} else {

    Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::OK 
        Body = $ToDoItem.Description 
    }) 
}

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

次の例は、Web API から 1 つの Azure Cosmos DB ドキュメントを読み取り、更新する方法を示しています。 ドキュメントの一意識別子は、route パラメーターを通じて提供されます。 route パラメーターは、HTTP 要求バインドの route プロパティで定義され、Azure Cosmos DB "Id": "{Id}" バインド プロパティで参照されます。

Azure Cosmos DB 入力バインドは、関数の構成ファイル (function.json) で見つかったバインドの一覧の先頭に表示されます。

{ 
  "bindings": [ 
    { 
      "type": "cosmosDB", 
      "name": "ToDoItem", 
      "databaseName": "ToDoItems", 
      "collectionName": "Items", 
      "connectionStringSetting": "CosmosDBConnection", 
      "direction": "in", 
      "Id": "{id}", 
      "PartitionKey": "{partitionKeyValue}" 
    },
    { 
      "authLevel": "anonymous", 
      "name": "Request", 
      "type": "httpTrigger", 
      "direction": "in", 
      "methods": [ 
        "get", 
        "post" 
      ], 
      "route": "todoitems/{partitionKeyValue}/{id}" 
    }, 
    { 
      "name": "Response", 
      "type": "http", 
      "direction": "out" 
    }
  ], 
  "disabled": false 
}

run.ps1 ファイルには、受信ドキュメントを読み取り、変更を出力する PowerShell コードが含まれます。

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

Write-Host 'PowerShell HTTP trigger function processed a request'

if (-not $ToDoItem) { 
    Write-Host 'ToDo item not found'

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::NotFound 
        Body = $ToDoItem.Description 
    })

} else { 
    Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::OK 
        Body = $ToDoItem.Description 
    }) 
}

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

次の例は、複数の Azure Cosmos DB ドキュメントを読み取る方法を示しています。 関数の構成ファイル (function.json) によって、sqlQuery を含むバインド プロパティが定義されます。 sqlQuery プロパティに指定された SQL ステートメントによって、関数に提供されるドキュメントのセットが選択されます。

{ 
  "name": "Documents", 
  "type": "cosmosDB", 
  "direction": "in", 
  "databaseName": "MyDb", 
  "collectionName": "MyCollection", 
  "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}", 
  "connectionStringSetting": "CosmosDBConnection" 
}

run1.ps1 ファイルには、受信ドキュメントを読み取る PowerShell コードが含まれます。

param($QueueItem, $Documents, $TriggerMetadata)

foreach ($Document in $Documents) { 
    # operate on each document 
}

このセクションには、次の例が含まれています。各例では、さまざまなソースから ID 値を指定して単一のドキュメントを読み取ります。

この例は、v1 と v2 のどちらの Python プログラミング モデルを使用するかによって異なります。

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

次の例は、Azure Cosmos DB 入力バインドを示しています。 この関数は、1 つのドキュメントを読み取って、そのドキュメントのテキスト値を更新します。

import logging
import azure.functions as func

app = func.FunctionApp()

@app.queue_trigger(arg_name="msg", 
                   queue_name="outqueue", 
                   connection="AzureWebJobsStorage")
@app.cosmos_db_input(arg_name="documents", 
                     database_name="MyDatabase",
                     collection_name="MyCollection",
                     id="{msg.payload_property}",
                     partition_key="{msg.payload_property}",
                     connection_string_setting="MyAccount_COSMOSDB")
@app.cosmos_db_output(arg_name="outputDocument", 
                      database_name="MyDatabase",
                      collection_name="MyCollection",
                      connection_string_setting="MyAccount_COSMOSDB")
def test_function(msg: func.QueueMessage,
                  inputDocument: func.DocumentList, 
                  outputDocument: func.Out[func.Document]):
     document = documents[id]
     document["text"] = "This was updated!"
     doc = inputDocument[0]
     doc["text"] = "This was updated!"
     outputDocument.set(doc)
     print(f"Updated document.")

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

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

現時点では、v2 に対応するサンプルはありません。

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

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

現時点では、v2 に対応するサンプルはありません。

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

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

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

現時点では、v2 に対応するサンプルはありません。

属性

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

属性のプロパティ 説明
接続 クエリ対象の Azure Cosmos DB アカウントへの接続方法を指定するアプリの設定または設定のコレクションの名前。 詳細については、「接続」を参照してください。
DatabaseName 監視対象のコンテナーを含む Azure Cosmos DB データベースの名前。
ContainerName 監視対象のコンテナーの名前。
PartitionKey 参照用のパーティション キー値を指定します。 バインディング パラメーターを含めることもできます。 パーティション分割されたコンテナーの検索に必要です。
Id 取得するドキュメントの ID。 このプロパティは、バインド式をサポートしています。 Id と SqlQuery プロパティの両方は設定しないでください。 いずれも設定しなかった場合は、コンテナー全体が取得されます。
SqlQuery 複数のドキュメントを取得するときに使用する Azure Cosmos DB SQL クエリ。 このプロパティは、次の例のように実行時のバインドをサポートします。SELECT * FROM c where c.departmentId = {departmentId} Id と SqlQuery プロパティの両方は設定しないでください。 いずれも設定しなかった場合は、コンテナー全体が取得されます。
PreferredLocations (省略可能) Azure Cosmos DB サービスの geo レプリケートされたデータベース アカウントの優先される場所 (リージョン) を定義します。 複数の値はコンマで区切る必要があります。 たとえば、East US,South Central US,North Europe のようにします。

デコレータ

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

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

プロパティ 説明
arg_name 変更されるドキュメントの一覧を表す、関数コードで使用する変数の名前。
database_name 監視されているコレクションを使用する Azure Cosmos DB データベースの名前。
collection_name 監視対象の Azure Cosmos DB コレクションの名前。
connection_string_setting 監視対象の Azure Cosmos DB の接続文字列。
partition_key 監視対象の Azure Cosmos DB のパーティション キー。
id 取得するドキュメントの ID。

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

注釈

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

構成

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

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

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

function.json のプロパティ 説明
type cosmosDB に設定する必要があります。
direction in に設定する必要があります。
name 変更されるドキュメントの一覧を表す、関数コードで使用する変数の名前。
connection 監視対象の Azure Cosmos DB アカウントへの接続方法を指定するアプリの設定または設定コンテナーの名前。 詳細については、「接続」を参照してください。
databaseName 監視対象のコンテナーを含む Azure Cosmos DB データベースの名前。
containerName 監視対象のコンテナーの名前。
partitionKey 参照用のパーティション キー値を指定します。 バインディング パラメーターを含めることもできます。 パーティション分割されたコンテナーの検索に必要です。
id 取得するドキュメントの ID。 このプロパティは、バインド式をサポートしています。 id と sqlQuery プロパティの両方は設定しないでください。 いずれも設定しなかった場合は、コンテナー全体が取得されます。
sqlQuery 複数のドキュメントを取得するときに使用する Azure Cosmos DB SQL クエリ。 このプロパティは、次の例のように実行時のバインドをサポートします。SELECT * FROM c where c.departmentId = {departmentId} id と sqlQuery プロパティの両方は設定しないでください。 いずれも設定しなかった場合は、コンテナー全体が取得されます。
preferredLocations (省略可能) Azure Cosmos DB サービスの geo レプリケートされたデータベース アカウントの優先される場所 (リージョン) を定義します。 複数の値はコンマで区切る必要があります。 たとえば、「 East US,South Central US,North Europe 」のように入力します。

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

使用法

関数が正常に終了すると、入力ドキュメントへの変更がすべて自動的に保持されます。

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

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

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

関数で 1 つのクエリから得た複数のドキュメントを処理するとき、Cosmos DB 入力バインドは次の型にバインドできます。

Type 説明
IEnumerable<T> (T は JSON シリアル化可能な型) クエリによって返されるエンティティの列挙型。 各エントリは 1 つのドキュメントを表します。
CosmosClient1 Cosmos DB アカウントに接続されているクライアント。
Database1 Cosmos DB データベースに接続されているクライアント。
Container1 Cosmos DB コンテナーに接続されているクライアント。

1 これらの型を使用するには、Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 以降と SDK 型バインドの一般的な依存関係を参照する必要があります。

Java 関数ランタイム ライブラリの @CosmosDBInput 注釈によって Azure Cosmos DB データは関数に公開されます。 この注釈は、Java のネイティブ型、POJO、または Optional<T> を使用した null 許容値で使用できます。

context.extraInputs.get() を使用してドキュメントにアクセスします。

関数の終了時にドキュメントへの更新が自動的に行われることはありません。 関数でドキュメントを更新するには、出力バインドを使用します。 詳細については、「PowerShell の例」を参照してください。

データは、DocumentList パラメーターを介して関数から使用できるようになります。 ドキュメントに加えられた変更は、自動的には保存されません。

接続

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

次のステップ