spacetimedb-procedures

このスキルは、リデューサーのトランザクションエントリーポイント以外のプロシージャやサーバーサイドの処理に使用します。

プロシージャの基本パターン

プロシージャは、値を返したり、外部 HTTP 呼び出しなど、リデューサーでは行うべきでない処理を実行したりできるサーバー関数です。クライアントから呼び出されるトランザクション上の状態変更にはリデューサーを使用し、呼び出し元が戻り値を必要とする場合や、関数が外部処理を行う必要がある場合はプロシージャを使用します。

TypeScript のプロシージャの形式：

export const add_two_numbers = spacetimedb.procedure(
  { lhs: t.u32(), rhs: t.u32() },
  t.u64(),
  (_ctx, { lhs, rhs }) => BigInt(lhs) + BigInt(rhs),
);

言語に関する注意事項：

• TypeScript のプロシージャは、宣言された t.* 型を返し、(ctx, args) を受け取ります。
• C# のプロシージャは不安定です。#pragma warning disable STDB_UNSTABLE を追加し、[SpacetimeDB.Procedure] を使用してください。
• Rust のプロシージャは不安定です。unstable 機能を有効にし、&mut ProcedureContext とともに #[spacetimedb::procedure] を使用してください。
• C++ のプロシージャは不安定です。ヘッダーをインクルードする前に SPACETIMEDB_UNSTABLE_FEATURES を定義してください。

トランザクションと HTTP

• プロシージャは自動的にトランザクション内で実行されるわけではありません。
• データベースへの書き込みは、TypeScript の ctx.withTx(...) など、各言語のトランザクションヘルパーで囲んでください。
• HTTP リクエストの実行中はトランザクションを開いたままにしないでください。先にデータを取得し、その後、結果を書き込むかリデューサーのロジックを呼び出すために、短時間のトランザクションを開始してください。
• 外部 API のシークレットや失敗は明示的に扱ってください。トークンや、非公開データが含まれる可能性のあるレスポンス本文をログに記録しないでください。
• プロシージャからリデューサーのロジックを呼び出す場合は、状態を変更する共有ロジックをトランザクションセーフにし、リデューサーコンテキストからも再利用できるようにしてください。

リファレンスマップ

必要な情報	開く
プロシージャの定義、データベースアクセス、HTTP、リデューサーの呼び出し、戻り値	references/functions-procedures.md

ガイダンス

• トランザクション上のクライアント呼び出しによる状態変更にはリデューサーを使用し、リファレンスで戻り値や外部処理が適切とされている場合はプロシージャを使用してください。
• HTTP リクエストと外部 API の処理では、シークレット、失敗、ランタイムの要件を明示的に扱ってください。
• 必要に応じて、テーブル変更の詳細は spacetimedb-reducers または spacetimedb-tables を参照してください。