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

  • [アーティクル]

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

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

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

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

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

重要

Python v2 プログラミング モデルは現在プレビュー段階です。

例

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

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

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

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

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

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

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

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

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

キュー トリガー、1 つのドキュメントの書き込み (v4 拡張機能)

Azure Cosmos DB 拡張機能バージョン 4.x 以降を使用しているアプリには、以下に示すように、さまざまな属性プロパティがあります。 次の例は、キュー ストレージからのメッセージで提供されるデータを使用して、ドキュメントをデータベースに追加する C# 関数を示しています。

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

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

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

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

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

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

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

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

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

  • 　　　　インプロセス クラス ライブラリ: Functions ランタイムと同じプロセスで実行されるコンパイル済みの C# 関数。
  • 分離ワーカー プロセス クラス ライブラリ: ランタイムから分離されたワーカー プロセスで実行されるコンパイル済みの C# 関数。 分離ワーカー プロセスは、非 LTS バージョンの .NET および.NET Framework で実行されている C# 関数をサポートするために必要です。
  • C# スクリプト: Azure portal で c# 関数を作成するときに主に使用されます。

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

次の例は、キュー ストレージのメッセージからのデータを使用して、ドキュメントをデータベースに追加する 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 のどちらかです。

次の例は、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": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": true,
    "connectionStringSetting": "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
      });
    };

一括挿入の場合は、オブジェクトを最初に作成してから、stringify 関数を実行します。 JavaScript コードを次に示します。

    module.exports = async function (context) {

        context.bindings.employeeDocument = JSON.stringify([
        {
            "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# スクリプトでは、function.json 構成ファイルを使用します。

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

デコレータ

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

デコレーターを使用して定義された Python v2 関数の場合、cosmos_db_output の次のプロパティ:

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

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

注釈

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

構成

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

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

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

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

使用法

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

Note

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

接続

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

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

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

接続文字列

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

ID ベースの接続

バージョン 4.x 以上の拡張機能を使用する場合は、シークレットを含む接続文字列を使う代わりに、アプリで Azure Active Directory 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 状態コード

次のステップ