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

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

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

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

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

このバインドに関しては現在、Goのサポートは利用できません。

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

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

次の例は、キュー ストレージ内のメッセージからのデータを含むドキュメントをデータベースに追加する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 のいずれかです。

次の例は、出力バインドを使用して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'

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "cosmosDB",
      "direction": "out",
      "name": "doc",
      "databaseName": "demodb",
      "collectionName": "data",
      "createIfNotExists": "true",
      "connectionStringSetting": "AzureCosmosDBConnectionString"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    }
  ]
}

import azure.functions as func

def main(req: func.HttpRequest, doc: func.Out[func.Document]) -> func.HttpResponse:

    request_body = req.get_body()

    doc.set(func.Document.from_json(request_body))

    return 'OK'

属性

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

デコレータ

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

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

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

注釈

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

• 名前
• connectionStringSetting
• databaseName
• collectionName
• createIfNotExists
• dataType
• partitionKey
• preferredLocations
• useMultipleWriteLocations（複数の書き込み場所を使用）

構成

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

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

出力関数パラメーターは、 func.Out[func.Document]として定義する必要があります。 詳細については、 出力例 を参照してください。

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