> ## 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.

# アクターのファイルとコード

> Actor クラス、そのハンドラー、接続、ストレージ、タイマーの完全なリファレンス

<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>

アプリのバックエンドで実行される `Actor` クラスの完全なリファレンスです。セッションに接続するクライアント SDK については、[`actors` SDK リファレンス](/ja/developers/references/sdk/docs/type-aliases/actors) を参照してください。

アクターの概念と用語については、[アクター概要](/ja/developers/backend/resources/actors/overview) を参照してください。

## 必須のハンドラー

`Actor` クラスは抽象クラスです。次の各ハンドラーの本体を実装します。これらのハンドラーは、クライアントとタイマーからのイベントに応答します。

| ハンドラー | イベント |
| - | - |
| [`handleConnect()`](#lifecycle-handlers) | クライアントが接続したとき。 |
| [`handleMessage()`](#lifecycle-handlers) | 接続中のクライアントがメッセージを送信したとき。 |
| [`handleClose()`](#lifecycle-handlers) | クライアントが切断したとき。 |
| [`handleTick()`](#timer-handlers-and-settings) | tick が有効な間、tick の間隔ごと。 |

## 省略可能なハンドラー

アクターで必要な場合は、次のハンドラーを実装します。

| ハンドラー | イベント |
| - | - |
| [`handleStart()`](#lifecycle-handlers) | セッションが開始したとき。Base44 が接続を処理する前に実行されます。 |
| [`shouldTick()`](#timer-handlers-and-settings) | 各接続、メッセージ、切断、tick の後。 |
| [`handleWake()`](#timer-handlers-and-settings) | `schedule()` で設定した時刻になったとき。 |

セッションで tick を使う場合は、[`tickIntervalMs`](#timer-handlers-and-settings) を設定します。`shouldTick()` を省略すると、セッションは tick しません。

## 呼び出せるメソッド

アクタークラスには組み込みの機能があります。アクターのハンドラーを実装するときに、次のメソッドを使用できます。

| メソッド | 目的 |
| - | - |
| [`schedule()`](#timer-handlers-and-settings) | 指定した時刻に wake を設定します。 |
| [`cancelSchedule()`](#timer-handlers-and-settings) | スケジュールした wake をクリアします。 |
| [`conn.send()`](#connections) | 1 つのクライアントに返信します。 |
| [`conn.reject()`](#connections) | 接続しようとするクライアントを拒否します。 |
| [`broadcast()`](#connections) | セッション内のすべてのクライアントに送信します。 |
| [`getConnections()`](#connections) | 接続中のクライアントを一覧表示します。 |
| [`this.storage.get()`](#storage) | 保存されたセッションの値を読み取ります。 |
| [`this.storage.put()`](#storage) | セッションの値を保存します。 |
| [`this.storage.delete()`](#storage) | 保存された値を 1 つ削除します。 |
| [`this.storage.deleteAll()`](#storage) | セッションのストアをクリアします。 |
| [`secrets.get()`](#read-secrets) | アプリのシークレットを読み取ります。 |

[エンティティ](/ja/developers/backend/resources/entities/overview) の読み書きには [`this.client`](#entity-access) を使用します。

## クラス宣言

`base44:runtime/actors` から `Actor` をインポートし、`Actor` を継承したクラスを `base44/actors/<actor-name>/entry.ts` からデフォルトエクスポートとしてエクスポートします。
フォルダー名は SDK でのアクター名になります。設定の詳細については、[アクターを作成する](/ja/developers/backend/resources/actors/create-actor) を参照してください。

<ResponseField name="Incoming" type="generic">
  接続中のクライアントからアクターが受信するメッセージの型です。
  `handleMessage()` の `msg` パラメーターに適用されます。
</ResponseField>

<ResponseField name="Outgoing" type="generic">
  アクターが接続中のクライアントに送信するメッセージの型です。
  `conn.send()` と `broadcast()` に適用されます。
</ResponseField>

## ランタイム API

アクターは `base44:runtime/actors` モジュールから `Actor` クラスをインポートします。

```typescript theme={null}
import { Actor } from "base44:runtime/actors";
```

### シークレットを読み取る

ハンドラーからアプリの環境変数を読み取るには、`secrets.get()` を使用します。このメソッドは値を文字列として返します。シークレットが設定されていない場合は `undefined` を返します。

`base44:runtime` モジュールから `secrets` をインポートします。

```typescript theme={null}
import { secrets } from "base44:runtime";
```

シークレットは、CLI から [`secrets set`](/ja/developers/references/cli/commands/secrets-set) で設定します。

シークレットが必要な処理には、[バックエンド関数](/ja/developers/backend/resources/backend-functions/overview) を呼び出すことをおすすめします。関数がシークレットを読み取って結果を返すため、アクターはシークレットを受け取りません。サンプルフローについては、[シークレットが必要な処理でバックエンド関数を呼び出す](/ja/developers/backend/resources/actors/sample-flows#call-a-backend-function-for-secret-work) を参照してください。

## ライフサイクルハンドラー

Base44 は、セッション内のクライアントのアクティビティに応じて、これらのハンドラーを呼び出します。
各ハンドラーの本体は自分で実装します。
詳しくは [アクターとクライアントのやり取り](/ja/developers/backend/resources/actors/overview#how-actors-and-clients-interact) を参照してください。
サンプルフローについては、[クライアント接続を管理する](/ja/developers/backend/resources/actors/sample-flows#manage-client-connections) を参照してください。

<ResponseField name="handleStart" type="method">
  セッションがアクティブになるたびに実行されます。たとえば次の場合です。

  * セッションが最初に作成されたとき。
  * クライアントがアイドル状態のセッションに接続したとき。
  * アイドル状態のセッションにメッセージが届いたとき。
  * スケジュールした時刻になったとき。

  `void` または `Promise<void>` を返します。
</ResponseField>

<ResponseField name="handleConnect" type="method" required>
  クライアントがセッションに接続したときに実行されます。
  `conn.send()` で現在のセッション状態を送信するか、`conn.reject()` で接続を拒否できます。
  `void` または `Promise<void>` を返します。

  <Expandable title="パラメーター">
    <ResponseField name="conn" type="Conn" required>
      接続したクライアントを表します。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="handleMessage" type="method" required>
  接続中のクライアントがメッセージを送信したときに実行されます。
  セッション状態を変更したりアプリのデータにアクセスしたりする前に、メッセージを検証できます。
  `void` または `Promise<void>` を返します。

  <Expandable title="パラメーター">
    <ResponseField name="conn" type="Conn" required>
      メッセージを送信したクライアントを表します。
    </ResponseField>

    <ResponseField name="msg" type="Incoming" required>
      クライアントから送信されたメッセージが含まれます。`Incoming` ジェネリクスが
      メッセージの型を定義します。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="handleClose" type="method" required>
  クライアントが切断したときに実行されます。
  このハンドラーを使って、接続 ID に関連付けられたセッション状態を削除します。
  同じ ID を再利用する再接続は、`handleClose()` を実行せずに古いソケットを置き換えます。
  `void` または `Promise<void>` を返します。

  <Expandable title="パラメーター">
    <ResponseField name="conn" type="Conn" required>
      切断したクライアントを表します。
    </ResponseField>
  </Expandable>
</ResponseField>

## タイマーハンドラーと設定

これらのハンドラーと設定は、セッション内の時間指定の処理を制御します。
Base44 は、クライアントのアクティビティではなく、スケジュールした時刻になったときにこれらを呼び出します。
詳しくは [スケジュールされた処理](/ja/developers/backend/resources/actors/overview#scheduled-work) を参照してください。
サンプルフローについては、[tick を実行する](/ja/developers/backend/resources/actors/sample-flows#run-ticks) と [wake をスケジュールする](/ja/developers/backend/resources/actors/sample-flows#schedule-wakes) を参照してください。

<ResponseField name="handleTick" type="method" required>
  `shouldTick()` が `true` を返し、セッションに少なくとも 1 つのクライアントがある間、間隔ごとに 1 回実行されます。
  `void` または `Promise<void>` を返します。
</ResponseField>

<ResponseField name="tickIntervalMs" type="number">
  tick の間隔をミリ秒で指定します。デフォルトは `100` です。
</ResponseField>

<ResponseField name="shouldTick" type="method">
  `boolean` を返します。セッションの tick を続けるには `true` を、停止するには `false` を返します。このメソッドは同期的です。

  このメソッドは高速に保ち、副作用を持たせないでください。Base44 は、各接続、メッセージ、切断、tick の後にこのメソッドを呼び出します。
</ResponseField>

<ResponseField name="handleWake" type="method">
  `schedule()` で設定した時刻になったときに 1 回実行されます。
  `void` または `Promise<void>` を返します。

  <Expandable title="パラメーター">
    <ResponseField name="key" type="string" required>
      `schedule()` に渡したキーが含まれます。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="schedule" type="method">
  指定した時刻に `handleWake()` を 1 回実行するようスケジュールします。
  Base44 がスケジュールを保存した後に完了する `Promise` を返します。
  スケジュールはアイドル期間をまたいで保持され、アイドル状態のセッションを開始できます。
  同じキーでこのメソッドを再度呼び出すと、スケジュールした時刻が置き換えられます。

  <Expandable title="パラメーター">
    <ResponseField name="key" type="string" required>
      スケジュールした wake を識別します。wake がトリガーされると `handleWake()` に渡されます。
    </ResponseField>

    <ResponseField name="at" type="number | Date" required>
      `handleWake()` を実行するタイミングを指定します。`Date` オブジェクト、または
      1970 年 1 月 1 日からのミリ秒数を使用します。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="cancelSchedule" type="method">
  キーに関連付けられたスケジュール済みの wake をキャンセルします。
  Base44 がスケジュールをクリアした後に完了する `Promise` を返します。

  <Expandable title="パラメーター">
    <ResponseField name="key" type="string" required>
      `schedule()` に渡したキーを指定します。
    </ResponseField>
  </Expandable>
</ResponseField>

## 接続

これらのプロパティとメソッドは、クライアントが関わるライフサイクルハンドラーに渡される `conn` オブジェクトで使用できます。
これらを使って、クライアントの ID の読み取り、メッセージの送信、接続の管理を行います。
メッセージングの概要については、[リアルタイムメッセージ](/ja/developers/backend/resources/actors/overview#realtime-messages) を参照してください。
サンプルフローについては、[クライアント接続を管理する](/ja/developers/backend/resources/actors/sample-flows#manage-client-connections) を参照してください。

<Note>
  `conn` は WebSocket のバックエンド側の端で、クライアントの `Connection` は同じソケットのもう一方の端です。アクタークラスでは `conn` を使用します。クライアントオブジェクトについては、`actors` SDK リファレンスを参照してください。
</Note>

<ResponseField name="conn.id" type="string">
  この接続を識別します。クライアントが接続時に渡した ID、
  または SDK が生成した ID と一致します。
</ResponseField>

<ResponseField name="conn.identity" type="object">
  この接続のクライアントを識別します。すべての
  接続に存在します。

  <Expandable title="プロパティ">
    <ResponseField name="type" type="string" required>
      `authenticated` または `anonymous` が含まれます。
    </ResponseField>

    <ResponseField name="userId" type="string">
      ログイン済みのクライアントを識別します。`type` が
      `authenticated` の場合に存在します。
    </ResponseField>

    <ResponseField name="anonymousId" type="string">
      匿名のクライアントを識別します。`type` が `anonymous` の場合に存在します。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conn.send" type="method">
  この接続にメッセージを送信します。`void` を返します。

  <Expandable title="パラメーター">
    <ResponseField name="data" type="Outgoing" required>
      この接続に送信するメッセージが含まれます。`Outgoing` ジェネリクスがメッセージの型を定義します。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conn.reject" type="method">
  `handleConnect()` から接続を拒否します。`void` を返します。

  <Expandable title="パラメーター">
    <ResponseField name="code" type="number" required>
      クライアントに送信するステータスコードを指定します。
    </ResponseField>

    <ResponseField name="reason" type="string" required>
      アクターが接続を拒否した理由を説明します。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="broadcast" type="method">
  セッション内のすべてのライブ接続にメッセージを送信します。`void` を返します。

  <Expandable title="パラメーター">
    <ResponseField name="data" type="Outgoing" required>
      セッション内のすべての接続に送信するメッセージが含まれます。`Outgoing` ジェネリクスがメッセージの型を定義します。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="getConnections" type="method">
  セッション内のライブな `conn` オブジェクトの配列を返します。
  `handleStart()` でこのメソッドを使うと、復元したデータを、
  アイドル期間中も接続を維持していたクライアントと照合できます。
</ResponseField>

<ResponseField name="this.instanceId" type="string">
  セッションレベルのプロパティです。クライアントがこのセッションに
  到達するために使用したセッション ID が含まれます。
</ResponseField>

## ストレージ

セッションデータの読み書きには `this.storage` を使用します。クラスフィールドとは異なり、ストレージはアイドル期間をまたいで保持されます。ストレージとクラスフィールドの使い分けについては、[ストレージ](/ja/developers/backend/resources/actors/overview#storage) を参照してください。サンプルフローについては、[セッションデータを永続化する](/ja/developers/backend/resources/actors/sample-flows#persist-session-data) を参照してください。

<ResponseField name="this.storage.get" type="method">
  キーで値を取得します。保存された値に解決される `Promise` を返します。
  キーが存在しない場合は `undefined` に解決されます。

  <Expandable title="パラメーター">
    <ResponseField name="key" type="string" required>
      取得するキーを指定します。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.put" type="method">
  キーで値を保存します。そのキーにすでに保存されている値を置き換えます。
  書き込みが完了すると完了する `Promise` を返します。

  <Expandable title="パラメーター">
    <ResponseField name="key" type="string" required>
      保存するキーを指定します。
    </ResponseField>

    <ResponseField name="value" type="unknown" required>
      保存する JSON 互換の値を指定します。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.delete" type="method">
  キーで値を削除します。キーが存在した場合は `true` に、
  それ以外の場合は `false` に解決される `Promise` を返します。

  <Expandable title="パラメーター">
    <ResponseField name="key" type="string" required>
      削除するキーを指定します。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.deleteAll" type="method">
  セッションの保存データをすべて削除します。ストアが空になると完了する
  `Promise` を返します。その後の接続は、新しいセッションと同じ空のストレージで
  開始します。
</ResponseField>

## エンティティへのアクセス

アクターのハンドラー内からアプリのエンティティを読み書きするには、`this.client` と `this.client.asServiceRole` を使用します。サンプルフローについては、[セッションからエンティティデータを書き込む](/ja/developers/backend/resources/actors/sample-flows#write-entity-data-from-a-session) を参照してください。

<ResponseField name="this.client" type="Base44Client">
  このセッションにスコープされたアプリクライアントを提供します。このクライアントは
  匿名認証を使用するため、エンティティへのアクセスはログアウトした
  クライアントと同じルールに従います。また、本番データを読み取ります。
</ResponseField>

<ResponseField name="this.client.asServiceRole" type="Base44Client">
  行レベルセキュリティをバイパスする昇格したアクセスを提供します。このクライアントを
  使う前にメッセージを検証してください。エラー後にセッションがハンドラーを再実行する
  場合があるため、書き込みは繰り返しても安全なものにしてください。
</ResponseField>

## 関連項目

* [アクター概要](/ja/developers/backend/resources/actors/overview): 概念と用語
* [アクター: サンプルフロー](/ja/developers/backend/resources/actors/sample-flows): ライフサイクル、タイマー、接続、ストレージ、エンティティ、バックエンド関数
* [`actors` SDK リファレンス](/ja/developers/references/sdk/docs/type-aliases/actors): クライアント SDK API
* [`secrets set`](/ja/developers/references/cli/commands/secrets-set): CLI から環境変数を設定します

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


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