Durable Functions のバインド (Azure Functions)

[アーティクル]
04/07/2023

Durable Functions 拡張機能には、オーケストレーター関数、エンティティ関数、アクティビティ関数の実行を制御する 3 つの新しいトリガーのバインドが導入されています。 Durable Functions ランタイムのクライアントとして機能する出力バインドも導入されています。

記事の冒頭で Durable Functions の開発言語を必ず選択してください。

重要

この記事は、Durable Functions 用の Python v1 および Python v2 の両方のプログラミングモデルをサポートしています。

Python v2 プログラミングモデル

Durable Functions は、新しい Python v2 プログラミングモデルでサポートされています。 v2 モデルを使用するには、PyPI パッケージ azure-functions-durable、バージョン 1.2.2 またはそれ以降のバージョンである Durable Functions SDK をインストールする必要があります。 Durable Functions で v2 モデルを使用するには、アプリが拡張機能バンドルバージョン 4.x を参照していることを host.json で確認する必要もあります。

Durable Functions SDK for Python リポジトリでフィードバックや提案を提供することができます。

オーケストレーショントリガー

オーケストレーショントリガーを使用して、永続的なオーケストレーター関数を作成できます。このトリガーは、新しいオーケストレーションインスタンスのスケジュールが設定されたときと、既存のオーケストレーションインスタンスでイベントが受信されたときに実行されます。オーケストレーター関数がトリガーされる可能性があるイベントの例としては、永続的なタイマーの有効期限、アクティビティ関数の応答、外部クライアントによって発生したイベントがあります。

.NET で関数を作成すると、OrchestrationTriggerAttribute .NET 属性を使用して、オーケストレーショントリガーが構成されます。

Java の場合、@DurableOrchestrationTrigger 注釈はオーケストレーショントリガーの構成に使用されます。

オーケストレーター関数を記述するとき、オーケストレーショントリガーは、function.json ファイルの bindings 配列の次の JSON オブジェクトによって定義されます。

{
    "name": "<Name of input parameter in function signature>",
    "orchestration": "<Optional - name of the orchestration>",
    "type": "orchestrationTrigger",
    "direction": "in"
}

orchestration は、クライアントがこのオーケストレーター関数の新しいインスタンスを開始するときに使用する必要がある、オーケストレーションの名前です。このプロパティは省略可能です。指定されない場合は関数の名前が使用されます。

Azure Function では、Python の 2 つのプログラミングモデルがサポートされています。オーケストレーショントリガーを定義する方法は、選択したプログラミングモデルによって異なります。

Python v2 プログラミングモデルでは、orchestration_trigger デコレーターを直接 Python 関数コード内で使用してオーケストレーショントリガーを定義することができます。

v2 モデルでは、Durable Functions のトリガーとバインドには DFApp のインスタンスからアクセスします。これは、FunctionApp のサブクラスであり、Durable Functions 固有のデコレーターを追加でエクスポートします。

Python v1 プログラミングモデルでオーケストレーター関数を記述するとき、オーケストレーショントリガーは、function.json ファイルの bindings 配列の次の JSON オブジェクトによって定義されます。

{
    "name": "<Name of input parameter in function signature>",
    "orchestration": "<Optional - name of the orchestration>",
    "type": "orchestrationTrigger",
    "direction": "in"
}

orchestration は、クライアントがこのオーケストレーター関数の新しいインスタンスを開始するときに使用する必要がある、オーケストレーションの名前です。このプロパティは省略可能です。指定されない場合は関数の名前が使用されます。

内部的には、このトリガーバインドによって、オーケストレーション開始イベント、永続的なタイマーの有効期限のイベント、アクティビティ関数の応答イベント、他の関数によって発生した外部イベントなど、新しいオーケストレーションイベントについて、構成された永続ストアがポーリングされます。

トリガーの動作

オーケストレーショントリガーについての注意事項を次に示します。

シングルスレッド - 1 つのホストインスタンスのすべてのオーケストレーター関数の実行で単一のディスパッチャースレッドが使用されます。このため、オーケストレーター関数コードが効率的であり、I/O の実行がないことを保証することが重要です。さらに、このスレッドが、Durable Functions 固有のタスクの種類のために待機しているとき以外は、非同期操作を行わないことを保証することも重要です。
有害メッセージの処理 - オーケストレーショントリガーでは、有害メッセージはサポートされません。
メッセージの可視性 - オーケストレーショントリガーメッセージはキューから削除され、構成可能な期間にわたって非表示を保持します。これらのメッセージの可視性は、関数アプリが正常に実行されている限り、自動的に更新されます。
戻り値 - 戻り値は JSON にシリアル化され、Azure Table Storage のオーケストレーション履歴テーブルに保存されます。これらの戻り値は、オーケストレーションクライアントのバインドによるクエリを実行できます。これについては、後で説明します。

警告

オーケストレーター関数は、オーケストレーショントリガーのバインドを除いて、入力または出力バインドを使用しないでください。これらのバインドはシングルスレッドルールと I/O ルールに従っていない可能性があるため、これらのバインドを実行すると、Durable Task 拡張機能で問題が発生する可能性があります。他のバインドを使用する場合は、オーケストレーター関数から呼び出されたアクティビティ関数にそれらを追加します。オーケストレーター関数のコーディングの制約について詳しくは、「オーケストレーター関数のコードの制約」のドキュメントをご覧ください。

警告

オーケストレーター関数を async で宣言してはなりません。

トリガーの使用方法

オーケストレーショントリガーのバインドは、入力と出力の両方をサポートします。入力と出力の処理に関する注意事項を次に示します。

入力 - オーケストレーショントリガーは、コンテキスト入力オブジェクトを介してアクセスされる入力を使用して呼び出すことができます。すべての入力は、JSON にシリアル化できる必要があります。
出力 - オーケストレーショントリガーは、入力と同じように出力値をサポートします。関数の戻り値は、出力値を割り当てるために使用され、JSON にシリアル化できる必要があります。

トリガーサンプル

最もシンプルな "Hello World" オーケストレーター関数のコードの例を次に示します。この例のオーケストレーターでは、実際にはタスクはスケジュールされません。

トリガーを定義するために使用される特定の属性は、C# 関数をインプロセスで実行しているか、分離されたワーカープロセスで実行しているかによって異なります。

インプロセス
分離プロセス

[FunctionName("HelloWorld")]
public static string Run([OrchestrationTrigger] IDurableOrchestrationContext context)
{
    string name = context.GetInput<string>();
    return $"Hello {name}!";
}

Note

前のコードは Durable Functions 2.x 用です。 Durable Functions 1.x の場合、IDurableOrchestrationContext の代わりに DurableOrchestrationContext を使用する必要があります。バージョン間の相違点の詳細については、Durable Functions のバージョンに関する記事を参照してください。

[Function("HelloWorld")]
public static string Run([OrchestrationTrigger] TaskOrchestrationContext context, string name)
{
    return $"Hello {name}!";
}

Note

インプロセスと .NET 分離の両方の Durable Functions で、オーケストレーション入力は context.GetInput<T>() を介して抽出できます。ただし、NET 分離では、上に示すようにパラメーターとして指定される入力もサポートされます。入力バインディングでは、バインディング属性がなく、他の入力バインディングで既に扱う既知の型 (つまり、FunctionContext) ではない最初のパラメーターにバインドされます。

const df = require("durable-functions");

module.exports = df.orchestrator(function*(context) {
    const name = context.df.getInput();
    return `Hello ${name}!`;
});

Note

ライブラリ durable-functions によって、ジェネレーター関数の終了時に同期 context.done メソッドの呼び出しが処理されます。

import azure.functions as func
import azure.durable_functions as df

myApp = df.DFApp(http_auth_level=func.AuthLevel.ANONYMOUS)

@myApp.orchestration_trigger(context_name="context")
def my_orchestrator(context):
    result = yield context.call_activity("Hello", "Tokyo")
    return result

import azure.durable_functions as df

def orchestrator_function(context: df.DurableOrchestrationContext):
    input = context.get_input()
    return f"Hello {input['name']}!"

main = df.Orchestrator.create(orchestrator_function)

param($Context)

$InputData = $Context.Input
$InputData

@FunctionName("HelloWorldOrchestration")
public String helloWorldOrchestration(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    return String.format("Hello %s!", ctx.getInput(String.class));
}

オーケストレーター関数の大半はアクティビティ関数を呼び出すため、"Hello World" の例でアクティビティ関数を呼び出す方法を示します。

インプロセス
分離プロセス

[FunctionName("HelloWorld")]
public static async Task<string> Run(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    string name = context.GetInput<string>();
    string result = await context.CallActivityAsync<string>("SayHello", name);
    return result;
}

Note

[Function("HelloWorld")]
public static async Task<string> Run(
    [OrchestrationTrigger] TaskOrchestrationContext context, string name)
{
    string result = await context.CallActivityAsync<string>("SayHello", name);
    return result;
}

const df = require("durable-functions");

module.exports = df.orchestrator(function*(context) {
    const name = context.df.getInput();
    const result = yield context.df.callActivity("SayHello", name);
    return result;
});

@FunctionName("HelloWorld")
public String helloWorldOrchestration(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    String input = ctx.getInput(String.class);
    String result = ctx.callActivity("SayHello", input, String.class).await();
    return result;
}

アクティビティトリガー

アクティビティトリガーを使用すると、オーケストレーター関数によって呼び出される関数 (アクティビティ関数と呼ばれる) を作成できます。

アクティビティトリガーは ActvityTriggerAttribute .NET 属性を使用して構成されます。

アクティビティトリガーは、@DurableActivityTrigger 注釈を使用して構成されます。

アクティビティトリガーは、function.json の bindings 配列の次の JSON オブジェクトによって定義されます。

{
    "name": "<Name of input parameter in function signature>",
    "activity": "<Optional - name of the activity>",
    "type": "activityTrigger",
    "direction": "in"
}

activity はアクティビティの名前です。この値は、オーケストレーター関数がこのアクティビティ関数を呼び出すために使用する名前です。このプロパティは省略可能です。指定されない場合は関数の名前が使用されます。

アクティビティトリガーを定義する方法は、選択したプログラミングモデルによって異なります。

activity_trigger デコレーターを直接 Python 関数コードで使用する。

アクティビティトリガーは、function.json の bindings 配列の次の JSON オブジェクトによって定義されます。

{
    "name": "<Name of input parameter in function signature>",
    "activity": "<Optional - name of the activity>",
    "type": "activityTrigger",
    "direction": "in"
}

activity はアクティビティの名前です。この値は、オーケストレーター関数がこのアクティビティ関数を呼び出すために使用する名前です。このプロパティは省略可能です。指定されない場合は関数の名前が使用されます。

内部的には、このトリガーバインドによって、構成された永続ストアに対して新しいアクティビティ実行イベントがポーリングされます。

トリガーの動作

アクティビティトリガーに関する注意事項を次に示します。

スレッド処理 - オーケストレーショントリガーとは異なり、アクティビティトリガーにはスレッド処理と I/O に関する制限はありません。それらは、標準的な関数と同様に扱うことができます。
有害メッセージの処理 - アクティビティトリガーには、有害メッセージのサポートはありません。
メッセージの可視性 - アクティビティトリガーメッセージはキューから削除され、構成可能な期間にわたって非表示を保持します。これらのメッセージの可視性は、関数アプリが正常に実行されている限り、自動的に更新されます。
戻り値 - 戻り値は JSON にシリアル化され、構成された永続ストアに保存されます。

トリガーの使用方法

アクティビティトリガーのバインドは、オーケストレーショントリガーと同じように、入力と出力の両方をサポートします。入力と出力の処理に関する注意事項を次に示します。

入力 - アクティビティトリガーは、オーケストレーター関数からの入力を使用して呼び出すことができます。すべての入力は、JSON にシリアル化できる必要があります。
出力 - アクティビティ関数は、入力と同じように出力値をサポートします。関数の戻り値は、出力値を割り当てるために使用され、JSON にシリアル化できる必要があります。
メタデータ - .NET アクティビティ関数を string instanceId パラメーターにバインドして、呼び出し元オーケストレーションのインスタンス ID を取得できます。

トリガーサンプル

シンプルな SayHello アクティビティ関数のコードの例を次に示します。

インプロセス
分離プロセス

[FunctionName("SayHello")]
public static string SayHello([ActivityTrigger] IDurableActivityContext helloContext)
{
    string name = helloContext.GetInput<string>();
    return $"Hello {name}!";
}

.NET の ActivityTriggerAttribute バインディングの既定のパラメーター型は IDurableActivityContext (Durable Functions v1 の場合は DurableActivityContext) です。ただし、.NET アクティビティトリガーは、JSON にシリアル化できる型 (プリミティブ型を含む) への直接的なバインドもサポートしているため、同じ関数を次のように単純化できます。

[FunctionName("SayHello")]
public static string SayHello([ActivityTrigger] string name)
{
    return $"Hello {name}!";
}

.NET 分離ワーカーでは、入力を表すシリアル化可能な型のみが [ActivityTrigger] でサポートされています。

[Function("SayHello")]
public static string SayHello([ActivityTrigger] string name)
{
    return $"Hello {name}!";
}

module.exports = async function(context) {
    return `Hello ${context.bindings.name}!`;
};

JavaScript のバインドは、追加のパラメーターとして渡すこともできるため、同じ関数を次のように単純化できます。

module.exports = async function(context, name) {
    return `Hello ${name}!`;
};

import azure.functions as func
import azure.durable_functions as df

myApp = df.DFApp(http_auth_level=func.AuthLevel.ANONYMOUS)

@myApp.activity_trigger(input_name="myInput")
def my_activity(myInput: str):
    return "Hello " + myInput

def main(name: str) -> str:
    return f"Hello {name}!"

param($name)

"Hello $name!"

@FunctionName("SayHello")
public String sayHello(@DurableActivityTrigger(name = "name") String name) {
    return String.format("Hello %s!", name);
}

入出力バインドを使用する

アクティビティトリガーのバインドに加えて、通常の入出力バインドを使用できます。

たとえば、アクティビティのバインディングへの入力を取得することや、Event Hubs 出力バインディングを使用してイベントハブにメッセージを送信することができます。

{
  "bindings": [
    {
      "name": "message",
      "type": "activityTrigger",
      "direction": "in"
    },
    {
      "type": "eventHub",
      "name": "outputEventHubMessage",
      "connection": "EventhubConnectionSetting",
      "eventHubName": "eh_messages",
      "direction": "out"
  }
  ]
}

module.exports = async function (context) {
    context.bindings.outputEventHubMessage = context.bindings.message;
};

オーケストレーションクライアント

オーケストレーションクライアントのバインドを使用すると、オーケストレーター関数とやりとりする関数を記述できます。これらの関数は、多くの場合、クライアント関数と呼ばれます。たとえば、次のようにオーケストレーションインスタンスを操作できます。

インスタンスを開始する。
インスタンスの状態をクエリする。
インスタンスを終了する。
インスタンスの実行中にイベントを送信する。
インスタンスの履歴を消去します。

DurableClientAttribute 属性 (Durable Functions v1.x の場合は OrchestrationClientAttribute) を使用して、オーケストレーションクライアントにバインドできます。

@DurableClientInput 注釈を使用してオーケストレーションクライアントにバインドできます。

持続的クライアントトリガーは、function.json の bindings 配列の次の JSON オブジェクトによって定義されます。

{
    "name": "<Name of input parameter in function signature>",
    "taskHub": "<Optional - name of the task hub>",
    "connectionName": "<Optional - name of the connection string app setting>",
    "type": "orchestrationClient",
    "direction": "in"
}

taskHub - 複数の関数アプリが同じストレージアカウントを共有するが、相互に分離する必要があるシナリオで使用されます。指定されていない場合は、host.json の既定値が使用されます。この値は、ターゲットのオーケストレーター関数によって使用される値と一致している必要があります。
connectionName - ストレージアカウント接続文字列を含むアプリ設定の名前。この接続文字列で表されるストレージアカウントは、ターゲットのオーケストレーター関数によって使用されるものと同じにする必要があります。指定されない場合は、関数アプリの既定のストレージアカウント接続文字列が使用されます。

Note

ほとんどの場合、これらのプロパティを省略し、既定の動作を使用することをお勧めします。

持続的クライアントトリガーを定義する方法は、選択したプログラミングモデルによって異なります。

durable_client_input デコレーターを直接 Python 関数コードで使用する。

持続的クライアントトリガーは、function.json の bindings 配列の次の JSON オブジェクトによって定義されます。

{
    "name": "<Name of input parameter in function signature>",
    "taskHub": "<Optional - name of the task hub>",
    "connectionName": "<Optional - name of the connection string app setting>",
    "type": "orchestrationClient",
    "direction": "in"
}

taskHub - 複数の関数アプリが同じストレージアカウントを共有するが、相互に分離する必要があるシナリオで使用されます。指定されていない場合は、host.json の既定値が使用されます。この値は、ターゲットのオーケストレーター関数によって使用される値と一致している必要があります。
connectionName - ストレージアカウント接続文字列を含むアプリ設定の名前。この接続文字列で表されるストレージアカウントは、ターゲットのオーケストレーター関数によって使用されるものと同じにする必要があります。指定されない場合は、関数アプリの既定のストレージアカウント接続文字列が使用されます。

Note

ほとんどの場合、これらのプロパティを省略し、既定の動作を使用することをお勧めします。

クライアントの使用

通常は IDurableClient (Durable Functions v1.x の場合は DurableOrchestrationClient) にバインドします。これにより、Durable Functions によってサポートされるすべてのオーケストレーションクライアント API にフルアクセスできます。

通常は DurableClientContext クラスにバインドします。

言語に固有の SDK を使用してクライアントオブジェクトにアクセスする必要があります。

"HelloWorld" オーケストレーションを開始する、キューによってトリガーされる関数の例を次に示します。

インプロセス
分離プロセス

[FunctionName("QueueStart")]
public static Task Run(
    [QueueTrigger("durable-function-trigger")] string input,
    [DurableClient] IDurableOrchestrationClient starter)
{
    // Orchestration input comes from the queue message content.
    return starter.StartNewAsync<string>("HelloWorld", input);
}

Note

前記の C# コードは Durable Functions 2.x 用です。 Durable Functions 1.x では、DurableClient 属性の代わりに OrchestrationClient 属性を使用する必要があります。また、IDurableOrchestrationClient ではなく DurableOrchestrationClient パラメーター型を使用する必要があります。バージョン間の相違点の詳細については、Durable Functions のバージョンに関する記事を参照してください。

[Function("QueueStart")]
public static Task Run(
    [QueueTrigger("durable-function-trigger")] string input,
    [DurableClient] DurableTaskClient client)
{
    // Orchestration input comes from the queue message content.
    return client.ScheduleNewOrchestrationInstanceAsync("HelloWorld", input);
}

function.json

{
  "bindings": [
    {
      "name": "input",
      "type": "queueTrigger",
      "queueName": "durable-function-trigger",
      "direction": "in"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ]
}

index.js

const df = require("durable-functions");

module.exports = async function (context) {
    const client = df.getClient(context);
    return instanceId = await client.startNew("HelloWorld", undefined, context.bindings.input);
};

run.ps1

param([string] $input, $TriggerMetadata)

$InstanceId = Start-DurableOrchestration -FunctionName $FunctionName -Input $input

import azure.functions as func
import azure.durable_functions as df

myApp = df.DFApp(http_auth_level=func.AuthLevel.ANONYMOUS)

@myApp.route(route="orchestrators/{functionName}")
@myApp.durable_client_input(client_name="client")
async def durable_trigger(req: func.HttpRequest, client):
    function_name = req.route_params.get('functionName')
    instance_id = await client.start_new(function_name)
    response = client.create_check_status_response(req, instance_id)
    return response

function.json

{
  "bindings": [
    {
      "name": "input",
      "type": "queueTrigger",
      "queueName": "durable-function-trigger",
      "direction": "in"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ]
}

__init__.py

import json
import azure.functions as func
import azure.durable_functions as df

async def main(msg: func.QueueMessage, starter: str) -> None:
    client = df.DurableOrchestrationClient(starter)
    payload = msg.get_body().decode('utf-8')
    instance_id = await client.start_new("HelloWorld", client_input=payload)

function.json

{
  "bindings": [
    {
      "name": "input",
      "type": "queueTrigger",
      "queueName": "durable-function-trigger",
      "direction": "in"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ]
}

run.ps1

param([string]$InputData, $TriggerMetadata)

$InstanceId = Start-DurableOrchestration -FunctionName 'HelloWorld' -Input $InputData

@FunctionName("QueueStart")
public void queueStart(
        @QueueTrigger(name = "input", queueName = "durable-function-trigger", connection = "Storage") String input,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    // Orchestration input comes from the queue message content.
    durableContext.getClient().scheduleNewOrchestrationInstance("HelloWorld", input);
}

インスタンスの開始の詳細については、インスタンスの管理に関する記事を参照してください。

エンティティトリガー

エンティティトリガーを使用すると、エンティティ関数を作成できます。このトリガーでは、特定のエンティティインスタンスのイベントの処理がサポートされています。

Note

エンティティトリガーは、Durable Functions 2.x 以降で使用できます。

内部的には、このトリガーバインドによって、実行する必要がある新しいエンティティ操作について、構成された永続ストアがポーリングされます。

エンティティトリガーは EntityTriggerAttribute .NET 属性を使用して構成されます。

エンティティトリガーは、function.json の bindings 配列の次の JSON オブジェクトによって定義されます。

{
    "name": "<Name of input parameter in function signature>",
    "entityName": "<Optional - name of the entity>",
    "type": "entityTrigger",
    "direction": "in"
}

既定では、エンティティの名前は関数の名前です。

注意

エンティティトリガーは、Java ではまだサポートされていません。

エンティティトリガーを定義する方法は、選択したプログラミングモデルによって異なります。

entity_trigger デコレーターを直接 Python 関数コードで使用する。

エンティティトリガーは、function.json の bindings 配列の次の JSON オブジェクトによって定義されます。

{
    "name": "<Name of input parameter in function signature>",
    "entityName": "<Optional - name of the entity>",
    "type": "entityTrigger",
    "direction": "in"
}

既定では、エンティティの名前は関数の名前です。

トリガーの動作

エンティティトリガーに関する注意事項を次に示します。

シングルスレッド: 特定のエンティティに対する操作を処理する場合は、単一のディスパッチャースレッドが使用されます。複数のメッセージが同時に 1 つのエンティティに送信される場合、操作は一度に 1 つずつ処理されます。
有害メッセージの処理 - エンティティトリガーには、有害メッセージのサポートはありません。
メッセージの可視性 - エンティティトリガーメッセージはキューから削除され、構成可能な期間にわたって非表示を保持します。これらのメッセージの可視性は、関数アプリが正常に実行されている限り、自動的に更新されます。
戻り値 - エンティティ関数では戻り値をサポートしません。特定の API を使用することで、状態を保存したり、オーケストレーションに値を渡したりすることができます。

実行中にエンティティに対して行われた状態の変更はいずれも、実行の完了後も自動的に保持されます。

エンティティトリガーの定義と操作の詳細と例について詳しくは、持続エンティティに関するドキュメントをご覧ください。

エンティティクライアント

エンティティクライアントバインディングを使用すると、エンティティ関数を非同期的にトリガーできます。これらの関数は、クライアント関数と呼ばれることもあります。

.NET クラスライブラリ関数の DurableClientAttribute .NET 属性を使用することで、エンティティクライアントにバインドできます。

Note

また、[DurableClientAttribute] を使用して、オーケストレーションクライアントにバインドすることもできます。

エンティティクライアントは、function.json の bindings 配列の次の JSON オブジェクトによって定義されます。

{
    "name": "<Name of input parameter in function signature>",
    "taskHub": "<Optional - name of the task hub>",
    "connectionName": "<Optional - name of the connection string app setting>",
    "type": "durableClient",
    "direction": "in"
}

taskHub - 複数の関数アプリが同じストレージアカウントを共有するが、相互に分離する必要があるシナリオで使用されます。指定されていない場合は、host.json の既定値が使用されます。この値は、ターゲットのエンティティ関数によって使用される値と一致している必要があります。
connectionName - ストレージアカウント接続文字列を含むアプリ設定の名前。この接続文字列で表されるストレージアカウントは、ターゲットのエンティティ関数によって使用されるものと同じにする必要があります。指定されない場合は、関数アプリの既定のストレージアカウント接続文字列が使用されます。

Note

ほとんどの場合、オプションのプロパティを省略し、既定の動作を使用することをお勧めします。

エンティティクライアントを定義する方法は、選択したプログラミングモデルによって異なります。

durable_client_input デコレーターを直接 Python 関数コードで使用する。

エンティティクライアントは、function.json の bindings 配列の次の JSON オブジェクトによって定義されます。

{
    "name": "<Name of input parameter in function signature>",
    "taskHub": "<Optional - name of the task hub>",
    "connectionName": "<Optional - name of the connection string app setting>",
    "type": "durableClient",
    "direction": "in"
}

taskHub - 複数の関数アプリが同じストレージアカウントを共有するが、相互に分離する必要があるシナリオで使用されます。指定されていない場合は、host.json の既定値が使用されます。この値は、ターゲットのエンティティ関数によって使用される値と一致している必要があります。
connectionName - ストレージアカウント接続文字列を含むアプリ設定の名前。この接続文字列で表されるストレージアカウントは、ターゲットのエンティティ関数によって使用されるものと同じにする必要があります。指定されない場合は、関数アプリの既定のストレージアカウント接続文字列が使用されます。

Note

ほとんどの場合、オプションのプロパティを省略し、既定の動作を使用することをお勧めします。

注意

エンティティクライアントは、Java ではまだサポートされていません。

エンティティをクライアントとして操作する方法の詳細と例について詳しくは、持続エンティティに関するドキュメントをご覧ください。

host.json 設定

Durable Functions の構成設定。

Note

Durable Functions のすべてのメジャーバージョンは、Azure Functions ランタイムのすべてのバージョンでサポートされています。ただし、host.json 構成のスキーマは、Azure Functions ランタイムのバージョンと使用する Durable Functions 拡張機能のバージョンによって若干異なります。次の例は、Azure Functions 2.0 および3.0 で使用するためのものです。どちらの例でも、Azure Functions 1.0 を使用している場合、使用可能な設定は同じですが、host.json の "durableTask" セクションは、"extensions" の下のフィールドとしてではなく、host.json 構成のルートに配置する必要があります。

Durable Functions 2.x
Durable Functions 1.x

{
 "extensions": {
  "durableTask": {
    "hubName": "MyTaskHub",
    "storageProvider": {
      "connectionStringName": "AzureWebJobsStorage",
      "controlQueueBatchSize": 32,
      "controlQueueBufferThreshold": 256,
      "controlQueueVisibilityTimeout": "00:05:00",
      "maxQueuePollingInterval": "00:00:30",
      "partitionCount": 4,
      "trackingStoreConnectionStringName": "TrackingStorage",
      "trackingStoreNamePrefix": "DurableTask",
      "useLegacyPartitionManagement": true,
      "useTablePartitionManagement": false,
      "workItemQueueVisibilityTimeout": "00:05:00",
    },
    "tracing": {
      "traceInputsAndOutputs": false,
      "traceReplayEvents": false,
    },
    "notifications": {
      "eventGrid": {
        "topicEndpoint": "https://topic_name.westus2-1.eventgrid.azure.net/api/events",
        "keySettingName": "EventGridKey",
        "publishRetryCount": 3,
        "publishRetryInterval": "00:00:30",
        "publishEventTypes": [
          "Started",
          "Completed",
          "Failed",
          "Terminated"
        ]
      }
    },
    "maxConcurrentActivityFunctions": 10,
    "maxConcurrentOrchestratorFunctions": 10,
    "extendedSessionsEnabled": false,
    "extendedSessionIdleTimeoutInSeconds": 30,
    "useAppLease": true,
    "useGracefulShutdown": false,
    "maxEntityOperationBatchSize": 50,
    "storeInputsInOrchestrationHistory": false
  }
 }
}

{
  "extensions": {
    "durableTask": {
      "hubName": "MyTaskHub",
      "controlQueueBatchSize": 32,
      "partitionCount": 4,
      "controlQueueVisibilityTimeout": "00:05:00",
      "workItemQueueVisibilityTimeout": "00:05:00",
      "maxConcurrentActivityFunctions": 10,
      "maxConcurrentOrchestratorFunctions": 10,
      "maxQueuePollingInterval": "00:00:30",
      "azureStorageConnectionStringName": "AzureWebJobsStorage",
      "trackingStoreConnectionStringName": "TrackingStorage",
      "trackingStoreNamePrefix": "DurableTask",
      "traceInputsAndOutputs": false,
      "logReplayEvents": false,
      "eventGridTopicEndpoint": "https://topic_name.westus2-1.eventgrid.azure.net/api/events",
      "eventGridKeySettingName":  "EventGridKey",
      "eventGridPublishRetryCount": 3,
      "eventGridPublishRetryInterval": "00:00:30",
      "eventGridPublishEventTypes": ["Started", "Completed", "Failed", "Terminated"]
    }
  }
}

タスクハブの名前は、先頭文字をアルファベットとする必要があります。また、使用できるのはアルファベットと数値だけです。指定しない場合、関数アプリのデフォルトタスクハブ名は TestHubName です。詳細については、タスクハブに関するページをご覧ください。

プロパティ	Default	説明
hubName	TestHubName (Durable Functions 1.x を使用している場合は DurableFunctionsHub)	代替タスクハブ名を使用すると、複数の Durable Functions アプリケーションが同じストレージバックエンドを使用している場合でも、これらのアプリケーションを互いに分離できます。
controlQueueBatchSize	32	コントロールキューから一度にプルするメッセージの数。
controlQueueBufferThreshold	Python の従量課金プラン: 32 JavaScript および C# の従量課金プラン: 128 専用プランまたは Premium プラン: 256	一度にメモリにバッファー処理できる制御キューメッセージの数。その時点で、ディスパッチャーは、追加のメッセージがデキューされるまで待機します。
partitionCount	4	コントロールキューのパーティション数。 1 から 16 までの正の整数を使用できます。
controlQueueVisibilityTimeout	5 分	デキューされたコントロールキューメッセージの表示タイムアウト。
workItemQueueVisibilityTimeout	5 分	デキューされた作業項目キューメッセージの表示タイムアウト。
maxConcurrentActivityFunctions	従量課金プラン: 10 専用プランまたは Premium プラン: 現在のマシンのプロセッサ数の 10 倍	1 つのホストインスタンスで同時に処理できるアクティビティ関数の最大数。
maxConcurrentOrchestratorFunctions	従量課金プラン: 5 専用プランまたは Premium プラン: 現在のマシンのプロセッサ数の 10 倍	1 つのホストインスタンスで同時に処理できるオーケストレーター関数の最大数。
maxQueuePollingInterval	30 秒	コントロールおよび作業項目キューの最大ポーリング間隔 (hh:mm:ss 形式)。値が高くなるほどメッセージ処理の待機時間が長くなる可能性があります。値が低くなるほどストレージコストが高くなる可能性があります。これは、ストレージトランザクションが増加するからです。
connectionName (2.7.0 以降) connectionStringName (2.x) azureStorageConnectionStringName (1.x)	AzureWebJobsStorage	基になる Azure Storage リソースへの接続方法を指定するアプリ設定または設定コレクションの名前。 1 つのアプリ設定を指定する場合は、Azure Storage 接続文字列にする必要があります。
trackingStoreConnectionName (2.7.0 以降) azureStorageConnectionStringName		履歴およびインスタンステーブルへの接続方法を指定するアプリ設定または設定コレクションの名前。 1 つのアプリ設定を指定する場合は、Azure Storage 接続文字列にする必要があります。指定しない場合は、`connectionStringName` (Durable 2.x) または `azureStorageConnectionStringName` (Durable 1.x) 接続が使用されます。
trackingStoreNamePrefix		`trackingStoreConnectionStringName` が指定されているときに履歴テーブルとインスタンステーブルに使用されるプレフィックス。設定されていない場合、既定のプレフィックス値は `DurableTask` になります。 `trackingStoreConnectionStringName` が指定されていない場合、履歴テーブルとインスタンステーブルは `hubName` 値をプレフィックスとして使用し、`trackingStoreNamePrefix` の設定はすべて無視されます。
traceInputsAndOutputs	false	関数呼び出しの入力と出力をトレースするかどうかを示す値。関数の実行イベントをトレースした場合の既定の動作では、関数呼び出しのシリアル化された入力および出力のバイト数が記録されます。この動作により、ログが肥大化することも、機密情報が誤って公開されることもなく、入力および出力に関する最小限の情報が示されます。このプロパティを true に設定すると、既定の関数ログ記録によって、関数の入力および出力の内容全体がログに記録されます。
traceReplayEvents	false	オーケストレーションの再生イベントを Application Insights に書き込むかどうかを示す値。
eventGridTopicEndpoint		Azure Event Grid カスタムトピックエンドポイントの URL。このプロパティが設定されている場合は、オーケストレーションのライフサイクル通知イベントがこのエンドポイントに発行されます。このプロパティは、アプリ設定の解決をサポートします。
eventGridKeySettingName		`EventGridTopicEndpoint` での Azure Event Grid カスタムトピックによる認証に使用されるキーを含むアプリ設定の名前。
eventGridPublishRetryCount	0	Event Grid トピックへの発行が失敗した場合に再試行する回数。
eventGridPublishRetryInterval	5 分	Event Grid の発行を再試行する間隔 (hh:mm:ss 形式)。
eventGridPublishEventTypes		Event Grid に発行するイベントの種類の一覧。指定されていない場合は、すべてのイベントの種類が発行されます。指定できる値は、`Started`、`Completed`、`Failed`、`Terminated` です。
useAppLease	true	`true` に設定すると、アプリはタスクハブメッセージを処理する前にアプリレベルの BLOB リースを取得する必要があります。詳細については、ディザスターリカバリーと geo ディストリビューションに関するドキュメントを参照してください。 v2.3.0 以降で利用可能です。
useLegacyPartitionManagement	false	`false` に設定した場合は、スケールアウト時に関数の実行が重複する可能性を抑えるパーティション管理アルゴリズムを使用します。v2.3.0 以降で使用できます。
useTablePartitionManagement	false	`true` に設定すると、Azure Storage V2 アカウントのコストを削減するために設計されたパーティション管理アルゴリズムが使用されます。 v2.10.0 以降で利用可能です。この機能は現在プレビュー段階であり、まだ従量課金プランとの互換性はありません。
useGracefulShutdown	false	(プレビュー) 正常なシャットダウンを有効にして、ホストのシャットダウンでインプロセス関数の実行が失敗する可能性を減らします。
maxEntityOperationBatchSize(2.6.1)	従量課金プラン: 50 専用プランまたは Premium プラン: 5000	バッチとして処理されるエンティティ操作の最大数。 1 に設定すると、バッチ処理は無効になり、各操作メッセージは個別の関数呼び出しによって処理されます。
storeInputsInOrchestrationHistory	false	`true` に設定すると、履歴テーブルにアクティビティ入力を保存するように Durable Task Framework に指示します。こうすると、オーケストレーション履歴のクエリを実行するときにアクティビティ関数の入力を表示できるようになります。

これらの設定の多くはパフォーマンスの最適化を目的としています。詳細については、「パフォーマンスと拡張性」を参照してください。

次のステップ

インスタンス管理用の組み込みの HTTP API リファレンス

Durable Functions のバインド (Azure Functions)

Python v2 プログラミング モデル

オーケストレーション トリガー

トリガーの動作

トリガーの使用方法

トリガー サンプル

アクティビティ トリガー

トリガーの動作

トリガーの使用方法

トリガー サンプル

入出力バインドを使用する

オーケストレーション クライアント

クライアントの使用

エンティティ トリガー

トリガーの動作

エンティティ クライアント

host.json 設定

次のステップ

その他のリソース

Python v2 プログラミングモデル

オーケストレーショントリガー

トリガーサンプル

アクティビティトリガー

トリガーサンプル

オーケストレーションクライアント

エンティティトリガー

エンティティクライアント