> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Internal links on these pages omit the .md extension. Append .md to a docs page URL, or send an Accept: text/markdown header, to get that page as markdown.

# アクター概要

> アクターがリアルタイムメッセージとタイマーを使って、共有のライブセッションを実行するしくみを学びます

<div className="dev-docs-banner">
  <div className="dev-docs-banner-content">
    <div className="dev-docs-banner-title">
      開発者向けドキュメントを表示しています
    </div>

    <div className="dev-docs-banner-text">
      このドキュメントは、Base44 開発者プラットフォームで作業する開発者向けです。
    </div>
  </div>
</div>

アクターは、複数のクライアントが同時に接続する、長時間実行されるバックエンドプロセスです。

アクターを使うと、次の機能をサポートするライブセッションインスタンスを構築できます。

* **リアルタイムメッセージング:** WebSocket を介してクライアントとメッセージを送受信します。
* **永続ストレージ:** アイドル期間をまたいでセッション状態を維持します。
* **スケジュールされた処理:** 一定の間隔または特定の時刻にロジックを実行します。

チャットルームやマルチプレイヤーゲームなど、複数のクライアントがリアルタイムの更新とやり取りを必要とする機能を構築する場合に、アクターを使用します。

## アクター

[`Actor`](/ja/developers/backend/resources/actors/reference) は、バックエンドで継承するクラスです。

アクタークラスは、ライブセッションの動作を定義します。アクターでは次のことができます。

* **[接続を管理する](#connections):** セッションに接続するクライアントを受け入れるか拒否し、接続者を識別します。
* **[メッセージを処理する](#realtime-messages):** クライアントからメッセージを受信し、セッション状態を更新して、1 つのクライアントに返信するか全員にブロードキャストします。
* **[処理をスケジュールする](#scheduled-work):** 一定の間隔またはスケジュールした時刻にロジックを実行します。

## セッション

セッションは、実行中のアクターのインスタンスです。アクター名と、自分で選ぶセッション ID で識別されます。\
各セッションは、独自の状態、ストレージ、クライアント接続を個別に管理します。

### 接続

接続は、クライアントからセッションへの WebSocket を表します。参加する各クライアントには、一意の接続が割り当てられます。アクターはその接続を使って、接続者の識別、クライアント接続の管理、メッセージの送信を行います。

詳しくは [接続](/ja/developers/backend/resources/actors/reference#connections) を参照してください。サンプルフローについては、[クライアント接続を管理する](/ja/developers/backend/resources/actors/sample-flows#manage-client-connections) を参照してください。

### アクティブなセッションとアイドル状態のセッション

セッションは常に次のいずれかの状態にあります。

* **アクティブ:** セッションはライブで、イベントを処理しています。クライアントが接続したとき、クライアントがアイドル状態のセッションにメッセージを送ったとき、またはスケジュールした wake 時刻になったときに、セッションはアクティブになります。
* **アイドル:** セッションはイベントを処理していません。最後のメッセージの処理が終わり、スケジュールされたすべての処理が停止すると、まもなくセッションはアイドル状態になります。セッションは、再びアクティブになるまで、[保存データ](#storage)、スケジュールされた時刻、開いている接続を維持します。

セッションがアイドル状態になっても、接続を開いているクライアントは接続されたままです。クライアントの次のメッセージか、スケジュールされた [wake](#wakes) によって、セッションは再びアクティブになります。

## クライアント

JavaScript SDK の [`base44.actors`](/ja/developers/references/sdk/docs/type-aliases/actors) を使って、クライアントをアクターセッションに接続し、メッセージを交換します。

actors SDK は次の機能をサポートします。

* **接続:** セッションへの WebSocket 接続を開きます。
* **サブスクライブ:** アクターからメッセージを受信します。
* **送信:** アクターにメッセージを送信します。
* **クローズ:** アクターへの WebSocket 接続を閉じます。

詳しくは [クライアントをセッションに接続する](/ja/developers/backend/resources/actors/sample-flows#connect-a-client-to-a-session) を参照してください。

## アクターとクライアントのやり取り

次の図は、クライアントとアクターの一般的なやり取りを示しています。

```mermaid theme={null}
sequenceDiagram
    participant C as クライアント
    participant A as アクター

    C->>A: 1. connect(sessionId)
    A->>A: 2. handleStart()
    A->>A: 3. handleConnect(conn)
    C->>A: 4. send(data)
    A->>A: 5. handleMessage(conn, msg)
    A-->>C: 6. broadcast(data)
    C->>A: 7. close()
    A->>A: 8. handleClose(conn)
```

1. クライアントが WebSocket 経由でアクターに接続します。
2. セッションがアクティブになります。[`handleStart()`](/ja/developers/backend/resources/actors/reference#lifecycle-handlers) は、初回起動時と、セッションがアイドル状態からアクティブになるたびに実行されます。
3. アクターが接続を処理します。クライアントの ID を確認して接続を拒否するか、現在の状態を送信できます。
4. クライアントがメッセージを送信します。
5. アクターがメッセージを処理します。セッション状態を変更する前に、形式と送信者の権限を検証できます。
6. アクターは、接続中のすべてのクライアントに更新をブロードキャストするか、送信者にのみ返信します。
7. クライアントが接続を閉じます。
8. アクターが切断を処理します。接続ごとの状態を削除できます。

## リアルタイムメッセージ

接続中の各クライアントはセッションに属し、WebSocket を介してリアルタイムでメッセージを送信できます。クライアントは [`subscribe()`](/ja/developers/references/sdk/docs/type-aliases/actors#subscribe) を使って、受信メッセージをリッスンすることもできます。

<Note>
  Base44 には、サブスクリプションベースのリスナーを使うリアルタイム機能がいくつかあります。

  * アクターの [`subscribe()`](/ja/developers/references/sdk/docs/type-aliases/actors#subscribe) は、アクターが接続中のクライアントに送信するメッセージをリッスンします。
  * エンティティの [`subscribe()`](/ja/developers/references/sdk/docs/type-aliases/entities#subscribe) は、アプリのエンティティの変更をリッスンします。

  期待するイベントを受信できるように、使用しているサービスを確認してください。
</Note>

リアルタイムメッセージでは、次のことができます。

* 特定のクライアントに返信します。
* 接続中のすべてのクライアントにブロードキャストします。
* 現在接続中のクライアントを一覧表示します。
* 各クライアントを識別し、ログイン済みかどうかを確認します。

詳しくは [接続](#connections) を参照してください。サンプルフローについては、[クライアント接続を管理する](/ja/developers/backend/resources/actors/sample-flows#manage-client-connections) を参照してください。

## メッセージの種類

クライアントとアクターは、接続を介してメッセージを交換します。メッセージは次の種類に分かれます。

* **受信メッセージ:** 接続中のクライアントがアクターに送るものです。テキスト、手、投票などがあります。クライアントは [`send()`](/ja/developers/references/sdk/docs/type-aliases/actors#send) で送信し、アクターは [`handleMessage()`](/ja/developers/backend/resources/actors/reference#lifecycle-handlers) で受信します。
* **送信メッセージ:** アクターが接続中のクライアントに送るものです。クライアントへの返信、接続中の全クライアントへのブロードキャスト、誰かが参加したときの現在の盤面などがあります。アクターは [`conn.send()`](/ja/developers/backend/resources/actors/reference#connections) または `broadcast()` で送信し、クライアントは [`subscribe()`](/ja/developers/references/sdk/docs/type-aliases/actors#subscribe) のコールバックで受信します。

アクターとクライアントで各メッセージの形が一致するように、メッセージに型を付けることをおすすめします。

* **バックエンド:** `Incoming` と `Outgoing` の型を、`Actor` クラスのジェネリクスとして渡します。完全な例については、[アクターを作成する](/ja/developers/backend/resources/actors/create-actor) を参照してください。
* **クライアント:** 同じ形で [`ActorRegistry`](/ja/developers/references/sdk/docs/type-aliases/actors#actorregistry) インターフェースを拡張します。これにより、TypeScript が `send()` と `subscribe()` の型をチェックします。

## ストレージ

アクターには、セッションがデータをどのように使用、保持するかに応じて、いくつかのストレージオプションがあります。

* **[インメモリストレージ](#in-memory-storage):** セッションがアクティブな間、クラスフィールドに保持される作業状態です。セッションがアイドル状態になるとリセットされます。
* **[永続ストレージ](#persistent-storage):** セッションがアイドル状態になっても残す必要があるデータのためのキーバリューストアです。

### インメモリストレージ

クラスフィールドは、セッションがアクティブな間の作業状態を保持します。たとえば、現在の盤面やラウンドのタイマーです。データが頻繁に変わり、アイドル時に永続化する必要がない場合は、インメモリストレージを使います。たとえば、ライブスコアやカーソル位置です。

セッションがアイドル状態になると、クラスフィールドはリセットされます。

### 永続ストレージ

各セッションには、完全に管理できる独自のキーバリューストアがあります。
セッションがアイドル状態になってもデータを残す必要がある場合は、永続ストレージを使います。たとえば、チャット履歴やゲームの盤面です。

アプリ全体で利用できるデータを保存するには、[エンティティ](/ja/developers/backend/resources/entities/overview) を使用します。

アクターのストレージについて詳しくは、[ストレージ](/ja/developers/backend/resources/actors/reference#storage) を参照してください。

### 状態の復元

セッションがアイドル状態になると、インメモリの状態はリセットされます。永続ストレージは残りますが、セッションがアクティブになっても、保存データは自動的にはメモリに読み込まれません。

チャット履歴やゲームの盤面などの永続データを復元するには、[`handleStart()`](/ja/developers/backend/resources/actors/reference#lifecycle-handlers) を使用します。

サンプルフローについては、[セッションデータを永続化する](/ja/developers/backend/resources/actors/sample-flows#persist-session-data) を参照してください。

## スケジュールされた処理

アクターには、クライアントのメッセージとは無関係に、セッションがスケジュールに従ってロジックを実行する機能があります。

* **[tick](#ticks):** 一定の間隔でコードを実行し、繰り返している間はセッションをアクティブに保ちます。
* **[wake](#wakes):** セッションがアクティブかアイドルかに関係なく、指定した時刻に 1 回実行されます。

### tick

tick は一定の間隔でコードを実行し、繰り返している間はセッションをアクティブに保ちます。

[`shouldTick()`](/ja/developers/backend/resources/actors/reference#timer-handlers-and-settings) を使って、tick を実行する条件を設定します。
アクターは、接続、メッセージ、切断、tick のたびに `shouldTick()` を再評価します。そのため、条件を満たさなくなるとすぐに tick は停止します。

<Note>
  tick には、少なくとも 1 つの接続中のクライアントが必要です。
</Note>

tick では、次のことができます。

* 各間隔の長さを選択します。
* tick を開始、停止する条件を定義します。例: 「セッションに 2 人以上のプレイヤーがいる」。
* 各間隔で実行するコードを記述します。

クライアントがメッセージを送っていないときでもセッションをアクティブに保つには、tick を使います。たとえば、ラウンドのタイマーを更新する場合です。

tick について詳しくは、[タイマーハンドラーと設定](/ja/developers/backend/resources/actors/reference#timer-handlers-and-settings) を参照してください。サンプルフローについては、[tick を実行する](/ja/developers/backend/resources/actors/sample-flows#run-ticks) を参照してください。

### wake

wake は、セッションがアクティブかアイドルかに関係なく、指定した時刻に 1 回実行されます。

wake では、次のことができます。

* wake を実行するタイミングをスケジュールします。
* wake の発生時に実行するロジックを実装します。

1 回限りのアクションをスケジュールするには、wake を使います。たとえば、ゲームのターンの終了、空のロビーのクローズ、リマインダーのトリガー、特定の時刻でのイベント開始などです。

wake について詳しくは、[タイマーハンドラーと設定](/ja/developers/backend/resources/actors/reference#timer-handlers-and-settings) を参照してください。サンプルフローについては、[wake をスケジュールする](/ja/developers/backend/resources/actors/sample-flows#schedule-wakes) を参照してください。

## アクターをデプロイする

アクターは [`actors deploy`](/ja/developers/references/cli/commands/actors-deploy) でデプロイします。プロジェクトのすべてのリソースを一度にプッシュするには、[`deploy`](/ja/developers/references/cli/commands/deploy) を使用します。デプロイすると、リモートのアクターが追加、更新され、それ以外はそのまま残ります。

## アクターを削除する

アクターを削除するには:

* [`actors delete`](/ja/developers/references/cli/commands/actors-delete) を実行して、Base44 からリモートのアクターを削除します。
* ローカルプロジェクトからアクターディレクトリを削除します。

<Note>
  ローカルプロジェクトからアクターを削除しないと、次回の [`actors deploy`](/ja/developers/references/cli/commands/actors-deploy) または [`deploy`](/ja/developers/references/cli/commands/deploy) で、アクターが再作成され Base44 プロジェクトにデプロイされます。
</Note>

## 関連項目

* [アクターを作成する](/ja/developers/backend/resources/actors/create-actor): アクターファイルと最小限のクラス
* [アクター: サンプルフロー](/ja/developers/backend/resources/actors/sample-flows): ライフサイクル、タイマー、接続、ストレージ、エンティティ、バックエンド関数
* [アクターのファイルとコード](/ja/developers/backend/resources/actors/reference): バックエンドクラス API の完全なリファレンス
* [`actors` SDK リファレンス](/ja/developers/references/sdk/docs/type-aliases/actors): クライアント SDK API

<Note>このページは AI によって翻訳されました。最も正確で最新の情報については、[英語版](/) を参照してください。</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.