Sunucu betiği API'si

Sunucu betiği TypeScript ya da JavaScript'te tek bir defineScript({ … }) çağrısıdır. Editör bu adları tamamlar ve kaydetmeden önce tipleri denetler. Betik oluşturmak ve çalıştırmak için bkz. Sunucu betikleri.

defineScript

defineScript({
  tags: ["Line1.P1", { path: "Line1.Breaker", on: "any" }],
  every: "10s",
  at: "0 6 * * *",
  alarms: { tags: ["Boiler?.*"], minPriority: "high" },
  when: { expr: "ctx.value('Line1.P1') > 80", forMs: 2000 },
  timezone: "Europe/Istanbul",
  onStart(ctx) {},
  onChange(ctx, path, ev) {},
  onTimer(ctx) {},
  onSchedule(ctx, ev) {},
  onAlarm(ctx, alarm) {},
  onWhen(ctx, ev) {},
  onStop(ctx) {},
});

Bir betik defineScript'i bir kez çağırır. Birden çok tetikleyici birlikte kullanılabilir; işleyiciler art arda, asla aynı anda çalışmaz. Her işleyici async olabilir; hata ya da reddedilen bir promise betiğin hatası sayılır.

Tetikleyiciler

Seçenek	Biçim	Çağırır
`tags`	Yol listesi; bir öğe `{ path, on, deadband }` olabilir, `on` = `"value"` (varsayılan), `"quality"` ya da `"any"`	`onChange`
`every`	Süre: önceki çalışma bittikten sonra sabit gecikme. `{ rate: "10s" }`: sabit hız; önceki çalışma sürerken gelen tik atlanır. `{ delay: "10s" }` düz biçimle aynıdır. En az 50 ms.	`onTimer`
`at`	5 alanlı cron (dakika saat gün ay haftanın günü), bir kez çalışan ISO tarih ve saat (`2026-12-31T23:59:00`, isteğe bağlı `Z` ya da `+03:00` ile) ya da bunların listesi	`onSchedule`
`alarms`	`{ tags, states, minPriority }`: `*` ve `?` ile yol desenleri (boş: tüm alarmlar); durumlar `"came"`, `"went"`, `"acked"` (boş: üçü); `minPriority` `"low"`, `"medium"`, `"high"`, `"critical"` ya da 0–3	`onAlarm`
`when`	Bir ya da birkaç `{ expr, forMs, edge, name }`: `expr` metin ya da `ctx`'in işlevi; `forMs` yeni durumun ne kadar sürmesi gerektiği; `edge` `"rising"` (varsayılan), `"falling"` ya da `"both"`	`onWhen`
`timezone`	`at` için saat dilimi; betiğin Time zone (cron) ayarı önceliklidir; boş: sunucunun yerel saati	—

Süreler "500ms", "10s", "1m", "1h" ya da milisaniye sayısı olarak yazılır.

when koşulu yalnız tags'tekilerden biri değişince (ve forMs geçince) değerlendirilir: ifadenin okuduğu sinyalleri tags'e yazın. İlk değerler gelince (en geç 5 saniye sonra) başlangıç durumu kenar üretilmeden kurulur; böylece yeniden başlatma sahte bir kenar tetiklemez.

İşleyiciler ve olaylar

İşleyici	Ne zaman	Olay
`onStart(ctx)`	Betik başlayınca	—
`onChange(ctx, path, ev)`	`tags`'teki bir sinyal değişince	`ev.prev`, `ev.cur`: `{ value, quality, ts }` ya da `null`; `ev.initial`: başlangıçtan sonraki ilk değer; `ev.qualityOnly`: yalnız kalite değişti; `ev.missed`: betik meşgulken birleşen değişimler
`onTimer(ctx)`	`every` dolunca	—
`onSchedule(ctx, ev)`	`at` zamanı gelince	`ev.at`: tetikleyen öğe; `ev.missed`: betik dururken kaçırılan, başlangıçta bir kez telafi edilen çalışma
`onAlarm(ctx, alarm)`	Bir alarm gelince, gidince ya da onaylanınca	`id`, `defId`, `path`, `state`, `priority`, `priorityLevel`, `text`, `ts`, `value`, `user` (onaylayan), `area`, `alarmClass`, `level`, `description`
`onWhen(ctx, ev)`	Bir `when` koşulunun kenarı oluşunca	`index`, `name`, `edge`, `value`, `ts`
`onStop(ctx)`	Betik yeniden kaydedilince, etkinliği kapatılınca ya da servis düzgün durunca	— ; en çok işleyici süre sınırı ve 5 saniye sürebilir

ev.initial, onStart'tan sonra her sinyal için son değer deposundan ya da ilk canlı değerden bir kez true gelir. Yeniden başlatmadan sonra sahte kenarları önlemek için prev ile cur'u ancak bundan sonra karşılaştırın. Aynı değer yeniden gelince onChange çağrılmaz (on: "value" ile).

Bir betiğe saniyede en çok 50 alarm olayı (anlık 200) iletilir ve en çok 256'sı bekler; fazlası atlanır ve Skipped'te sayılır. Alarm süzgecini dar tutun.

ctx

Üye	Döndürür	Anlamı
`ctx.value(yol)`	Değer ya da `undefined`	Bir sinyalin son değeri; okumak ona abone de olur
`ctx.quality(yol)`	Metin	`"good"`, `"uncertain"`, `"bad"`, `"not_connected"`, `"overflow"`, `"substituted"` ya da sinyal yoksa `"unknown"`
`ctx.ts(yol)`	Milisaniye	Son değişimin zamanı
`ctx.setTag(yol, değer)`	—	Sayı, açık/kapalı ya da metin yazar; bkz. Yazma. Reddedilince hata fırlatır
`ctx.log(...)`, `ctx.warn(...)`, `ctx.error(...)`	—	Betik günlüğüne yazar; `console.log` / `warn` / `error` da aynısını yapar
`ctx.now()`	Milisaniye	Şimdiki zaman
`ctx.state.get(anahtar)`, `ctx.state.set(anahtar, değer)`	Değer	Betiğin yeniden başlatmalarda korunan kalıcı durumu; en çok 1000 anahtar ve değer başına 64 KB
`ctx.lib(ad)`	Nesne	Paylaşılan bir kütüphane
`ctx.dryRun`	Açık/kapalı	Hiçbir şeyin yazılmadığı deneme çalıştırmasında true

Bir betik saniyede en çok 200 günlük satırı yazar.

Yazma

Hedef	Kural
Dahili bellek sinyali	Her zaman serbest
Bir sürücünün sinyali (saha noktası)	Yalnız Can command field points açıkken ve yol Command target patterns'ten birine uyuyorsa; Command rate limit (per minute) içinde. Bir komuttur: komut kaydına tetikleyici (`onChange:<yol>`, `every`, `at`, `alarm:<yol>`, `when`, `onStop`) ve sürümle `script:<ad>` olarak yazılır
Sürücüsü olmayan sinyal noktası	Yalnız Can publish computed values açıkken ve yol Publish target patterns'ten birine uyuyorsa: değer o noktanın değeri olarak yayınlanır. Komut değildir, komut kaydı yoktur
`System.`, `Alarms.`, `Session.*`, hesaplanan dahili sinyaller	Reddedilir

Desenler * (herhangi bir dizi) ve ? (tek karakter) kullanır, örneğin Line1.* ya da Boiler?.Sp.

Betiğin hangi noktalara komut verebileceğini kalıplar belirler: komut hedeflerini olabildiğince dar tutun. Sorumluluk alanları betiklere uygulanmaz ve betik bir elektrik cihazının komut noktasına yazamaz. YTCC'nin göndermeden reddettiği yazma (izin, kalıp, hız sınırı, elektrik cihazı) hata fırlatır ve Rejected'te sayılır. ctx.setTag sürücüyü beklemez: sürücünün reddettiği ya da zaman aşımına uğrayan komut hata fırlatmaz; komut kaydında görünür.

Yayınlanan değerler:

noktanın veri tipine çevrilir (açık/kapalı nokta true'yu, sıfır olmayan bir sayıyı ya da "true" / "1" metnini alır; tam sayılar yuvarlanır ve aralığa sığmalıdır; liste, nesne ve null reddedilir);
nokta başına saniyede en çok 10 kez gönderilir; daha hızlı değişimler birleşir ve son değer her zaman ulaşır;
betiğin kalitesini taşır: betik durunca, yüklenemeyince ya da karantinaya alınınca noktalar 6 saniye içinde Bad · Not connected olur;
betiğin kendi onChange'ini tetiklemez (yankı döngüsü yok);
betik başına tags sayısı artı 10 000 noktayla sınırlıdır.

İki betik aynı noktayı yayınlarsa son yazan kazanır; editör çakışan desenler için uyarır.

defineLibrary

defineLibrary("common", {
  average(...xs: number[]) { return xs.reduce((a, b) => a + b, 0) / Math.max(1, xs.length); },
});

İlk bağımsız değişken kütüphanenin kaydedildiği adla aynı olmalıdır. Kütüphanenin kendi süreci, izinleri ya da günlüğü yoktur: onu kullanan betiğin içinde, o betiğin izinleriyle çalışır. YTCC'nin kütüphane değişince hangi betikleri yeniden yükleyeceğini bilmesi için adı ctx.lib("common") içinde sabit metin olarak yazın.

Durum sinyalleri

Her betiğin ekranlarda, alarmlarda ve tarihçede kullanılabilen System.Scripts.<ad>.* sinyalleri vardır:

Sinyal	Anlamı
`Running`, `Quarantined`	Betik çalışıyor; karantinada
`Version`	Çalışan sürüm
`Runs`, `Errors`	İşleyici çalışma ve hata sayısı
`LastRun`, `LastError`	Son çalışmanın zamanı; son hatanın metni
`AvgMs`	Ortalama çalışma süresi
`Commands`, `Rejected`	Gönderilen komutlar; reddedilen yazmalar
`Published`	Gerçekten yayınlanan değerler
`Skipped`	Betik meşgul olduğu ya da bir sınıra ulaşıldığı için atlanan tikler ya da alarm olayları

Sınırlar

Sınır	Varsayılan	Aralık	Aşılırsa
Memory limit (MB)	64	8–1024	Betik durdurulur ve yeniden başlatılır
Handler time limit (ms)	1000	10–60000	Çağrı kesilir ve hata sayılır
Command rate limit (per minute)	60	1–6000	Komut reddedilir

Betiğin dosyalara, ağa ya da başka programlara erişimi yoktur. Süreci beş dakikada beş kez çökerse betik karantinaya alınır: bekler ve yüksek öncelikli bir script_<ad> sistem alarmı üretilir. Betiği yeniden kaydetmek karantinayı kaldırır.

defineScript​

Tetikleyiciler​

İşleyiciler ve olaylar​

ctx​

Yazma​

defineLibrary​

Durum sinyalleri​

Sınırlar​