Durable Functions のバインド (Azure Functions)Bindings for Durable Functions (Azure Functions)

Durable Functions 拡張機能には、オーケストレーター関数とアクティビティ関数の実行を制御する 2 つの新しいトリガーのバインドが導入されています。The Durable Functions extension introduces two new trigger bindings that control the execution of orchestrator and activity functions. Durable Functions ランタイムのクライアントとして機能する出力バインドも導入されています。It also introduces an output binding that acts as a client for the Durable Functions runtime.

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

オーケストレーション トリガーを使用して、永続的なオーケストレーター関数を作成できます。The orchestration trigger enables you to author durable orchestrator functions. このトリガーは、新しいオーケストレーター関数インスタンスの開始と、タスクのために "待機している" 既存のオーケストレーター関数インスタンスの再開をサポートします。This trigger supports starting new orchestrator function instances and resuming existing orchestrator function instances that are "awaiting" a task.

Azure Functions 用の Visual Studio ツールを使用する場合、オーケストレーション トリガーは、OrchestrationTriggerAttribute .NET 属性を使用して構成されます。When you use the Visual Studio tools for Azure Functions, the orchestration trigger is configured using the OrchestrationTriggerAttribute .NET attribute.

オーケストレーター関数を (Azure ポータルなどで ) スクリプト言語で記述する場合、オーケストレーション トリガーは、function.json ファイルの bindings 配列の次の JSON オブジェクトによって定義されます。When you write orchestrator functions in scripting languages (for example, in the Azure portal), the orchestration trigger is defined by the following JSON object in the bindings array of the function.json file:

{
    "name": "<Name of input parameter in function signature>",
    "orchestration": "<Optional - name of the orchestration>",
    "type": "orchestrationTrigger",
    "direction": "in"
}
  • orchestration はオーケストレーションの名前です。orchestration is the name of the orchestration. これは、クライアントがこのオーケストレーター関数の新しいインスタンスを開始するときに使用する必要がある値です。This is the value that clients must use when they want to start new instances of this orchestrator function. このプロパティは省略可能です。This property is optional. 指定されない場合は関数の名前が使用されます。If not specified, the name of the function is used.

内部的には、このトリガーのバインドは、関数アプリの既定のストレージ アカウントで一連のキューをポーリングします。Internally this trigger binding polls a series of queues in the default storage account for the function app. これらのキューは拡張機能の内部実装の詳細であるため、バインド プロパティに明示的に構成されることはありません。These queues are internal implementation details of the extension, which is why they are not explicitly configured in the binding properties.

トリガーの動作Trigger behavior

オーケストレーション トリガーについての注意事項を次に示します。Here are some notes about the orchestration trigger:

  • シングル スレッド - 1 つのホスト インスタンスのすべてのオーケストレーター関数の実行で単一のディスパッチャー スレッドが使用されます。Single-threading - A single dispatcher thread is used for all orchestrator function execution on a single host instance. このため、オーケストレーター関数が効率的であり、I/O の実行がないことを保証することが重要です。For this reason, it is important to ensure that orchestrator function code is efficient and doesn't perform any I/O. さらに、このスレッドが、Durable Functions 固有のタスクの種類のために待機しているとき以外は、非同期操作を行わないことを保証することも重要です。It is also important to ensure that this thread does not do any async work except when awaiting on Durable Functions-specific task types.
  • 有害メッセージの処理 - オーケストレーション トリガーでは、有害メッセージはサポートされません。Poison-message handling - There is no poison message support in orchestration triggers.
  • メッセージの可視性 - オーケストレーション トリガー メッセージはキューから削除され、構成可能な期間にわたって非表示を保持します。Message visibility - Orchestration trigger messages are dequeued and kept invisible for a configurable duration. これらのメッセージの可視性は、関数アプリが正常に実行されている限り、自動的に更新されます。The visibility of these messages is renewed automatically as long as the function app is running and healthy.
  • 戻り値 - 戻り値は JSON にシリアル化され、Azure Table ストレージのオーケストレーション履歴テーブルに保存されます。Return values - Return values are serialized to JSON and persisted to the orchestration history table in Azure Table storage. これらの戻り値は、オーケストレーション クライアントのバインドによるクエリを実行できます。これについては、後で説明します。These return values can be queried by the orchestration client binding, described later.

警告

オーケストレーター関数は、オーケストレーション トリガーのバインドを除いて、入力または出力バインドを使用しないでください。Orchestrator functions should never use any input or output bindings other than the orchestration trigger binding. これらのバインドはシングル スレッド ルールと I/O ルールに従っていない可能性があるため、これらのバインドを実行すると、Durable Task 拡張機能で問題が発生する可能性があります。Doing so has the potential to cause problems with the Durable Task extension because those bindings may not obey the single-threading and I/O rules.

トリガーの使用方法Trigger usage

オーケストレーション トリガーのバインドは、入力と出力の両方をサポートします。The orchestration trigger binding supports both inputs and outputs. 入力と出力の処理に関する注意事項を次に示します。Here are some things to know about input and output handling:

  • 入力 - オーケストレーション関数は、パラメーター型として DurableOrchestrationContext のみをサポートします。inputs - Orchestration functions support only DurableOrchestrationContext as a parameter type. 関数シグネチャ内で入力を直接逆シリアル化することはサポートされていません。Deserialization of inputs directly in the function signature is not supported. コードでは、GetInput<T> メソッドを使用してオーケストレーター関数の入力をフェッチする必要があります。Code must use the GetInput<T> method to fetch orchestrator function inputs. これらの入力は、JSON にシリアル化できる型にする必要があります。These inputs must be JSON-serializable types.
  • 出力 - オーケストレーション トリガーは、入力と同じように出力値をサポートします。outputs - Orchestration triggers support output values as well as inputs. 関数の戻り値は、出力値を割り当てるために使用され、JSON にシリアル化できる必要があります。The return value of the function is used to assign the output value and must be JSON-serializable. 関数が Task または voidを返した場合は、出力として null 値が保存されます。If a function returns Task or void, a null value will be saved as the output.

トリガー サンプルTrigger sample

最も単純な "Hello World" オーケストレーター関数の例を次に示します。The following is an example of what the simplest "Hello World" orchestrator function might look like:

C#C#

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

JavaScript (Functions v2 のみ)JavaScript (Functions v2 only)

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

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

注意

JavaScript オーケストレーターでは return を使用する必要があります。JavaScript orchestrators should use return. durable-functions ライブラリは、context.done メソッドの呼び出しを管理します。The durable-functions library takes care of calling the context.done method.

オーケストレーター関数の大半はアクティビティ関数を呼び出すため、"Hello World" の例でアクティビティ関数を呼び出す方法を示します。Most orchestrator functions call activity functions, so here is a "Hello World" example that demonstrates how to call an activity function:

C#C#

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

JavaScript (Functions v2 のみ)JavaScript (Functions v2 only)

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

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

アクティビティ トリガーActivity triggers

アクティビティ トリガーを使用して、オーケストレーター関数によって呼び出される関数を作成できます。The activity trigger enables you to author functions that are called by orchestrator functions.

Visual Studio を使用する場合、アクティビティ トリガーは ActvityTriggerAttribute .NET 属性を使用して構成されます。If you're using Visual Studio, the activity trigger is configured using the ActvityTriggerAttribute .NET attribute.

Azure ポータルを使用して開発する場合、アクティビティ トリガーは、function.jsonbindings 配列の次の JSON オブジェクトによって定義されます。If you're using the Azure portal for development, the activity trigger is defined by the following JSON object in the bindings array of function.json:

{
    "name": "<Name of input parameter in function signature>",
    "activity": "<Optional - name of the activity>",
    "type": "activityTrigger",
    "direction": "in"
}
  • activity はアクティビティの名前です。activity is the name of the activity. これは、オーケストレーター関数がこのアクティビティ関数を呼び出すために使用する値です。This is the value that orchestrator functions use to invoke this activity function. このプロパティは省略可能です。This property is optional. 指定されない場合は関数の名前が使用されます。If not specified, the name of the function is used.

内部的には、このトリガーのバインドは、関数アプリの既定のストレージ アカウントでキューをポーリングします。Internally this trigger binding polls a queue in the default storage account for the function app. このキューは拡張機能の内部実装の詳細であるため、バインド プロパティに明示的に構成されることはありません。This queue is an internal implementation detail of the extension, which is why it is not explicitly configured in the binding properties.

トリガーの動作Trigger behavior

アクティビティ トリガーに関する注意事項を次に示します。Here are some notes about the activity trigger:

  • スレッド処理 - オーケストレーション トリガーとは異なり、アクティビティ トリガーにはスレッド処理と I/O に関する制限はありません。Threading - Unlike the orchestration trigger, activity triggers don't have any restrictions around threading or I/O. それらは、標準的な関数と同様に扱うことができます。They can be treated like regular functions.
  • 有害メッセージの処理 - アクティビティ トリガーでは、有害メッセージはサポートされません。Poising-message handling - There is no poison message support in activity triggers.
  • メッセージの可視性 - アクティビティ トリガー メッセージはキューから削除され、構成可能な期間にわたって非表示を保持します。Message visibility - Activity trigger messages are dequeued and kept invisible for a configurable duration. これらのメッセージの可視性は、関数アプリが正常に実行されている限り、自動的に更新されます。The visibility of these messages is renewed automatically as long as the function app is running and healthy.
  • 戻り値 - 戻り値は JSON にシリアル化され、Azure Table ストレージのオーケストレーション履歴テーブルに保存されます。Return values - Return values are serialized to JSON and persisted to the orchestration history table in Azure Table storage.

警告

アクティビティ関数のストレージ バックエンドは実装の詳細であるため、ユーザー コードはこれらのストレージ エンティティと直接対話すべきではありません。The storage backend for activity functions is an implementation detail and user code should not interact with these storage entities directly.

トリガーの使用方法Trigger usage

アクティビティ トリガーのバインドは、オーケストレーション トリガーと同じように、入力と出力の両方をサポートします。The activity trigger binding supports both inputs and outputs, just like the orchestration trigger. 入力と出力の処理に関する注意事項を次に示します。Here are some things to know about input and output handling:

  • 入力 - アクティビティ関数は、パラメーター型として DurableActivityContext をネイティブに使用します。inputs - Activity functions natively use DurableActivityContext as a parameter type. 別の方法として、JSON にシリアル化できるパラメーター型を使用してアクティビティ関数を宣言できます。Alternatively, an activity function can be declared with any parameter type that is JSON-serializable. DurableActivityContext を使用する場合は、GetInput<T> を呼び出して、アクティビティ関数の入力をフェッチして逆シリアル化できます。When you use DurableActivityContext, you can call GetInput<T> to fetch and deserialize the activity function input.
  • 出力 - アクティビティ関数は、入力と同じように出力値をサポートします。outputs - Activity functions support output values as well as inputs. 関数の戻り値は、出力値を割り当てるために使用され、JSON にシリアル化できる必要があります。The return value of the function is used to assign the output value and must be JSON-serializable. 関数が Task または voidを返した場合は、出力として null 値が保存されます。If a function returns Task or void, a null value will be saved as the output.
  • メタデータ - アクティビティ関数を string instanceId パラメーターにバインドして、親オーケストレーションのインスタンス ID を取得できます。metadata - Activity functions can bind to a string instanceId parameter to get the instance ID of the parent orchestration.

トリガー サンプルTrigger sample

単純な "Hello World" アクティビティ関数の例を次に示します。The following is an example of what a simple "Hello World" activity function might look like:

C#C#

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

JavaScript (Functions v2 のみ)JavaScript (Functions v2 only)

module.exports = function(context) {
    context.done(null, `Hello ${context.bindings.name}!`);
};

ActivityTriggerAttribute バインドの既定のパラメーター型は DurableActivityContext です。The default parameter type for the ActivityTriggerAttribute binding is DurableActivityContext. ただし、アクティビティ トリガーは、JSON にシリアル化できる型 (プリミティブ型を含む) への直接的なバインドもサポートしているため、同じ関数を次のように単純化できます。However, activity triggers also support binding directly to JSON-serializeable types (including primitive types), so the same function could be simplified as follows:

C#C#

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

JavaScript (Functions v2 のみ)JavaScript (Functions v2 only)

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

複数のパラメーターを渡すPassing multiple parameters

アクティビティ関数に複数のパラメーターを直接渡すことはできません。It is not possible to pass multiple parameters to an activity function directly. この場合の推奨は、オブジェクトの配列を渡すか、ValueTuples オブジェクトを使用することです。The recommendation in this case is to pass in an array of objects or to use ValueTuples objects.

次の例では、C# 7 に追加された ValueTuples の新機能を使用しています。The following sample is using new features of ValueTuples added with C# 7:

[FunctionName("GetCourseRecommendations")]
public static async Task<dynamic> RunOrchestrator(
    [OrchestrationTrigger] DurableOrchestrationContext context)
{
    string major = "ComputerScience";
    int universityYear = context.GetInput<int>();

    dynamic courseRecommendations = await context.CallActivityAsync<dynamic>("CourseRecommendations", (major, universityYear));
    return courseRecommendations;
}

[FunctionName("CourseRecommendations")]
public static async Task<dynamic> Mapper([ActivityTrigger] DurableActivityContext inputs)
{
    // parse input for student's major and year in university 
    (string Major, int UniversityYear) studentInfo = inputs.GetInput<(string, int)>();

    // retrieve and return course recommendations by major and university year
    return new {
        major = studentInfo.Major,
        universityYear = studentInfo.UniversityYear,
        recommendedCourses = new []
        {
            "Introduction to .NET Programming",
            "Introduction to Linux",
            "Becoming an Entrepreneur"
        }
    };
}

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

オーケストレーション クライアントのバインドを使用して、オーケストレーター関数と対話する関数を記述できます。The orchestration client binding enables you to write functions which interact with orchestrator functions. たとえば、次のようにオーケストレーション インスタンスを操作できます。For example, you can act on orchestration instances in the following ways:

  • インスタンスを開始する。Start them.
  • インスタンスの状態をクエリする。Query their status.
  • インスタンスを終了する。Terminate them.
  • インスタンスの実行中にイベントを送信する。Send events to them while they're running.

Visual Studio を使用する場合は、OrchestrationClientAttribute .NET 属性を使用してオーケストレーション クライアントにバインドできます。If you're using Visual Studio, you can bind to the orchestration client by using the OrchestrationClientAttribute .NET attribute.

スクリプト言語 (.csx ファイルなど) を使用して開発する場合、オーケストレーション トリガーは、function.jsonbindings 配列の次の JSON オブジェクトによって定義されます。If you're using scripting languages (e.g. .csx files) for development, the orchestration trigger is defined by the following JSON object in the bindings array of function.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": "out"
}
  • taskHub - 複数の関数アプリが同じストレージ アカウントを共有するが、相互に分離する必要があるシナリオで使用されます。taskHub - Used in scenarios where multiple function apps share the same storage account but need to be isolated from each other. 指定されていない場合は、host.json の既定値が使用されます。If not specified, the default value from host.json is used. この値は、ターゲットのオーケストレーター関数によって使用される値と一致している必要があります。This value must match the value used by the target orchestrator functions.
  • connectionName - ストレージ アカウント接続文字列を含むアプリ設定の名前。connectionName - The name of an app setting that contains a storage account connection string. この接続文字列で表されるストレージ アカウントは、ターゲットのオーケストレーター関数によって使用されるものと同じにする必要があります。The storage account represented by this connection string must be the same one used by the target orchestrator functions. 指定されない場合は、関数アプリの既定のストレージ アカウント接続文字列が使用されます。If not specified, the default storage account connection string for the function app is used.

注意

ほとんどの場合、これらのプロパティを省略し、既定の動作を使用することをお勧めします。In most cases, we recommend that you omit these properties and rely on the default behavior.

クライアントの使用Client usage

C# 関数では、通常は、DurableOrchestrationClient にバインドします。これにより、Durable Functions によってサポートされるすべてのクライアント API にフル アクセスできます。In C# functions, you typically bind to DurableOrchestrationClient, which gives you full access to all client APIs supported by Durable Functions. クライアント オブジェクトの API には以下が含まれます。APIs on the client object include:

IAsyncCollector<T> にバインドすることもできます。TStartOrchestrationArgs または JObject です。Alternatively, you can bind to IAsyncCollector<T> where T is StartOrchestrationArgs or JObject.

これらの操作の詳細については、API のドキュメントの DurableOrchestrationClient を参照してください。See the DurableOrchestrationClient API documentation for additional details on these operations.

クライアントのサンプル (Visual Studio での開発)Client sample (Visual Studio development)

"HelloWorld" オーケストレーションを開始するキューによってトリガーされる関数の例を次に示します。Here is an example queue-triggered function that starts a "HelloWorld" orchestration.

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

クライアントのサンプル (Visual Studio 以外)Client sample (not Visual Studio)

開発用に Visual Studio を使用していない場合は、次の function.json ファイルを作成できます。If you're not using Visual Studio for development, you can create the following function.json file. この例は、永続的なオーケストレーション クライアントのバインドを使用するキューによってトリガーされる関数の構成方法を示しています。This example shows how to configure a queue-triggered function that uses the durable orchestration client binding:

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

新しいオーケストレーター関数のインスタンスを開始する言語固有のサンプルを次に示します。Following are language-specific samples that start new orchestrator function instances.

C# のサンプルC# Sample

次の例は、永続的なオーケストレーション クライアントのバインドを使用して、C# スクリプト関数から新しい関数インスタンスを開始する方法を示しています。The following sample shows how to use the durable orchestration client binding to start a new function instance from a C# script function:

#r "Microsoft.Azure.WebJobs.Extensions.DurableTask"

public static Task<string> Run(string input, DurableOrchestrationClient starter)
{
    return starter.StartNewAsync("HelloWorld", input);
}

JavaScript のサンプルJavaScript Sample

次の例は、永続的なオーケストレーション クライアントのバインドを使用して、JavaScript 関数から新しい関数インスタンスを開始する方法を示しています。The following sample shows how to use the durable orchestration client binding to start a new function instance from a JavaScript function:

module.exports = function (context, input) {
    var id = generateSomeUniqueId();
    context.bindings.starter = [{
        FunctionName: "HelloWorld",
        Input: input,
        InstanceId: id
    }];

    context.done(null, id);
};

インスタンスの開始の詳細については、インスタンスの管理に関する記事を参照してください。More details on starting instances can be found in Instance management.

次の手順Next steps