Durable Task SDK for Go で開発

Go 用 Durable Task SDKを使えば、オーケストレーション、アクティビティ、永続エンティティを Go 関数として定義できます。 自分のコンピュートプラットフォームでアプリケーションをホストしてください。 Durable Task Schedulerは実行履歴を保存し、作業をGoワーカーに送信します。

Important

Go SDKは ベータ版です。 この記事と Goクイックスタート は v1.0.0-beta3を使用しています。 ベータ版はv0.6.0のドロップイン代替ではありません。組み込みSQLiteやPostgreSQLバックエンド、またはスタンドアロンのgRPCホストをサポートしていません。 GoはDurable Functions言語ではありません。

前提条件とインストール

  • Go 1.25 以降にしてください。
  • Durable Task Schedulerエミュレーター用のDockerまたは互換性のあるコンテナランタイム。
  • Azure では、既存のスケジューラとタスク ハブ、および Durable Task Data Contributor ロールが割り当てられた ID が必要です。 ID ベースのアクセスを参照してください。

既存のGoモジュールから公開済みのベータ版をインストールしてください:

go get github.com/microsoft/durabletask-go@v1.0.0-beta3

SDKのインポートをコードに追加した後、 go mod tidy を実行して推移依存関係やチェックサムを記録します。

ワーカーを起動し、並列作業をスケジュールし、結果を読み取り、シャットダウンする完全なアプリケーションについては、「Durable Task SDKs - Go でアプリを作成」をご覧ください。

プログラミング モデル

SDKは1つのGoモジュールとして出荷されます。 主なパッケージは以下の通りです:

パッケージ Purpose
task オーケストレーション、アクティビティ、エンティティ コンテキスト; タスク登録; 永続ワークフローの基本要素。
durabletaskscheduler 接続オプション、および Durable Task Scheduler のクライアント接続とワーカー接続を分離
client ワーカーの設定には、並行性、バージョン管理、作業項目フィルターが含まれます。
api インスタンスおよびエンティティID、オーケストレーションメタデータ、管理リクエストオプション。

オーケストレーターはシグネチャ func(*task.OrchestrationContext) (any, error) を持っています。 アクティビティにはシグネチャ func(task.ActivityContext) (any, error) があります。 関数ベースのエンティティはシグネチャ func(*task.EntityContext) (any, error)を持ちます。 GetInputで型付き入力を読み込み、シリアル化可能な結果またはエラーを返します。 JSONがデフォルトのデータ形式です。

タスクの登録と実行

task.NewTaskRegistry でレジストリを作成します。 固定名には AddOrchestratorN、AddActivityN、AddEntityNを付けて登録し、登録エラーをチェックします。 アクティビティコールやクライアントのスケジューリングで使われる名前は登録と一致しなければなりません。

接続文字列をdurabletaskscheduler.NewOptionsFromConnectionStringで解析してください。 オプションを以下に渡してください:

  • durabletaskscheduler.NewClient オーケストレーションインスタンスを開始および管理するには
  • durabletaskscheduler.NewWorker 登録済みタスクを実行

ワーカーで Start を呼び出して、作業項目の処理を開始します。 client.WithAutoWorkItemFilters()を使ってレジストリからワーカールーティングフィルターを導出してください。 別のアプリケーションによってのみ登録されたタスクを作業員に処理させないでください。

クライアントとワーカーは別々の接続を所有しています。 終わったらクライアントアプリを閉じてください。 アプリケーションの実行コンテキストが期限切れの場合は、新しい有界コンテキストで、Shutdown を使用してワーカーをドレインします。 クイックスタートは両方の操作からのエラーをチェックします。

決定論的なオーケストレーターを書く

永続的な操作にはオーケストレーション コンテキストを活用しましょう：

Operation Go API 詳細を表示
アクティビティの順序設定 ctx.CallActivity(...).Await(&result) 関数の連鎖
ファンアウトとファンイン すべてのタスクをスケジュールし、その後ctx.WhenAll(tasks...)して、Awaitで結果を読み取ります。 ファンアウト/ファンイン
遅延 ctx.CreateTimer(duration).Await(nil) 持続的タイマー
イベントを待つ ctx.WaitForSingleEvent(name, timeout).Await(&result) 外部イベント
子ワークフローを呼び出します ctx.CallSubOrchestrator(...).Await(&result) サブオーケストレーション
アクティビティを再試行する task.WithActivityRetryPolicy エラー処理と再試行
新しい履歴を始めましょう ctx.ContinueAsNew 永続的オーケストレーション
進捗状況のレポート ctx.SetCustomStatusValue カスタムステータス
エンティティに連絡またはシグナルを送る ctx.CallEntity と ctx.SignalEntity 永続エンティティ

オーケストレーターでネットワークコール、ファイルI/O、環境変数読み取り、その他の非決定性作業は行わないでください。 その作業を活動に活かしましょう。 オーケストレーターコードでは、ネイティブのゴルーチン、チャネル、 sync.WaitGroup、 time.Sleep の代わりにSDKの持続的な並行性プリミティブを使いましょう。 リプレイ対応のロギングには ctx.Logger() を使いましょう。 詳細は、Orchestrator のコード制約を参照してください。

アクティビティは通常のGo I/Oを実行することができますが、複数回実行される可能性があります。 外部副作用は冪等にしてください。

完了結果を確認

WaitForOrchestrationCompletion エラーなしで戻ったということは、インスタンスが終端状態に達したということであり、必ずしもワークフローが成功したとは限りません。 リクエストのペイロードにapi.WithFetchPayloads(true)を使用し、RuntimeStatusがapi.RUNTIME_STATUS_COMPLETEDであることを確認し、その後ReadOutputで出力をデコードします。

失敗した場合はFailureDetailsを確認してください。 失敗や終了したオーケストレーションを成功として報告しないでください。 インスタンス管理を参照してください。

エミュレーターまたはAzureに接続してください

クイックスタートは接続文字列 Endpoint=http://localhost:8080;TaskHub=default;Authentication=Noneを使っています。 Authentication=None はローカル エミュレーター開発に使用し、認証された Azure アクセスには使用しないでください。

Azureでは、スケジューラーのHTTPSエンドポイントとタスクハブ名を使いましょう。 Azure Identity 認証チェーンには Authentication=DefaultAzure、Azure CLI を通じてサインインした開発 ID には Authentication=AzureCLI を選択します。 Go SDKはマネージドIDおよびワークロードアイデンティティもサポートしています。 設定の詳細や対応認証モードについては、 Go SDK接続ガイドをご覧ください。

クイックスタートはDTS_CONNECTION_STRING環境変数の接続文字列を読み取り、それをNewOptionsFromConnectionStringに渡します。 SDKはこの変数を自動的には読み取りません。

サンプル

Go SDKリポジトリには、アクティビティシーケンス、ファンアウト/ファンイン、外部イベント、再トライ、耐久エンティティ、スケジュール、大規模ペイロード、履歴エクスポート、分散トレーシングなどの機能領域ごとに実行可能なサンプルが含まれています。 完全なリスト、前提条件、実行手順については、Go SDK のサンプルをご覧ください。

テストオーケストレーション

SDKにはストレージバックエンドが含まれていないため、オーケストレーションはDurable Task Schedulerまたはそのエミュレーターに対してのみ実行されます。 通常のGo単元テストでアクティビティやその他のビジネスロジックをテストします。 オーケストレーションの挙動を検証するために、リプレイを含め、エミュレーターや専用のタスクハブに対して統合テストを実行してください。

ベータ互換性の考慮事項

  • スケジュール: Goのスケジュールは他のSDKと永続状態形式を共有しません。 スケジュールされたタスクにはGo専用のタスクハブを使いましょう。
  • エンティティロック:GoとPythonは.NETとは異なるマルチエンティティロックの順序を使用しています。 Go/Pythonと.NETのオーケストレーションで重複するロックセットを同時に取得しないでください。
  • 巻き戻し: Goワーカーは、失敗したアクティビティや子操作後に追加の非ライフサイクルイベントを含む履歴を保守的に拒否します。 リワインドリクエストが受け入れられたからといって回復は証明されません。新しい実行IDと成功した出力を検証してください。
  • エミュレーター管理API: インスタンス一覧表示やフィルタドパージにはエミュレータの制限が文書化されています。 インスタンスごとにスコープを絞ったクリーンアップを好んで、共有ハブをクリアしないようにしましょう。
  • 履歴エクスポート(プレビュー): 分離されたGo専用のタスクハブとエクスポート先を使い、エクスポートジョブが無関係なアプリケーションデータをエクスポート・削除できないようにしましょう。

詳細な互換性やライフサイクル動作については 、Go SDKの機能マトリックスおよびトランスポートガイド をご覧ください。

関連するコンテンツ

  • 最終更新: