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

# קבצים וקוד של Actors

> תיעוד מלא של המחלקה Actor, ה-handlers, החיבורים, האחסון והטיימרים שלה

<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 בצד הלקוח שמתחבר ל-session, ראה את [תיעוד ה-SDK של `actors`](/he/developers/references/sdk/docs/type-aliases/actors).

למושגים ומונחים של actors, ראה את [סקירת ה-actors](/he/developers/backend/resources/actors/overview).

## Handlers נדרשים

המחלקה `Actor` היא מופשטת. ממש את הגוף של כל אחד מה-handlers הבאים. ה-handlers מגיבים לאירועים מלקוחות ומטיימרים.

| Handler | אירועים |
| - | - |
| [`handleConnect()`](#lifecycle-handlers) | לקוח מתחבר. |
| [`handleMessage()`](#lifecycle-handlers) | לקוח מחובר שולח הודעה. |
| [`handleClose()`](#lifecycle-handlers) | לקוח מתנתק. |
| [`handleTick()`](#timer-handlers-and-settings) | בכל מרווח tick, כל עוד ה-ticks פעילים. |

## Handlers אופציונליים

כשה-actor צריך אותם, ממש את ה-handlers האלה.

| Handler | אירועים |
| - | - |
| [`handleStart()`](#lifecycle-handlers) | ה-session מתחיל, לפני ש-Base44 מטפלת בחיבור. |
| [`shouldTick()`](#timer-handlers-and-settings) | אחרי כל חיבור, הודעה, ניתוק ו-tick. |
| [`handleWake()`](#timer-handlers-and-settings) | מגיע זמן שהוגדר עם `schedule()`. |

כשה-session מריץ ticks, הגדר את [`tickIntervalMs`](#timer-handlers-and-settings). אם תשמיט את `shouldTick()`, ה-session לעולם לא יריץ ticks.

## מתודות לקריאה

מחלקת ה-actor מספקת יכולות מובנות. אלה המתודות שאפשר להשתמש בהן בזמן מימוש ה-handlers של actor.

| מתודה | מטרה |
| - | - |
| [`schedule()`](#timer-handlers-and-settings) | תזמון השכמה בזמן שאתה בוחר. |
| [`cancelSchedule()`](#timer-handlers-and-settings) | ביטול השכמה מתוזמנת. |
| [`conn.send()`](#connections) | תשובה ללקוח אחד. |
| [`conn.reject()`](#connections) | דחיית לקוח שמתחבר. |
| [`broadcast()`](#connections) | שליחה לכל הלקוחות ב-session. |
| [`getConnections()`](#connections) | הצגת הלקוחות המחוברים. |
| [`this.storage.get()`](#storage) | קריאת ערך session שמור. |
| [`this.storage.put()`](#storage) | שמירת ערך session. |
| [`this.storage.delete()`](#storage) | הסרת ערך שמור אחד. |
| [`this.storage.deleteAll()`](#storage) | ניקוי מאגר ה-session. |
| [`secrets.get()`](#read-secrets) | קריאת secret של האפליקציה. |

השתמש ב-[`this.client`](#entity-access) כדי לקרוא ולכתוב [entities](/he/developers/backend/resources/entities/overview).

## הצהרת המחלקה

ייבא את `Actor` מ-`base44:runtime/actors` וייצא כ-default export מחלקה שמרחיבה את `Actor`, מהקובץ `base44/actors/<actor-name>/entry.ts`.
שם התיקייה הופך לשם ה-actor ב-SDK. לפרטי הגדרה, ראה [יצירת actor](/he/developers/backend/resources/actors/create-actor).

<ResponseField name="Incoming" type="generic">
  מגדיר את הטיפוסים של ההודעות שה-actor מקבל מלקוחות מחוברים. חל על
  הפרמטר `msg` של `handleMessage()`.
</ResponseField>

<ResponseField name="Outgoing" type="generic">
  מגדיר את הטיפוסים של ההודעות שה-actor שולח ללקוחות מחוברים. חל על
  `conn.send()` ו-`broadcast()`.
</ResponseField>

## Runtime API

Actors מייבאים את המחלקה `Actor` מהמודול `base44:runtime/actors`:

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

### קריאת secrets

השתמש ב-`secrets.get()` כדי לקרוא את משתני הסביבה של האפליקציה מתוך handler. המתודה מחזירה את הערך כמחרוזת, או `undefined` כשה-secret לא מוגדר.

ייבא את `secrets` מהמודול `base44:runtime`:

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

הגדר secrets מה-CLI עם [`secrets set`](/he/developers/references/cli/commands/secrets-set).

מומלץ לקרוא ל-[פונקציית בקאנד](/he/developers/backend/resources/backend-functions/overview) לעבודה שדורשת secret. הפונקציה קוראת את ה-secret ומחזירה את התוצאה, כך שה-actor לעולם לא מקבל את ה-secret. לתהליך לדוגמה, ראה [קריאה לפונקציית בקאנד לעבודה עם secrets](/he/developers/backend/resources/actors/sample-flows#call-a-backend-function-for-secret-work).

## Handlers של מחזור חיים

Base44 קוראת ל-handlers האלה בתגובה לפעילות של לקוחות ב-session.
אתה מממש את הגוף של כל אחד מהם.
למידע נוסף, ראה [איך actors ולקוחות מתקשרים](/he/developers/backend/resources/actors/overview#how-actors-and-clients-interact).
לתהליך לדוגמה, ראה [ניהול חיבורי לקוחות](/he/developers/backend/resources/actors/sample-flows#manage-client-connections).

<ResponseField name="handleStart" type="method">
  רץ בכל פעם ש-session מופעל, למשל:

  * כשה-session נוצר לראשונה.
  * כשלקוח מתחבר ל-session לא פעיל.
  * כשהודעה מגיעה ל-session לא פעיל.
  * כשמגיע זמן מתוזמן.

  מחזיר `void` או `Promise<void>`.
</ResponseField>

<ResponseField name="handleConnect" type="method" required>
  רץ כשלקוח מתחבר ל-session.
  אפשר לשלוח את מצב ה-session הנוכחי עם `conn.send()`, או לדחות את החיבור עם `conn.reject()`.
  מחזיר `void` או `Promise<void>`.

  <Expandable title="פרמטרים">
    <ResponseField name="conn" type="Conn" required>
      מייצג את הלקוח שהתחבר.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="handleMessage" type="method" required>
  רץ כשלקוח מחובר שולח הודעה.
  אפשר לאמת את ההודעה לפני שינוי מצב ה-session או גישה לנתוני האפליקציה.
  מחזיר `void` או `Promise<void>`.

  <Expandable title="פרמטרים">
    <ResponseField name="conn" type="Conn" required>
      מייצג את הלקוח ששלח את ההודעה.
    </ResponseField>

    <ResponseField name="msg" type="Incoming" required>
      מכיל את ההודעה שנשלחה מהלקוח. ה-generic `Incoming` מגדיר
      את סוג ההודעה.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="handleClose" type="method" required>
  רץ כשלקוח מתנתק.
  השתמש ב-handler הזה כדי להסיר כל מצב session שקשור למזהה החיבור.
  התחברות מחדש עם אותו מזהה מחליפה את ה-socket הישן בלי להריץ את `handleClose()`.
  מחזיר `void` או `Promise<void>`.

  <Expandable title="פרמטרים">
    <ResponseField name="conn" type="Conn" required>
      מייצג את הלקוח שהתנתק.
    </ResponseField>
  </Expandable>
</ResponseField>

## Handlers והגדרות של טיימרים

ה-handlers וההגדרות האלה שולטים בעבודה מתוזמנת ב-session.
Base44 קוראת להם כשמגיע זמן מתוזמן, ולא בתגובה לפעילות של לקוחות.
למידע נוסף, ראה [עבודה מתוזמנת](/he/developers/backend/resources/actors/overview#scheduled-work).
לתהליכים לדוגמה, ראה [הרצת ticks](/he/developers/backend/resources/actors/sample-flows#run-ticks) ו[תזמון השכמות](/he/developers/backend/resources/actors/sample-flows#schedule-wakes).

<ResponseField name="handleTick" type="method" required>
  רץ פעם אחת בכל מרווח, כל עוד `shouldTick()` מחזיר `true` ויש ב-session לפחות לקוח אחד.
  מחזיר `void` או `Promise<void>`.
</ResponseField>

<ResponseField name="tickIntervalMs" type="number">
  מציין את המרווח בין ticks באלפיות שנייה. ברירת המחדל היא `100`.
</ResponseField>

<ResponseField name="shouldTick" type="method">
  מחזיר `boolean`. החזר `true` כדי להמשיך להריץ ticks, או `false` כדי לעצור. המתודה הזו סינכרונית.

  שמור על המתודה הזו מהירה וללא תופעות לוואי. Base44 קוראת לה אחרי כל חיבור, הודעה, ניתוק ו-tick.
</ResponseField>

<ResponseField name="handleWake" type="method">
  רץ פעם אחת כשמגיע זמן שהוגדר עם `schedule()`.
  מחזיר `void` או `Promise<void>`.

  <Expandable title="פרמטרים">
    <ResponseField name="key" type="string" required>
      מכיל את המפתח שהועבר ל-`schedule()`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="schedule" type="method">
  מתזמן הרצה אחת של `handleWake()` בזמן מסוים.
  מחזיר `Promise` שמסתיים אחרי ש-Base44 שומרת את התזמון.
  התזמון שורד תקופת חוסר פעילות ויכול להפעיל session לא פעיל.
  קריאה חוזרת למתודה עם אותו מפתח מחליפה את הזמן המתוזמן.

  <Expandable title="פרמטרים">
    <ResponseField name="key" type="string" required>
      מזהה את ההשכמה המתוזמנת. מועבר ל-`handleWake()` כשההשכמה מופעלת.
    </ResponseField>

    <ResponseField name="at" type="number | Date" required>
      מציין מתי `handleWake()` רץ. השתמש באובייקט `Date` או באלפיות שנייה
      מאז 1 בינואר 1970.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="cancelSchedule" type="method">
  מבטל את ההשכמה המתוזמנת שקשורה למפתח.
  מחזיר `Promise` שמסתיים אחרי ש-Base44 מנקה את התזמון.

  <Expandable title="פרמטרים">
    <ResponseField name="key" type="string" required>
      מציין את המפתח שהועבר ל-`schedule()`.
    </ResponseField>
  </Expandable>
</ResponseField>

## חיבורים

המאפיינים והמתודות האלה זמינים באובייקט `conn` שמועבר ל-handlers של מחזור חיים שמערבים לקוח.
השתמש בהם כדי לקרוא את זהות הלקוח, לשלוח הודעות ולנהל את החיבור.
לסקירה של שליחת הודעות, ראה [הודעות בזמן אמת](/he/developers/backend/resources/actors/overview#realtime-messages).
לתהליך לדוגמה, ראה [ניהול חיבורי לקוחות](/he/developers/backend/resources/actors/sample-flows#manage-client-connections).

<Note>
  `conn` הוא צד הבקאנד של ה-WebSocket, ו-`Connection` בלקוח הוא הצד השני של אותו socket. השתמש ב-`conn` במחלקת ה-actor. לאובייקט בצד הלקוח, ראה את תיעוד ה-SDK של `actors`.
</Note>

<ResponseField name="conn.id" type="string">
  מזהה את החיבור הזה. תואם למזהה שהלקוח העביר בעת ההתחברות,
  או למזהה שה-SDK יצר.
</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>
      מכיל את ההודעה שנשלחת לחיבור הזה. ה-generic `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>
      מתאר למה ה-actor דחה את החיבור.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="broadcast" type="method">
  שולח הודעה לכל חיבור חי ב-session. מחזיר `void`.

  <Expandable title="פרמטרים">
    <ResponseField name="data" type="Outgoing" required>
      מכיל את ההודעה שנשלחת לכל חיבור ב-session. ה-generic `Outgoing` מגדיר את סוג ההודעה.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="getConnections" type="method">
  מחזיר מערך של אובייקטי `conn` חיים ב-session. השתמש במתודה הזו
  ב-`handleStart()` כדי להתאים נתונים משוחזרים ללקוחות שנשארו מחוברים
  במהלך תקופת חוסר פעילות.
</ResponseField>

<ResponseField name="this.instanceId" type="string">
  מאפיין ברמת ה-session. מכיל את מזהה ה-session שהלקוח השתמש בו כדי להגיע
  ל-session הזה.
</ResponseField>

## אחסון

השתמש ב-`this.storage` כדי לקרוא ולכתוב נתוני session. בניגוד לשדות מחלקה, האחסון שורד תקופות של חוסר פעילות. לבחירה בין אחסון לשדות מחלקה, ראה [אחסון](/he/developers/backend/resources/actors/overview#storage). לתהליך לדוגמה, ראה [שמירת נתוני session](/he/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">
  מסיר ערך לפי מפתח. מחזיר `Promise` שמחזיר `true` כשהמפתח
  היה קיים, ו-`false` אחרת.

  <Expandable title="פרמטרים">
    <ResponseField name="key" type="string" required>
      מציין את המפתח להסרה.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.deleteAll" type="method">
  מסיר את כל הנתונים השמורים של ה-session. מחזיר `Promise` שמסתיים כש-
  המאגר ריק. חיבור מאוחר יותר מתחיל עם אותו אחסון ריק כמו
  session חדש.
</ResponseField>

## גישה ל-entities

השתמש ב-`this.client` וב-`this.client.asServiceRole` כדי לקרוא ולכתוב entities של האפליקציה מתוך handler של actor. לתהליך לדוגמה, ראה [כתיבת נתוני entity מתוך session](/he/developers/backend/resources/actors/sample-flows#write-entity-data-from-a-session).

<ResponseField name="this.client" type="Base44Client">
  מספק לקוח אפליקציה שמוגבל ל-session הזה. הלקוח משתמש באימות
  אנונימי, ולכן הגישה ל-entities כפופה לאותם כללים כמו של לקוח שלא
  מחובר לחשבון. הוא קורא נתוני ייצור.
</ResponseField>

<ResponseField name="this.client.asServiceRole" type="Base44Client">
  מספק גישה מורחבת שעוקפת את האבטחה ברמת השורה. אמת הודעות
  לפני שאתה משתמש בלקוח הזה. ודא שהכתיבות בטוחות לחזרה, כי ה-session עשוי להריץ handler
  שוב אחרי שגיאה.
</ResponseField>

## ראה גם

* [סקירת Actors](/he/developers/backend/resources/actors/overview): מושגים ומונחים
* [Actors: תהליכים לדוגמה](/he/developers/backend/resources/actors/sample-flows): מחזור חיים, טיימרים, חיבורים, אחסון, entities ופונקציות בקאנד
* [תיעוד ה-SDK של `actors`](/he/developers/references/sdk/docs/type-aliases/actors): ה-API של ה-SDK בצד הלקוח
* [`secrets set`](/he/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.