IronFlock SDK

IronFlock SDK, edge uygulamalarınızın IronFlock platformuyla etkileşim kurmasını sağlar. Aynı işlevselliğe sahip üç dilde sunulur — Python, JavaScript ve Go — ve aşağıda yan yana belgelenmiştir. Kayıtlı bir cihazda çalışırken kimlik doğrulamayı otomatik olarak yönetir; veri yayımlama, geçmiş sorgulama, cihazlar arası uzak prosedür çağırma ve cihaz meta verisini güncelleme işlevleri sunar.

Kurulum

pip install ironflock

npm install ironflock

go get github.com/RecordEvolution/ironflock-go

Hızlı Başlangıç

import asyncio
from datetime import datetime, timezone
from ironflock import IronFlock
 
async def main():
    while True:
        await ironflock.publish_to_table("sensordata", {
            "tsp": datetime.now(timezone.utc).isoformat(),
            "temperature": 22.5,
            "humidity": 60
        })
        await asyncio.sleep(5)
 
ironflock = IronFlock(mainFunc=main)
ironflock.run()

import { IronFlock } from "ironflock";
 
const ironflock = new IronFlock();
await ironflock.start();
 
setInterval(async () => {
    await ironflock.publishToTable("sensordata", [{
        tsp: new Date().toISOString(),
        temperature: 22.5,
        humidity: 60
    }]);
}, 5000);

package main
 
import (
	"context"
	"log"
	"time"
 
	ironflock "github.com/RecordEvolution/ironflock-go"
)
 
func main() {
	ifl, err := ironflock.New()
	if err != nil {
		log.Fatal(err)
	}
 
	// Run connects, runs main, and shuts down when main returns or on SIGINT/SIGTERM.
	err = ifl.Run(context.Background(), func(ctx context.Context) error {
		ticker := time.NewTicker(5 * time.Second)
		defer ticker.Stop()
		for {
			row := ironflock.Row{"tsp": time.Now(), "temperature": 22.5, "humidity": 60}
			if err := ifl.PublishToTable(ctx, "sensordata", row); err != nil {
				log.Print(err)
			}
			select {
			case <-ctx.Done():
				return nil
			case <-ticker.C:
			}
		}
	})
	if err != nil {
		log.Fatal(err)
	}
}

Bir IronFlock uygulama container’ı içinde kullanıldığında SDK, bağlantı kimlik bilgilerini ortamdan otomatik olarak okur — manuel yapılandırma gerekmez. Bir tabloya yazdığınız her satır, zaman damgası olan bir tsp taşır (bkz. publishToTable).

Yapıcı Seçenekleri

ironflock = IronFlock(
    mainFunc=main,           # async function to run after connecting
    serial_number="abc123",  # override device serial (optional)
    reconnect_window=60,     # seconds a table operation rides out a platform restart (optional)
)

const ironflock = new IronFlock({
    serialNumber: "abc123",    // device serial (env: DEVICE_SERIAL_NUMBER)
    deviceKey: "12",           // numeric device key (env: DEVICE_KEY)
    appName: "MyApp",          // app name (env: APP_NAME)
    swarmKey: 10,              // project key (env: SWARM_KEY)
    appKey: 20,                // app key (env: APP_KEY)
    env: "PROD",               // "DEV" or "PROD" (env: ENV)
    reconnectWindowMs: 60000,  // how long a table operation rides out a platform restart
});

ifl, err := ironflock.New(
	ironflock.WithSerialNumber("abc123"),          // device serial (env: DEVICE_SERIAL_NUMBER)
	ironflock.WithReconnectWindow(60*time.Second), // how long a table operation rides out a platform restart
)
if err != nil {
	log.Fatal(err) // no serial number in the environment or the options
}

Veri Yayımlama

publishToTable / publish_to_table

Bir filo tablosuna veri kaydı yayımlar. Tablo adı, uygulamanızın data-template.yml dosyasında tanımlanan bir tabloyla eşleşmelidir. SDK, veriyi doğru proje veritabanına otomatik olarak yönlendirir.

from datetime import datetime, timezone
 
await ironflock.publish_to_table("sensordata", {
    "tsp": datetime.now(timezone.utc).isoformat(),
    "temperature": 22.5,
    "humidity": 60,
    "device_id": "sensor-001"
})

await ironflock.publishToTable("sensordata", [{
    tsp: new Date().toISOString(),
    temperature: 22.5,
    humidity: 60,
    device_id: "sensor-001"
}]);

err := ifl.PublishToTable(ctx, "sensordata", ironflock.Row{
	"tsp":         time.Now(),
	"temperature": 22.5,
	"humidity":    60,
	"device_id":   "sensor-001",
})
if err != nil {
	return err
}

Veri arka ucu satırı ilk argümandan okur: Python’da bir dict, JavaScript’te dizinin ilk öğesi, Go’da ilk konumsal argüman (bir map veya bir struct). Ek anahtar kelime argümanları — Go’da argümanlar arasındaki bir ironflock.Kwargs değeri — yalnızca veri şablonunun onlara eşlediği sütunlar için okunur (kwargs.<name>).

Her satırın bir tsp’ye ihtiyacı vardır. Her tablonun zorunlu bir tsp sütunu vardır: satırın zaman damgası — ör. bir ISO 8601 dizesi ya da Go’da UTC’de RFC 3339 olarak gönderilen bir time.Time —; veri şablonu onu başka bir yere eşlemedikçe veri arka ucu bunu satırdan okur. tsp içermeyen yayımlanmış bir satırı düşürür ve bunun tek izi uygulamanın error-logs tablosundaki bir girdidir — onaylanan yayımlama başarılı görünür. Depolama yetersizliği nedeniyle reddettiği bir satır ise bu iz bile olmadan düşürülür. Bir satırın saklanıp saklanmadığını bilmeniz gerektiğinde appendToTable / append_to_table kullanın.

Varlık tablolarında kısmi satırlar. Varlık anahtarı olan bir tabloda (maintainLatestFlagFor) bir satır yalnızca varlık anahtarını, tsp’yi ve değişen sütunları taşıyabilir. Satırın dışarıda bıraktığı bir sütun varlığın önceki değerini korur; None / null / nil olarak gönderilen bir sütun temizlenir. Bir alanın dışarıda bırakılmış sayılıp sayılmayacağı satırı nasıl oluşturduğunuza bağlıdır:

• Python: değeri None olan bir anahtar null olarak gönderilir ve sütunu temizler. Eski değeri korumak için anahtarı dict’ten kaldırın.
• JavaScript: değeri undefined olan bir özellik veri yükünden düşer, bu yüzden eski değeri korur. Sütunu temizlemek için onu null yapın.
• Go: omitempty veya omitzero etiketli bir struct alanı boş olduğunda dışarıda bırakılır, bu yüzden eski değeri korur. Aksi halde nil bir işaretçi alanı, bir ironflock.Row içindeki nil değer gibi, null olarak gönderilir ve sütunu temizler.

Aynısı dört yazma yönteminin tümü için geçerlidir. Varlık anahtarı olmayan bir tabloda, satırın dışarıda bıraktığı bir sütun NULL olarak saklanır.

appendToTable / append_to_table

Yayımla/abone ol yerine uzak prosedür çağrısı kullanarak filo tablosuna veri ekler. Verinin kalıcı hale getirildiğine dair onay gerektiğinde bunu kullanın: reddedilen bir satır bir hatadır.

result = await ironflock.append_to_table("sensordata", {
    "tsp": datetime.now(timezone.utc).isoformat(),
    "temperature": 22.5,
    "humidity": 60
})

const result = await ironflock.appendToTable("sensordata", [{
    tsp: new Date().toISOString(),
    temperature: 22.5,
    humidity: 60
}]);

result, err := ifl.AppendToTable(ctx, "sensordata", ironflock.Row{
	"tsp":         time.Now(),
	"temperature": 22.5,
	"humidity":    60,
})
if err != nil {
	return err // the row was refused, or the call failed
}
log.Println(result.Value())

Satırın, publishToTable’da olduğu gibi bir tsp’ye ihtiyacı vardır. Veri arka ucu tsp içermeyen bir satırı wamp.error.runtime_error ile ve bir neden belirtmeden reddeder; SDK’nın hatası bu durumda şunu ekler: “the data backend refused the row without a reason — a missing tsp is the usual cause; see the error-logs table”. Bir appliance’ta dolan disk gibi türü belirli retler Veri Arka Ucu Retleri altında listelenir.

publishRowsToTable / publish_rows_to_table

Bir filo tablosuna tek bir mesajda birden çok satır (toplu ekleme) yayımlar. Platform, tüm yığını tek bir işlemde atomik olarak (ya hep ya hiç) ekler. Satır başına bir gidiş-dönüşün çok maliyetli olacağı yüksek frekanslı veriler için bunu kullanın. publishToTable gibi bu da gönder-unut prensibiyle çalışır — onay, veritabanı eklemesini değil, yönlendiriciye teslimi doğrular.

await ironflock.publish_rows_to_table("sensordata", [
    {"tsp": "2024-01-15T10:30:00.000Z", "temperature": 22.5},
    {"tsp": "2024-01-15T10:30:01.000Z", "temperature": 22.7},
])

await ironflock.publishRowsToTable("sensordata", [
    { tsp: "2024-01-15T10:30:00.000Z", temperature: 22.5 },
    { tsp: "2024-01-15T10:30:01.000Z", temperature: 22.7 },
]);

err := ifl.PublishRowsToTable(ctx, "sensordata", []ironflock.Row{
	{"tsp": "2024-01-15T10:30:00.000Z", "temperature": 22.5},
	{"tsp": "2024-01-15T10:30:01.000Z", "temperature": 22.7},
})
if err != nil {
	return err
}

İkinci argüman, her biri kendi tsp’sine sahip, eklenecek satır nesnelerinden oluşan boş olmayan bir listedir — Go’da bir satır slice’ı ([]ironflock.Row, []map[string]any veya bir struct slice’ı). Veri arka ucunun reddettiği bir yığın — örneğin bir satırın tsp’si eksik olduğu için — publishToTable’da olduğu gibi yayımlayana tek söz söylenmeden düşürülür.

appendRowsToTable / append_rows_to_table

Bir filo tablosuna tek bir uzak prosedür çağrısında birden çok satır (toplu ekleme) ekler. Platform, tüm yığını atomik olarak (ya hep ya hiç) ekler: herhangi bir satır geçersizse tüm yığın reddedilir ve hiçbir şey kalıcı hale getirilmez. Ekleme sonucuna ihtiyacınız olduğunda bunu publishRowsToTable / publish_rows_to_table yerine tercih edin. Her satırın kendi tsp’sine ihtiyacı vardır; retler, nedensiz reddedilen bir yığın için verilen ipucu dahil, appendToTable ile aynıdır.

result = await ironflock.append_rows_to_table("sensordata", [
    {"tsp": "2024-01-15T10:30:00.000Z", "temperature": 22.5},
    {"tsp": "2024-01-15T10:30:01.000Z", "temperature": 22.7},
])
# result -> {"success": True, "count": 2}

const result = await ironflock.appendRowsToTable("sensordata", [
    { tsp: "2024-01-15T10:30:00.000Z", temperature: 22.5 },
    { tsp: "2024-01-15T10:30:01.000Z", temperature: 22.7 },
]);
// result -> { success: true, count: 2 }

result, err := ifl.AppendRowsToTable(ctx, "sensordata", []ironflock.Row{
	{"tsp": "2024-01-15T10:30:00.000Z", "temperature": 22.5},
	{"tsp": "2024-01-15T10:30:01.000Z", "temperature": 22.7},
})
if err != nil {
	return err // the whole batch was refused, or the call failed
}
log.Println(result.Value()) // map[count:2 success:true]

reportError / report_error

Bir uygulama hatasını filonuzun error-logs tablosuna raporlar. Bu, publishToTable / appendToTable üzerine kullanışlı bir sarmalayıcıdır: satırı source: "app", bir önem level değeri ve bir zaman damgasıyla işaretler, ardından onu herhangi bir normal tablo satırı gibi yazar. Hata, fleetdb sistem hatalarının kullandığı (source: "system" olarak etiketlenmiş) aynı error-logs tablosuna düşer; bu nedenle getHistory ile sorgulanabilir, subscribeToTable / subscribe_to_table ile akışa alınabilir, board-template’lerde kullanılabilir ve transformed.error-logs üzerinde gerçek zamanlı olarak teslim edilir — platformun sistem hatası bildirimini tetiklemeden.

# Fire-and-forget (default): publishes to the error-logs table
await ironflock.report_error("Sensor read timed out", level="warn")
 
# Pass an exception to capture its traceback (falls back to the message)
try:
    risky_operation()
except Exception as err:
    await ironflock.report_error(err)
 
# Use the append RPC when you want to await the insert outcome, and show the
# operator a friendlier line than the raw error
await ironflock.report_error(
    "Calibration failed: offset 0.42 out of range",
    append=True,
    user_message="Please recalibrate the sensor",
)

// Fire-and-forget (default): publishes to the error-logs table
await ironflock.reportError("Sensor read timed out", { level: "warn" });
 
// Pass an Error to capture its stack (falls back to the message)
try {
    riskyOperation();
} catch (err) {
    await ironflock.reportError(err);
}
 
// Use the append RPC when you want to await the insert outcome, and show the
// operator a friendlier line than the raw error
await ironflock.reportError("Calibration failed: offset 0.42 out of range", {
    append: true,
    userMessage: "Please recalibrate the sensor",
});

// Fire-and-forget (default): publishes to the error-logs table
ifl.ReportError(ctx, "Sensor read timed out", ironflock.ReportErrorOptions{Level: ironflock.LevelWarn})
 
// Pass an error: it is recorded with %+v, so an error that carries a stack trace includes it
if err := riskyOperation(); err != nil {
	ifl.ReportError(ctx, err)
}
 
// Use the append RPC when you want the insert outcome, and show the
// operator a friendlier line than the raw error
_, err := ifl.ReportError(ctx, "Calibration failed: offset 0.42 out of range", ironflock.ReportErrorOptions{
	Append:      true,
	UserMessage: "Please recalibrate the sensor",
})
if err != nil {
	return err
}

Satır { tsp, msg, user_message, source: "app", level } biçimindedir: msg teknik metni (bir traceback ya da stack) tutar; user_message ise board’un hata bildiriminin (toast) gösterdiği metni: ilettiğiniz kullanıcı mesajını ya da, verilmediyse, mesajın kendisini.

Parametreler:

Python’da seçenekler anahtar kelime argümanlarıdır (report_error(error, level=..., append=..., tsp=..., user_message=...)); JavaScript’te bir seçenekler nesnesi aracılığıyla geçilir (reportError(error, { level, append, tsp, userMessage })); Go’da ise bir struct aracılığıyla (ReportError(ctx, errOrMsg, ironflock.ReportErrorOptions{Level, Append, Tsp, UserMessage})). Burada errOrMsg bir error veya bir dizedir, Level ironflock.LevelError, LevelWarn, LevelInfo, LevelDebug değerlerinden biridir ve döndürülen *Result, Append ayarlanmadıkça nil’dir.

publish

Kendinize ait bir WAMP konusuna mesaj yayımlar. Veritabanı tablosuna eşlenmeyen özel mesajlaşma veya olaylar için bunu kullanın. Yönlendirici bazı adları platform için ayırır — bkz. Bir Uygulamanın Kullanabileceği URI’ler.

await ironflock.publish("com.myapp.alerts", {
    "level": "warning",
    "message": "Temperature threshold exceeded"
})

await ironflock.publish("com.myapp.alerts", [{
    level: "warning",
    message: "Temperature threshold exceeded"
}]);

err := ifl.Publish(ctx, "com.myapp.alerts", map[string]any{
	"level":   "warning",
	"message": "Temperature threshold exceeded",
})
if err != nil {
	return err // the router refused the publish, or there was no connection
}

Geçmiş Veri Sorgulama

getHistory

Bir filo tablosundan veya transform’dan geçmiş verileri getirir: eşleşen en yeni satırları, artan tsp sırasıyla. Filtreleme, zaman aralığı ve sayfalama desteklenir.

# Simple query
data = await ironflock.getHistory("sensordata", {"limit": 100})
 
# Query with time range and filters
data = await ironflock.getHistory("sensordata", {
    "limit": 500,
    "offset": 0,
    "timeRange": ["2026-01-01T00:00:00Z", "2026-03-01T00:00:00Z"],
    "filterAnd": [
        {"column": "temperature", "operator": ">", "value": 20},
        {"column": "humidity", "operator": "<=", "value": 80}
    ]
})
 
# Current value(s) only: the "latest" marker returns the newest row per entity
current = await ironflock.getHistory("sensordata", {
    "limit": 100,
    "filterAnd": [{"latest": True}]
})
 
# One field of a large json column: the column comes back pruned to its paths
readings = await ironflock.getHistory("sensordata", {
    "limit": 100,
    "columns": ["json_data"],
    "columnPaths": ["json_data.sensor.temp"],
})

// Simple query
const data = await ironflock.getHistory("sensordata", { limit: 100 });
 
// Query with time range and filters
const data = await ironflock.getHistory("sensordata", {
    limit: 500,
    offset: 0,
    timeRange: ["2026-01-01T00:00:00Z", "2026-03-01T00:00:00Z"],
    filterAnd: [
        { column: "temperature", operator: ">", value: 20 },
        { column: "humidity", operator: "<=", value: 80 },
    ],
});
 
// Current value(s) only: the `latest` marker returns the newest row per entity
const current = await ironflock.getHistory("sensordata", {
    limit: 100,
    filterAnd: [{ latest: true }],
});
 
// One field of a large json column: the column comes back pruned to its paths
const readings = await ironflock.getHistory("sensordata", {
    limit: 100,
    columns: ["json_data"],
    columnPaths: ["json_data.sensor.temp"],
});

// Simple query
data, err := ifl.GetHistory(ctx, "sensordata", &ironflock.TableQueryParams{Limit: 100})
if err != nil {
	return err
}
 
// Query with time range and filters
data, err = ifl.GetHistory(ctx, "sensordata", &ironflock.TableQueryParams{
	Limit:  500,
	Offset: 0,
	TimeRange: ironflock.Between(
		time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC),
		time.Date(2026, 3, 1, 0, 0, 0, 0, time.UTC),
	),
	FilterAnd: []ironflock.Filter{
		ironflock.Where("temperature", ">", 20),
		ironflock.Where("humidity", "<=", 80),
	},
})
 
// Current value(s) only: the Latest() marker returns the newest row per entity
current, err := ifl.GetHistory(ctx, "sensordata", &ironflock.TableQueryParams{
	Limit:     100,
	FilterAnd: []ironflock.Filter{ironflock.Latest()},
})
 
// One field of a large json column: the column comes back pruned to its paths
readings, err := ifl.GetHistory(ctx, "sensordata", &ironflock.TableQueryParams{
	Limit:       100,
	Columns:     []string{"json_data"},
	ColumnPaths: []string{"json_data.sensor.temp"},
})

Sorgu parametreleri:

Go’da bunlar ironflock.TableQueryParams türünün Limit, Offset, TimeRange, FilterAnd, Columns ve ColumnPaths alanlarıdır. TimeRange bir *ironflock.TimeRange{Start, End} değeridir: her sınır bir time.Time, bir ISO 8601 dizesi, bir epoch milisaniye sayısı ya da açık bir uç için nil olabilir (ironflock.Between, Since ve Until, time.Time değerlerinden bir aralık oluşturur). FilterAnd bir []ironflock.Filter değeridir. Eski nesne biçimi yoktur.

Filtre operatörleri: =, !=, <>, >, <, >=, <=, LIKE, ILIKE, NOT LIKE, NOT ILIKE, IN, NOT IN, IS NULL, IS NOT NULL

Her filtre koşulu column, operator ve value anahtarlarına sahip bir nesnedir — Go’da ironflock.Where(column, operator, value), ironflock.IsNull(column) ve ironflock.IsNotNull(column) ile oluşturulur. Operatörler büyük/küçük harf fark etmeksizin, çevresindeki boşluklar yok sayılarak eşleştirilir ve yukarıda listelenen biçimde — veri arka ucunun kabul ettiği tek biçimde — gönderilir; böylece "like", gruplar içinde de "LIKE" olarak gider. Listenin dışındaki bir operatör, bir uyarıyla birlikte verildiği gibi gönderilir. IS NULL ve IS NOT NULL bir value almaz ve NULL’ı sorgulamanın tek yoludur: diğer her operatör, sütunu NULL olan bir satırı tam SQL’deki gibi dışarıda bırakır. IN ve NOT IN bir liste alır (Go’da bir slice). LIKE büyük/küçük harfe duyarlıdır; duyarsız eşleştirme için ILIKE kullanın.

OR ile birleştirme. filterAnd girdileri AND ile birleştirilir. Bir grup girdisi kendi girdilerini — koşulları, latest işaretini veya başka grupları — tek bir operatörle, "AND" ya da "OR" ile birleştirir:

# Rows that are not soft-deleted: deleted IS NULL OR deleted = false
"filterAnd": [
    {
        "combinator": "OR",
        "filters": [
            {"column": "deleted", "operator": "IS NULL"},
            {"column": "deleted", "operator": "=", "value": False},
        ],
    }
]

// Rows that are not soft-deleted: deleted IS NULL OR deleted = false
filterAnd: [
    {
        combinator: "OR",
        filters: [
            { column: "deleted", operator: "IS NULL" },
            { column: "deleted", operator: "=", value: false },
        ],
    },
]

// Rows that are not soft-deleted: deleted IS NULL OR deleted = false
q := &ironflock.TableQueryParams{
	Limit: 100,
	FilterAnd: []ironflock.Filter{
		ironflock.Or(
			ironflock.IsNull("deleted"),
			ironflock.Where("deleted", "=", false),
		),
	},
}

Gruplardan önceki bir veri arka ucu (v1.2.0 öncesi fleetdb) bu yapının bir kısmını uygulamak yerine onu reddeder; böylece filtrenin dışarıda bıraktığı satırları sessizce döndürmek yerine açıkça başarısız olur.

Güncel değerleri okuma. filterAnd içindeki bir {"latest": true} girdisi (Go’da ironflock.Latest()) bir filtre koşulu değil, bir mod anahtarıdır: veri arka ucu yalnızca varlık başına en yeni satırı döndürür; bu satır, tablonun maintainLatestFlagFor ile bildirdiği varlık anahtarından SQL’de türetilir. Varlık anahtarı olmayan bir tablo, yalnızca en son tek satırını döndürür.

Diğer koşullar bu işaretle beklediğiniz gibi birleşir: varlık anahtarı sütunları üzerindeki koşullar hangi varlıkların döndürüleceğini daraltır; diğer tüm koşullar ve timeRange ise elde edilen en son satırlara uygulanır. Yani {"latest": true} ile bir deleted filtresini birleştirmek, silinen varlıkların önceki satırını yeniden ortaya çıkarmak yerine bu varlıkları gizler.

IronFlock’un önceki sürümleri fiziksel bir latest_flag sütunu saklıyordu. Bu sütun artık mevcut değil — eski bir latest_flag = true filtresi hâlâ kabul edilir ve bu işaret gibi ele alınır, ancak yeni kodlar {"latest": true} kullanmalıdır. latest işareti getSeriesHistory içinde kullanılamaz.

Zaman aralıkları. Veri arka ucu, dize olarak verilen bir sınırı JavaScript’in Date nesnesiyle okur; bu yüzden bir ISO 8601 tarihi veya tarih-saati yazın (2026-07-01, 2026-07-01T12:30:15.250Z) ve tarih ile saati T ile ayırın. SDK’lar, Date’in yanlış okuduğu 0–99 yıllarında tarih ile saat arasındaki boşluğu reddeder: "0001-01-01 00:00:00" — Python’da str(datetime.min) ifadesinin verdiği değer — 2001 olarak okunurdu. Saat dilimi olmayan bir saat UTC olarak okunur. Sayısal bir sınır epoch milisaniyesidir ve sonlu olmalıdır: NaN ve ±Infinity veri arka ucuna açık bir sınır olarak ulaşır ve zaman filtresini sessizce düşürürdü; bu yüzden SDK’lar bunları göndermeden önce reddeder. Go’da bir time.Time sınırı UTC’de RFC 3339 olarak gönderilir; bir dize sınırı ise Date’in doğru okuduğu ISO 8601 biçimlerinden biri olmalıdır — bir tarih ya da isteğe bağlı bir Z veya UTC farkı (+02:00 veya +0200) içeren bir tarih ve günün saati; temel biçim 20260701T123000Z, yalnızca saatten oluşan bir fark veya ayda bulunmayan bir gün (2026-02-30) gibi diğer dizeler, hiçbir şey gönderilmeden önce ironflock.ErrInvalidArgument ile başarısız olur.

Transform’lar. Bir transform (bir veri şablonunun SQL görünümü, bkz. Dönüşüm Tabloları) bir tablodan farklı okunur. Veri arka ucu yalnızca limit — en fazla 3000; daha büyüğü URI_INVALID_LIMIT ile reddedilir —, offset ve filterAnd uygular. timeRange, columns, columnPaths ve latest işaretini yok sayar; transform’un tanımlamadığı bir sütun üzerindeki filtreyi düşürür (bir transform’un örtük tsp, device_key veya authid sütunu yoktur), bu da sonucu genişletir. Satırları, görünümün kendi sırasının tersiyle gelir: en yeni satırları en eskiden başlayarak yalnızca görünüm en yeniden başlayarak sıraladığında alırsınız. Bir transform’un zaman aralığını SQL’inde sınırlayın.

Büyük sonuçlar. Veri arka ucunun tek bir mesajına (8 MiB JSON) sığmayacak kadar büyük bir sonuç parçalar halinde gelir ve SDK bunları bellekte yeniden birleştirir: tek bir okumanın satırlarını aynı sırayla alırsınız. Tutmayan parçalar — biri eksik veya yinelenmiş ya da satır sayısı veri arka ucunun özetinden farklı — satırların bir kısmını döndürmek yerine okumayı başarısız kılar. 8 MiB’ı aşan tek bir satır veya veri arka ucunun 1 GiB korumasını aşan bir sonuç URI_RESULT_TOO_LARGE ile reddedilir: limit değerini düşürün, timeRange aralığını daraltın, daha az columns seçin veya columnPaths ile budayın.

getSeriesHistory / get_series_history

Bir filo tablosundan alt örneklenmiş zaman serisi verileri alır: zaman kovası başına toplanan sütunlar (ör. saatlik ortalamalar). Uzun zaman aralıklarını kapsayan grafikler için idealdir. Tablolar için (transform’lar için değil), fleetdb v1.0.58 ve sonrasındaki veri arka uçlarında kullanılabilir.

from datetime import datetime, timedelta, timezone
from ironflock import SeriesMetric
 
now = datetime.now(timezone.utc)
avg = SeriesMetric(ref="temperature", method="AVG")  # AVG, SUM, COUNT, MIN, MAX, FIRST, LAST
series = await ironflock.get_series_history("sensordata", {
    "metrics": [avg, {"ref": "humidity", "method": "MAX"}],
    "bucketMs": 3_600_000,  # one-hour buckets; omit to divide the range into `limit` buckets
    "limit": 24,            # the bucket budget, 1–10000
    "timeRange": [(now - timedelta(hours=24)).isoformat(), now.isoformat()],  # required, with a start
    "groupBy": ["device_key"],
})
for row in series:
    print(row["tsp"], row["device_key"], row[avg.column])  # avg.column is "AVG:temperature"

import { seriesColumn } from "ironflock";
 
const end = Date.now();
const avg = { ref: "temperature", method: "AVG" }; // AVG, SUM, COUNT, MIN, MAX, FIRST, LAST
const series = await ironflock.getSeriesHistory("sensordata", {
    metrics: [avg, { ref: "humidity", method: "MAX" }],
    bucketMs: 3_600_000,                     // one-hour buckets; omit to divide the range into `limit` buckets
    limit: 24,                               // the bucket budget, 1–10000
    timeRange: [end - 24 * 3_600_000, end],  // required, with a start
    groupBy: ["device_key"],
});
for (const row of series) {
    console.log(row.tsp, row.device_key, row[seriesColumn(avg)]); // seriesColumn(avg) is "AVG:temperature"
}

now := time.Now()
avg := ironflock.SeriesMetric{Ref: "temperature", Method: ironflock.MethodAvg} // MethodAvg, MethodSum, MethodCount, MethodMin, MethodMax, MethodFirst, MethodLast
series, err := ifl.GetSeriesHistory(ctx, "sensordata", ironflock.SeriesQueryParams{
	Metrics:   []ironflock.SeriesMetric{avg, {Ref: "humidity", Method: ironflock.MethodMax}},
	Bucket:    time.Hour,                                      // one-hour buckets; 0 divides the range into Limit buckets
	Limit:     24,                                             // the bucket budget, 1–10000
	TimeRange: ironflock.Between(now.Add(-24*time.Hour), now), // required, with a start
	GroupBy:   []string{"device_key"},
})
if err != nil {
	return err
}
for _, row := range series {
	log.Println(row["tsp"], row["device_key"], row[avg.Column()]) // avg.Column() is "AVG:temperature"
}

Sorgu parametreleri:

Satırlar. Her satır bir kovadır — groupBy ile, bir grubun kovası. tsp, kovanın epoch milisaniye cinsinden başlangıcıdır; her groupBy sütunu kendi adıyla, her metrik ise "<METHOD>:<ref>" altında döner (Python’da SeriesMetric.column, JavaScript’te seriesColumn(metric), Go’da SeriesMetric.Column()), ör. row["AVG:temperature"]. Satırlar tsp değerine göre artan sıradadır; satırı olmayan bir kova sonuçta yer almaz (boşluk doldurma yoktur). AVG ve SUM sayısal sütunları alır, MIN ve MAX dizeleri ve zaman damgalarını da; FIRST ve LAST kovanın en erken ve en geç satırının değerini verir; COUNT null olmayan değerleri sayar (tsp için: satırları). Büyük bir sonuç, getHistory’deki gibi parçalardan yeniden birleştirilir.

Kovalar ve açık bir uç. limit satırları değil kovaları sayar. bucketMs olmadan zaman aralığı limit kovaya bölünür. bucketMs verildiğinde, aralık limit değerinden fazla kova içeriyorsa veri arka ucu kovaları bucketMs değerinin bir katına genişletir — ve açık bir uç, veri arka ucunun kendi “şimdi”sine, yani sizinkinden biraz sonrasına kadar uzanır. Açık uçlu son 24 saat 25 adet bir saatlik kova içerir, bu yüzden limit: 24 iki saatlik kovalar alır. Örnekteki gibi bitişi sınırlayın veya bir kova fazlasına izin verin: bucketMs ve açık bir uçla limit + 1 kova dönebilir.

SDK’lar, veri arka ucunun reddedeceği şeyleri göndermeden önce denetler: en az bir metrik, boş olmayan ref’ler, bilinen metotlar, 63 baytı aşmayan sütun adları, bir başlangıç, başlangıçtan sonra gelen bir bitiş ve en az 1000 olan bir tamsayı olarak bucketMs (Go’da tam milisaniye cinsinden, en az 1 saniyelik bir Bucket). Veri arka ucu, yanıtlayamadığı şeyi URI_INVALID_TIME_RANGE, URI_INVALID_METRIC, URI_INVALID_GROUP_BY veya URI_SERIES_TOO_MANY_GROUPS (50.000’den fazla satır) ile reddeder — bkz. Veri Arka Ucu Retleri.

Kullanımdan kaldırılan biçim. 1.9.0’a kadarki SDK sürümleri metrics alanını sütun adları artı üst düzey bir method olarak gönderiyordu ({"metrics": ["temperature"], "method": "AVG", ...}); veri arka uçları bu biçimi fleetdb v1.0.58’den beri reddediyor. Bu biçim hâlâ çalışır: SDK sütun başına bir {ref, method} metriği gönderir, uyarır (Python’da bir DeprecationWarning, JavaScript’te süreç başına bir kez konsol uyarısı) ve sonuç sütunlarını yeniden sütun adlarıyla adlandırır; böylece eski kod row["temperature"] okumaya devam eder. Tek istisna, satırda o adda bir sütunun zaten bulunmasıdır; örneğin tsp’nin COUNT’u için tsp. {ref, method} metriklerine geçin ve row["AVG:temperature"] okuyun. Go SDK’sında yalnızca güncel biçim vardır: metrik başına bir metot (SeriesMetric).

Veriye Abone Olma

subscribeToTable / subscribe_to_table

Bir filo tablosundaki gerçek zamanlı güncellemelere abone olur. Veri arka ucu yeni bir satır sakladığında işleyici çağrılır; ilk argümanı, saklandığı haliyle satırdır — değerler veri şablonunun sütun türlerine göre tiplendirilmiş, gizli sütunlar maskelenmiş olarak. Toplu ekleme yolu (publishRowsToTable / appendRowsToTable) üzerinden yazılan satırlar işleyicinize birer birer teslim edilir, böylece verinin nasıl yazıldığından bağımsız olarak işleyici kodu aynı kalır.

def on_sensor_data(*args, **kwargs):
    row = args[0]
    print("New reading:", row["tsp"], row["temperature"])
 
await ironflock.subscribe_to_table("sensordata", on_sensor_data)

// The handler is called with (args, kwargs, details); the row is args[0]
function onSensorData(args) {
    const row = args[0];
    console.log("New reading:", row.tsp, row.temperature);
}
 
await ironflock.subscribeToTable("sensordata", onSensorData);

// The handler gets an *ironflock.Event; ev.Row() is the row (ev.Args[0])
ts, err := ifl.SubscribeToTable(ctx, "sensordata", func(ev *ironflock.Event) {
	row := ev.Row()
	log.Println("New reading:", row["tsp"], row["temperature"])
})
if err != nil {
	return err
}
defer ts.Unsubscribe(ctx) // removes the row and the bulk subscription

Bir transform’un kendine ait satırları yoktur: zamanlamasının her tetiklenişinde veri arka ucu görünümün tamamını — en fazla 3000 satır, görünümün sırasının tersiyle — ilk argümanı satır listesi olan tek bir olay olarak yayımlar. Python’da event_rows(args[0]), JavaScript’te eventRows(args) ve Go’da ev.Rows() her iki biçimi de okur: bir tablonun satırı [row] verir, bir transform’un listesi listenin kendisini (boş bir görünüm için []), başka her şey ise None / undefined / nil verir. Go’da bir transform olayı için ev.Row() nil’dir.

from ironflock import event_rows
 
def on_hourly(*args, **kwargs):
    for row in event_rows(args[0]) or []:
        print(row)
 
await ironflock.subscribe_to_table("hourly_averages", on_hourly)

import { eventRows } from "ironflock";
 
await ironflock.subscribeToTable("hourly_averages", (args) => {
    for (const row of eventRows(args) ?? []) console.log(row);
});

_, err := ifl.SubscribeToTable(ctx, "hourly_averages", func(ev *ironflock.Event) {
	for _, row := range ev.Rows() {
		log.Println(row)
	}
})
if err != nil {
	return err
}

subscribe

Özel gerçek zamanlı mesajlaşma için kendinize ait bir WAMP konusuna abone olur. Tablo satırları için subscribeToTable / subscribe_to_table kullanın: yönlendirici, ham tablo yazma konularına yapılan abonelikleri reddeder (bkz. Bir Uygulamanın Kullanabileceği URI’ler).

def on_alert(*args, **kwargs):
    print("Alert received:", args, kwargs)
 
await ironflock.subscribe("com.myapp.alerts", on_alert)

function onAlert(...args) {
    console.log("Alert received:", args);
}
 
await ironflock.subscribe("com.myapp.alerts", onAlert);

sub, err := ifl.Subscribe(ctx, "com.myapp.alerts", func(ev *ironflock.Event) {
	log.Println("Alert received:", ev.Args, ev.Kwargs)
})
if err != nil {
	return err
}
defer ifl.Unsubscribe(ctx, sub)

Gizli Sütunlar

Uygulamanın veri şablonunda secret: true olarak bildirilen bir sütun şifrelenmiş olarak saklanır. Hiçbir olağan okuma yolu düz metni döndürmez, onu yazan uygulamaya bile:

NULL, her yolda NULL olarak geçirilir; böylece “atanmış ama gizli” ile “hiç yazılmamış” birbirinden ayırt edilebilir kalır.

Bir varlık tablosunda oku-değiştir-yaz güvenlidir: hâlâ __secret__ yer tutucusunu taşıyan bir satırı yeniden yayımlamak — ya da gizli sütunu tamamen atlamak — saklanan sırrın üzerine yazmak yerine onu korur; açıkça gönderilen null ise sırrı temizler. Kesin kurallar için veri arka ucu kılavuzundaki Gizli Sütunlar bölümüne bakın.

from datetime import datetime, timezone
 
# Written like any other column — the data backend encrypts it on insert
await ironflock.publish_to_table("credentials", {
    "tsp": datetime.now(timezone.utc).isoformat(),
    "device_id": "d-1",
    "api_token": "hunter2",
})
 
# A normal read redacts it
rows = await ironflock.getHistory("credentials", {"limit": 1})
# [{"tsp": "...", "device_id": "d-1", "api_token": "__secret__"}]

// Written like any other column — the data backend encrypts it on insert
await ironflock.publishToTable("credentials", [
    { tsp: new Date().toISOString(), device_id: "d-1", api_token: "hunter2" },
]);
 
// A normal read redacts it
const rows = await ironflock.getHistory("credentials", { limit: 1 });
// [{ tsp: "...", device_id: "d-1", api_token: "__secret__" }]

// Written like any other column — the data backend encrypts it on insert
err := ifl.PublishToTable(ctx, "credentials", ironflock.Row{
	"tsp":       time.Now(),
	"device_id": "d-1",
	"api_token": "hunter2",
})
if err != nil {
	return err
}
 
// A normal read redacts it
rows, err := ifl.GetHistory(ctx, "credentials", &ironflock.TableQueryParams{Limit: 1})
// [map[api_token:__secret__ device_id:d-1 tsp:...]]

Aşağıdaki iki fonksiyon yalnızca uygulamanın kendi kapsayıcılarından çağrılabilir. Mesaj yönlendiricisi bunları her tarayıcı rolüne ve tüketen uygulamalara reddeder; bir ConsumedApp tanıtıcısının bunların karşılığını sunmamasının nedeni de budur: başka bir uygulamanın gizli sütunları size sansürlenmiş olarak ulaşır ve öyle kalır.

revealSecrets / reveal_secrets

Kendi tablolarınızdan birinin satırlarını, gizli sütunlarının şifresi çözülmüş halde okur.

rows = await ironflock.reveal_secrets("credentials", {
    "limit": 1,
    "filterAnd": [{"column": "device_id", "operator": "=", "value": "d-1"}],
})
# [{"tsp": "...", "device_id": "d-1", "api_token": "hunter2"}]

const rows = await ironflock.revealSecrets("credentials", {
    limit: 1,
    filterAnd: [{ column: "device_id", operator: "=", value: "d-1" }],
});
// [{ tsp: "...", device_id: "d-1", api_token: "hunter2" }]

rows, err := ifl.RevealSecrets(ctx, "credentials", &ironflock.TableQueryParams{
	Limit:     1,
	FilterAnd: []ironflock.Filter{ironflock.Where("device_id", "=", "d-1")},
})
if err != nil {
	return err
}
// [map[api_token:hunter2 device_id:d-1 tsp:...]]

Sorgu parametreleri getHistory ile aynıdır, tek bir farkla: limit, 100’ü aşamaz. Bu üst sınır, tek bir çağrının koca bir tablonun şifresini çözmesini engellemek için vardır ve veri arka ucu daha büyük bir değeri sessizce kırpmak yerine reddeder.

Veri arka ucu, bir cihazdaki uygulama kimlik bilgisi başına dakikada en fazla 30 açığa çıkarma isteğini yanıtlar; bunun ötesinde çağrı URI_RATE_LIMITED ile başarısız olur. Bir sırrı her kullanımda değil, bir kez açığa çıkarın ve saklayın. Gizli sütunu olmayan bir tablo URI_NOT_A_SECRET_COLUMN ile, bir gizli sütun üzerindeki filtre ise URI_SECRET_COLUMN ile reddedilir.

verifySecret / verify_secret

Bir aday değeri, gizli sütunu ifşa etmeden onunla karşılaştırır — açığa çıkarma fonksiyonunun parola denetimi karşılığıdır. Karşılaştırma veri arka ucunun içinde, sabit zamanda çalışır ve geriye yalnızca yanıt döner.

ok = await ironflock.verify_secret(
    "credentials", "api_token", submitted_token,
    {"limit": 1, "filterAnd": [{"column": "device_id", "operator": "=", "value": "d-1"}]},
)
if ok:
    ...

const { match, checked } = await ironflock.verifySecret(
    "credentials", "api_token", submittedToken,
    { limit: 1, filterAnd: [{ column: "device_id", operator: "=", value: "d-1" }] },
);
 
if (checked === 0) {
    // No row matched the selector at all — an unknown device, not a wrong token
}

res, err := ifl.VerifySecret(ctx, "credentials", "api_token", submittedToken, &ironflock.TableQueryParams{
	Limit:     1,
	FilterAnd: []ironflock.Filter{ironflock.Where("device_id", "=", "d-1")},
})
if err != nil {
	return err
}
if res.Checked == 0 {
	// No row matched the selector at all — an unknown device, not a wrong token
}
if res.Match {
	// ...
}

Parametreler:

Go’da parametreler context’ten sonra gelen konumsal dizelerdir; sorgu ise bir *ironflock.TableQueryParams değeridir (en son satır için nil).

JavaScript { match, checked } döndürür, Go ise Match ve Checked alanlarına sahip bir *ironflock.SecretVerifyResult; Python düz bir bool döndürür. checked elinizde olduğunda bunu kullanmaya değer: yanlış bir adayı (checked > 0), hiçbir satırla eşleşmeyen bir seçiciden (checked === 0) ayırır — bunlar kullanıcıya bildirilmesi gereken birbirinden çok farklı hatalardır.

Her satır kendi rastgele değeriyle şifrelendiği için, aynı sırrı tutan iki satır farklı şifreli metin saklar. Bir gizli sütun üzerinde = filtresinin çalışamamasının — veri arka ucu böyle bir sütun üzerindeki her filtreyi URI_SECRET_COLUMN ile reddeder — ve bunun yerine bu fonksiyonun var olmasının nedeni budur.

Veri arka ucu, bir cihazdaki uygulama kimlik bilgisi başına dakikada en fazla 120 denetimi yanıtlar; bunun ötesinde çağrı URI_RATE_LIMITED ile başarısız olur. Her istekte yapılan bir denetim için (ör. bir API anahtarı) olumlu bir sonucu kısa süreliğine önbelleğe alın. Gizli sütun olmayan bir sütun URI_NOT_A_SECRET_COLUMN ile reddedilir.

Uygulamalar Arası Veri Erişimi

Başka bir uygulamanın filo verilerini, aynı proje içinde kendi uygulamanızın içinden okuyun. Uygulamanız, sağlayıcı uygulamayı kendi data-template.yml dosyasının consumes: bölümünde belirtmeli (veya aşağıda açıklanan joker karakter iznine sahip olmalı) ve proje kullanıcısı erişim izni vermelidir. Erişim salt okunurdur: sağlayıcının paylaştığı tabloların ve transform’ların geçmişini sorgulayabilir ve satırlarına gerçek zamanlı olarak abone olabilirsiniz, ancak bunlara yazamazsınız. Tüketilen uygulamalara yapılan bağlantılar uygulama başına önbelleğe alınır ve örneğiniz durduğunda otomatik olarak kapatılır.

Bağlantı, cihaz ajanının enjekte ettiği uygulama başına kimlik bilgisini (APP_AUTH_ID, APP_AUTH_SECRET) gerektirir. Platform, eski cihaz kimlik bilgisini — uygulama başına kimlik bilgisi almamış bir uygulamanın, ör. eski bir cihaz ajanı altında, geri dönüş olarak kullandığı seri numarasını — başka bir uygulamanın realm’inde reddeder (NOT_AUTHORIZED, bunu belirten bir mesajla). Sağlayıcı uygulama aynı cihazda çalışıyorsa durum farklıdır: bu kimlik bilgisi o uygulamanın realm’ine salt okunur olarak değil, o uygulamanın kendi tam yetkileriyle katılır.

Uygulamanız joker karakter (wildcard) iznine (consumes: [{ app: "*" }]) sahipse, sağlayıcıları listConsumableApps / list_consumable_apps ve connectToAllApps / connect_to_all_apps (aşağıda) ile dinamik olarak keşfedebilir ve açabilirsiniz.

connectToApp / connect_to_app

Başka bir uygulamanın veri arka ucuna salt okunur bir bağlantı açar ve bir tanıtıcı (handle) döndürür. Tanıtıcı getHistory / get_history, subscribeToTable / subscribe_to_table ve getSeriesHistory / get_series_history (yalnızca tablolar) işlevlerini sunar — kendi tablolarınızda kullandığınız sorgulama ve abone olma işlemlerinin aynısı, aynı parametreler ve sonuçlarla — ayrıca close ile paylaşılan tables / transforms kataloglarını da sağlar.

# Open a read-only handle on another app's data backend
weather = await ironflock.connect_to_app("weather-app")
 
# Inspect what the provider shares
print([t["tablename"] for t in weather.tables])
 
# Query history and subscribe, just like your own tables
rows = await weather.get_history("forecasts", {"limit": 100})
 
def on_forecast(*args, **kwargs):
    print("New forecast:", args)
 
await weather.subscribe_to_table("forecasts", on_forecast)

// Open a read-only handle on another app's data backend
const weather = await ironflock.connectToApp("weather-app");
 
// Inspect what the provider shares
console.log(weather.tables.map((t) => t.tablename));
 
// Query history and subscribe, just like your own tables
const rows = await weather.getHistory("forecasts", { limit: 100 });
 
await weather.subscribeToTable("forecasts", (...args) => {
    console.log("New forecast:", args);
});

// Open a read-only handle on another app's data backend
weather, err := ifl.ConnectToApp(ctx, "weather-app")
var cerr *ironflock.CrossAppAccessError
if errors.As(err, &cerr) {
	return fmt.Errorf("no access to weather-app (%s): %w", cerr.Code, err) // e.g. NO_GRANT
} else if err != nil {
	return err
}
 
// Inspect what the provider shares
for _, t := range weather.Tables {
	log.Println(t.Tablename)
}
 
// Query history and subscribe, just like your own tables
rows, err := weather.GetHistory(ctx, "forecasts", &ironflock.TableQueryParams{Limit: 100})
if err != nil {
	return err
}
 
_, err = weather.SubscribeToTable(ctx, "forecasts", func(ev *ironflock.Event) {
	log.Println("New forecast:", ev.Row())
})

Parametreler:

Erişim reddedilir veya yanlış kullanılırsa, code alanına (Go’da ironflock.CodeNoGrant gibi sabitlerle birlikte Code) sahip bir CrossAppAccessError yükseltilir (Python) / fırlatılır (JavaScript) / döndürülür (Go; errors.As ile sınanacak bir *ironflock.CrossAppAccessError): NO_GRANT, PROVIDER_NOT_INSTALLED, UNKNOWN_APP, PRIVATE_TABLE, SECRET_COLUMN (sağlayıcının gizli olarak işaretlediği bir sütuna — bir grup içinde de — filtre uygulayan veya o sütunu seçen bir sorgu) ya da NOT_AUTHORIZED (izin iptal edildi veya o anda doğrulanamadı — ya da uygulamanız eski cihaz kimlik bilgisini sundu; bu durumda mesaj bunu belirtir).

connectToApp / connect_to_app beklerken gelen bir ret, çağrıyı hemen başarısız kılar. Bir tanıtıcı açıldıktan sonra ret ancak kalıcı olduğunda kesin sayılır — bağlantının en son ayakta olduğu andan bu yana 3 veya daha fazla ret (yönlendiricinin oturumu bir kimlik doğrulama nedeniyle kapatması da, reddedilen her yeniden bağlanma da bir ret sayılır), ilki en az 60 saniye önce —, çünkü platform erişimi kısa bir süre doğrulayamadığında da aynı şekilde reddeder. O zamana kadar tanıtıcı yeniden bağlanmayı sürdürür ve bir yeniden bağlanma başarılı olursa toparlanır. Ret kesinleştiğinde on_error / onError / OnError çağrılır ve tanıtıcı önbellekten çıkarılır: bir sonraki connectToApp / connect_to_app / ConnectToApp yeni bir bağlantı açar. O andan itibaren tanıtıcının okumaları ve abonelikleri, on_error / onError hangi hatayla çağrıldıysa o hatayla hemen başarısız olur — Go’da wamp.ErrStopped’u saran bir hatayla.

Python’da stage ve on_error anahtar kelime argümanlarıdır; JavaScript’te bir seçenekler nesnesi aracılığıyla geçilir (connectToApp(appName, { stage, onError })); Go’da ise bir struct aracılığıyla (ConnectToApp(ctx, appName, ironflock.ConnectToAppOptions{Stage, OnError})); burada OnError bir func(*ironflock.CrossAppAccessError)’dır. Go’da ctx yalnızca çağıranın beklemesini sınırlar: aynı uygulama için eşzamanlı çağrılar tek bir denemeyi paylaşır ve Close(ctx) bir tanıtıcıyı kapatır.

listConsumableApps / list_consumable_apps

Projedeki her özel olmayan sağlayıcıyı listeler — bu, joker karakter tüketim iznine (data-template.yml dosyanızdaki consumes: [{ app: "*" }], proje kullanıcısı tarafından verilir) sahip uygulamalar için temel keşif işlevidir. Tek bir çağrı yapar ve hiçbir bağlantı açmaz: döndürülen katalogları bir seçicide gösterin, ardından istediğiniz sağlayıcılar için connectToApp / connect_to_app çağırın — veya hepsini tek seferde açmak için connectToAllApps / connect_to_all_apps çağırın.

Not: İzni uygulamanızın data-template.yml dosyasında belirtin ve * işaretini tırnak içine alın — tırnaksız bir *, bir YAML takma adıdır ve ayrıştırılamaz:

consumes:
  - app: "*"

providers = await ironflock.list_consumable_apps()
 
for p in providers:
    print(p["app"], list(p["stages"].keys()))  # e.g. "weather-app" ["dev", "prod"]

const providers = await ironflock.listConsumableApps();
 
for (const p of providers) {
    console.log(p.app, Object.keys(p.stages)); // e.g. "weather-app" ["dev", "prod"]
}

providers, err := ifl.ListConsumableApps(ctx)
if err != nil {
	return err
}
 
for _, p := range providers {
	log.Println(p.App, p.Stages.Dev != nil, p.Stages.Prod != nil) // e.g. weather-app true true
	if c := p.Catalog("prod"); c != nil {
		log.Println(len(c.Tables), "shared tables")
	}
}

Her giriş bir sağlayıcıyı tanımlar:

Go’da her girdi; App, ProviderAppKey ve Stages.Dev / Stages.Prod (Tables ve Transforms içeren bir *StageCatalog, eksik bir aşama için nil) alanlarına sahip bir ironflock.ConsumedAppInfo’dur; Catalog(stage) adıyla birini döndürür.

Uygulamanızın hiçbir joker karakter izni yoksa, code: NO_GRANT içeren bir CrossAppAccessError yükseltilir (Python) / fırlatılır (JavaScript) / döndürülür (Go).

connectToAllApps / connect_to_all_apps

Projedeki her özel olmayan sağlayıcıya tek bir çağrıda salt okunur tanıtıcılar (handle) açar (yalnızca joker karakter tüketicileri). Sağlayıcıları listConsumableApps / list_consumable_apps aracılığıyla numaralandırır ve her birini açar; istenen aşama için veri arka ucu bulunmayanları atlar. Her tanıtıcı, connectToApp / connect_to_app ile aynı anahtar altında önbelleğe alınır, böylece daha sonraki bir connectToApp(name) çağrısı zaten hazırlanmış tanıtıcıyı döndürür. Döndürülen tanıtıcılar, örneğiniz durduğunda birlikte kapatılır.

apps = await ironflock.connect_to_all_apps(
    on_error=lambda err: print("Provider skipped:", err)
)
 
for app in apps:
    rows = await app.get_history(app.tables[0]["tablename"], {"limit": 10})
    print(app.app, rows)

const apps = await ironflock.connectToAllApps({
    onError: (err) => console.warn("Provider skipped:", err),
});
 
for (const app of apps) {
    const rows = await app.getHistory(app.tables[0]?.tablename, { limit: 10 });
    console.log(app.app, rows);
}

apps, err := ifl.ConnectToAllApps(ctx, ironflock.ConnectToAllAppsOptions{
	OnError: func(err error) { log.Println("Provider skipped:", err) },
})
if err != nil {
	return err
}
 
for _, app := range apps {
	if len(app.Tables) == 0 {
		continue
	}
	rows, err := app.GetHistory(ctx, app.Tables[0].Tablename, &ironflock.TableQueryParams{Limit: 10})
	if err != nil {
		return err
	}
	log.Println(app.App, rows)
}

Parametreler:

Başarıyla açılan sağlayıcı tanıtıcılarını döndürür (connectToApp / connect_to_app ile aynı tanıtıcı türü). Uygulamanızın hiçbir joker karakter izni yoksa, code: NO_GRANT içeren bir CrossAppAccessError yükseltilir (Python) / fırlatılır (JavaScript) / döndürülür (Go).

Python’da stage, on_error ve continue_on_error anahtar kelime argümanlarıdır; JavaScript’te bir seçenekler nesnesi aracılığıyla geçilir (connectToAllApps({ stage, onError, continueOnError })); Go’da ise bir struct aracılığıyla (ConnectToAllApps(ctx, ironflock.ConnectToAllAppsOptions{Stage, OnError, StopOnError})); burada OnError bir func(error)’dır ve StopOnError: true, continueOnError: false’a karşılık gelir.

Yönetilen Dosya Depolama

Her uygulama veri arka ucu, tablolarının yanı sıra files özelliği (Go’da ifl.Files(); Start’tan önce de alınabilen bir *filestore.FileStore) üzerinden erişilen özel bir nesne depolama alanı edinir. Bunu görüntüler, PDF’ler, kamera kareleri, firmware blob’ları — kısacası bir tablo satırına ait olmayan her şey — için kullanın. Kurulum gerekmez: veri şablonunda files: bölümü bulunmayan bir uygulama bile default adında bir ad alanı edinir (kendi ad alanlarını tanımlayan bir şablon onun yerini alır — bkz. Ad Alanları).

Bu bölüm istemci tarafı referansıdır. Platform tarafı için — ad alanlarını, kotaları ve saklamayı tanımlama, uygulamalar arasında dosya paylaşma, uygulama başına S3 kimlik bilgileri ve yerinde (on-premises) davranış — bkz. Dosya Depolama.

Temel fikir şudur: bir nesneyi sakladığınızda size aynı çağrıda doğrudan bir tablo sütununa yazabileceğiniz kalıcı bir URL döner; böylece bir pano widget’ı onu başka hiçbir iş yapmadan görüntüleyebilir:

from datetime import datetime, timezone
 
# Store an object and get a permanent URL back in the same call
info = await ironflock.files.put("part-1.jpg", jpeg_bytes, content_type="image/jpeg")
 
# The URL is safe to store in a table column — a dashboard widget can then
# render <img src="{{photo_url}}"> without any extra round trip
await ironflock.publish_to_table("inspections", {
    "tsp": datetime.now(timezone.utc).isoformat(),
    "part_id": "1",
    "photo_url": info.url,
})
 
# Read it back
data = await ironflock.files.get("part-1.jpg")
 
# Every object in the folder 2026/, in its subfolders too (pages are fetched for you)
async for obj in ironflock.files.iter(prefix="2026/"):
    print(obj.key, obj.size)

// Store an object and get a permanent URL back in the same call
const info = await ironflock.files.put("part-1.jpg", jpegBytes, {
    contentType: "image/jpeg",
});
 
// The URL is safe to store in a table column — a dashboard widget can then
// render <img src="{{photo_url}}"> without any extra round trip
await ironflock.publishToTable("inspections", [
    { tsp: new Date().toISOString(), part_id: "1", photo_url: info.url },
]);
 
// Read it back
const data = await ironflock.files.get("part-1.jpg");
 
// Every object in the folder 2026/, in its subfolders too (pages are fetched for you)
for await (const obj of ironflock.files.iterate({ prefix: "2026/" })) {
    console.log(obj.key, obj.size);
}

files := ifl.Files()
 
// Store an object and get a permanent URL back in the same call
info, err := files.Put(ctx, "part-1.jpg", jpegBytes, filestore.ContentType("image/jpeg"))
if err != nil {
	return err
}
 
// The URL is safe to store in a table column — a dashboard widget can then
// render <img src="{{photo_url}}"> without any extra round trip
err = ifl.PublishToTable(ctx, "inspections", ironflock.Row{
	"tsp":       time.Now(),
	"part_id":   "1",
	"photo_url": info.URL,
})
 
// Read it back
data, err := files.Get(ctx, "part-1.jpg")
 
// Every object in the folder 2026/, in its subfolders too (pages are fetched for you)
for obj, err := range files.Iter(ctx, filestore.Prefix("2026/")) {
	if err != nil {
		return err
	}
	log.Println(obj.Key, obj.Size)
}

Bu URL hiçbir zaman sona ermez, ancak herkese açık bir bağlantı değildir: yalnızca bu veri arka ucu üzerinde READ erişimine sahip, kimliği doğrulanmış bir istek sahibi tarafından okunabilir kalır ve bir kimlik doğrulama proxy’si bunu her istekte yeniden denetler. Bu nedenle veritabanında saklanması güvenlidir.

Ad Alanları

Bir ad alanı (namespace), politika taşıyan bir anahtar önekidir — saklama süresi, paylaşım kuralları, izin verilen içerik türleri. Ayrı bir bucket değildir; bir uygulamanın her ad alanı, o uygulamanın tek depolama alanının içinde yer alır. Yalnızca bir nesne kümesinin farklı kurallara ihtiyacı olduğunda yeni bir tane tanımlayın; aksi halde default içinde kalın ve nesnelerinizi 2026/03/part-1.jpg gibi anahtar yollarıyla düzenleyin.

Ad alanlarını data-template.yml dosyasında tanımlayın. Herhangi birini tanımlamak örtük default’un yerini alır: default adında bir tane de listeleyin, aksi halde ad alanı belirtilmeyen her çağrı NO_SUCH_NAMESPACE ile başarısız olur.

files:
  # Storage budget the app suggests for itself. The project user can change it,
  # and their setting is the one that gets enforced.
  quotaBytes: 5368709120
  namespaces:
    # Keep default: declaring namespaces replaces the implicit one.
    - name: default
    - name: frames
      description: Raw camera frames, one JPEG per inspected part.
      contentTypes: ["image/jpeg"]
      maxObjectBytes: 20971520
      retention: { deleteAfter: 30 days }

Bütçenin ad alanı başına değil, uygulamanın tamamı için bir kez tanımlandığına dikkat edin. Bir ad alanı yalnızca uygulamanın tek depolama alanı içindeki bir anahtar önekidir, dolayısıyla önek başına bir bütçenin uygulanabileceği bir şey yoktur. maxObjectBytes ise ad alanı başınadır — bir toplamı değil, tek bir nesneyi sınırlar: ayarlanmadıysa 100 MiB, en fazla 5 GiB (üstünde OBJECT_TOO_LARGE).

Aşağıdaki her metot ad alanını isteğe bağlı bir argüman olarak alır ve varsayılan olarak default kullanır; boş bir ad alanı ("") da default anlamına gelir.

Nesneleri Saklama ve Okuma

# Bytes in, bytes out
info = await ironflock.files.put("reports/march.pdf", pdf_bytes, content_type="application/pdf")
data = await ironflock.files.get("reports/march.pdf")
 
# Or straight from/to a local file — these stream on the large-object path,
# so a multi-gigabyte file never has to fit in memory
await ironflock.files.put_file("firmware/v2.bin", "/data/build/v2.bin")
await ironflock.files.get_to_file("firmware/v2.bin", "/tmp/v2.bin")

// Bytes in, bytes out — put/get work on Uint8Array in both Node and the browser
const info = await ironflock.files.put("reports/march.pdf", pdfBytes, {
    contentType: "application/pdf",
});
const data = await ironflock.files.get("reports/march.pdf");

files := ifl.Files()
 
// Bytes in, bytes out
info, err := files.Put(ctx, "reports/march.pdf", pdfBytes, filestore.ContentType("application/pdf"))
if err != nil {
	return err
}
data, err := files.Get(ctx, "reports/march.pdf")
 
// Or straight from/to a local file — these stream on the large-object path,
// so a multi-gigabyte file never has to fit in memory
_, err = files.PutFile(ctx, "firmware/v2.bin", "/data/build/v2.bin")
_, err = files.GetToFile(ctx, "firmware/v2.bin", "/tmp/v2.bin")
 
// Or from a reader / to a writer
_, err = files.PutReader(ctx, "logs/today.txt", logReader, logSize)
_, err = files.GetTo(ctx, "logs/today.txt", os.Stdout)

JavaScript’te dosya yolu yardımcıları yoktur, çünkü paket hem Node hem de tarayıcı için tek bir derleme yayımlar — yerel dosyaları fs ile kendiniz okuyup yazın.

Python’da put_file ve get_to_file metotlarının dosya işleri olay döngüsünün dışında çalışır. get_to_file, eksik üst dizinleri oluşturur ve nesnenin ilk baytları elde edilir edilmez dosyayı yerinde yazar: reddedilen bir okuma (böyle bir nesne yok, yetki yok) yola hiç dokunmaz; yarıda başarısız olan bir okuma ise o ana kadar yazılanı bırakır. Bir FIFO, nesne akış halinde geldikçe yazılır ve onu açmak bir okuyucu bekler; bu yüzden kimsenin okumadığı bir FIFO çağrıyı (olay döngüsünü değil) engeller; asyncio.wait_for ondan vazgeçebilir. put_file, bir FIFO’yu saklamadan önce sonuna kadar okur.

Go’da GetToFile da eksik üst dizinleri oluşturur, ancak hedefin yanındaki geçici bir dosyaya indirir ve indirme tamamlanınca onu yeniden adlandırarak yerine koyar: başarısız olan veya iptal edilen bir indirme hiçbir zaman yarım bir dosya bırakmaz ve önceki dosyayı korur. Sembolik bağlantılar izlenir (gösterdikleri dosya yazılır, bağlantılar yerinde kalır); yeni dosya, sürecin izin verdiği ölçüde eski dosyanın sahibini, grubunu ve izin bitlerini alır. Bir FIFO veya bir aygıt, nesne akarken yerinde yazılır. Yanına yeni bir dosya konamayan bir hedef için — örneğin salt okunur veya sözde (pseudo) bir dosya sistemindeki bir hedef — kendiniz açtığınız bir dosyayla GetTo kullanın.

put şunları kabul eder: content_type / contentType (MIME türü; ad alanı hangilerine izin verildiğini kısıtlayabilir) ve namespace. Python’da bunlar anahtar kelime argümanlarıdır; JavaScript’te bir seçenekler nesnesinin içine girer; Go’da seçeneklerdir (filestore.ContentType(…), filestore.Namespace(…)).

Listeleme ve İnceleme

Klasörler. / ile biten bir önek bir klasörü adlandırır: iter(prefix="2026/") / iterate({ prefix: "2026/" }) / Iter(ctx, filestore.Prefix("2026/")), 2026/a.txt ve 2026/sub/c.txt öğelerini verir, ancak 2026-notes.txt öğesini vermez. list bir klasörü adıyla açamaz, çünkü dosya servisi / ile biten bir listeleme önekini reddeder (FleetFiles v0.2 INTERNAL yanıtını verir): 2026 önekiyle çağrılan list, nesneler arasında 2026-notes.txt öğesini, önekler arasında ise 2026/ klasörünü döndürür. Servis anahtarları Unicode normalleştirme biçimi C’de saklar; bu yüzden klasör önekini de NFC olarak verin. Önekin başka bir biçimi altındaki bir anahtarla karşılaşan bir yineleme, her anahtarı atlamak yerine başarısız olur.

Nesneler üç SDK’da da aynı alanlarla, her dilin adlandırma stiline uygun olarak tanımlanır: namespace, key, size, etag, content_type / contentType, last_modified / lastModified, checksum_sha256 / checksumSha256 ve url — Go’da filestore.ObjectInfo türünün Namespace, Key, Size, ETag, ContentType, LastModified, ChecksumSHA256 ve URL alanları.

Depolama Kullanımı ve Kota

usage, tek bir çağrıyla doğrudan nesne deposundan yanıt alır; bu nedenle toplamlar SDK tarafından toplanmış değil, kesindir:

u = await ironflock.files.usage()
print(u.size_bytes, u.object_count, u.quota_bytes, u.free_bytes)
 
# Break the total down per namespace (costs one listing per namespace)
detailed = await ironflock.files.usage(detail=True)
print(detailed.per_namespace)   # {"default": 1048576, "frames": 73400320}

const u = await ironflock.files.usage();
console.log(u.sizeBytes, u.objectCount, u.quotaBytes, u.freeBytes);
 
// Break the total down per namespace (costs one listing per namespace)
const detailed = await ironflock.files.usage({ detail: true });
console.log(detailed.perNamespace);   // { default: 1048576, frames: 73400320 }

u, err := ifl.Files().Usage(ctx)
if err != nil {
	return err
}
log.Println(u.SizeBytes, u.ObjectCount, u.QuotaBytes, u.FreeBytes)
 
// Break the total down per namespace (costs one listing per namespace)
detailed, err := ifl.Files().Usage(ctx, filestore.Detail())
if err != nil {
	return err
}
log.Println(detailed.PerNamespace) // map[default:1048576 frames:73400320]

Go’da alanlar filestore.StorageUsage türünün SizeBytes, ObjectCount, QuotaBytes, FreeBytes ve PerNamespace alanlarıdır.

Ad alanı başına döküm varsayılan olarak kapalıdır, çünkü depo bunu doğrudan yanıtlayamaz: hesabı depolama alanı başına tutar ve bir ad alanı yalnızca bir önektir, dolayısıyla SDK’nın boyutları toplamak için her ad alanını listelemesi gerekir. Bunu istediğinizde isteyin, sıcak bir kod yolunda değil.

Birbirinden ayrı tutulması gereken iki farklı kota vardır. catalog() her ikisini de bildirir:

Go’da Catalog(ctx), QuotaBytes ve SuggestedQuotaBytes alanlarına sahip bir *filestore.Catalog döndürür.

Bir kullanıcı uygulamanın bütçesini yükselttiğinde ya da düşürdüğünde bu iki değer birbirinden ayrılır; uygulanan değerin şablondan değil depodan okunmasının nedeni de budur — uygulamanın yeniden dağıtılması, kullanıcının seçimini sessizce sıfırlamamalıdır. Bir arayüz her ikisini de gösterebilir (“uygulama X öneriyor, siz Y ayarladınız”). Uygulama her zaman ilkini kullanır. Kullanıcı bütçeyi istediği zaman değiştirebilir ve catalog() onu son getirildiği andaki haliyle bildirir: güncel değeri usage() ile okuyun.

Nesneleri Paylaşma

İki tür bağlantı vardır ve aradaki fark önemlidir:

share_url / shareUrl bir taşıyıcı (bearer) yetkidir: geçici erişime ihtiyacı olan bir kişiye verin ve veritabanında saklamayın. Bir panonun görüntülediği her şey için url kullanın.

url, dağıtımın bir HTTP kenarı bulunmadığı durumlarda (örneğin düz HTTP çalışan bir appliance) None / undefined / "" (Go) döndürür — bu, get’e geri dönmeniz gerektiğinin işaretidir. Nesnenin etag değerini version argümanı olarak (Go’da filestore.Version(etag)) geçmek, tarayıcıların yanıtı değişmez (immutable) biçimde önbelleğe almasını sağlar.

Python ve Go’da cloud_url(key, …) / CloudURL(ctx, key, …), kalıcı URL’yi bir appliance’ın bulut dosya tüneli üzerinden döndürür (https://i<instanceKey>-files.<cloud-edge>): appliance çevrimiçi olduğu sürece internetten erişilebilir ve url ile aynı yetkilendirmeye tabidir. Bulutta barındırılan dağıtımlarda (url değerinin zaten internetten erişilebildiği yerlerde), HTTP kenarının bulunmadığı yerlerde ve veri arka ucunun bulut paylaşımı kapalıyken None (Go’da "") döndürür. Kullanıcı bunu istediği zaman açıp kapatabilir; bu nedenle cloud_url / CloudURL, önbellekteki katalog 30 saniyeden eskiyse kataloğu yeniden okur.

upload_url / uploadUrl / UploadURL, doğrudan yükleme kabul eden süreli bir URL üretir ve url, method, headers ile expires_in / expiresIn döndürür (Go’da URL, Method, Headers ve ExpiresIn alanlarına sahip bir *filestore.UploadTarget). Nesnenin URL üretilirken belirlenen içerik türüyle saklanması için başlıkları verildiği gibi gönderin. Ad alanının içerik türleri ve boyut sınırı, bildirilen bir size ve kota, URL kullanıldığında değil üretildiğinde denetlenir: URL yalnızca ana makine (host) için imzalanır; bu nedenle onu elinde tutan herkes, süresi dolana kadar anahtarına herhangi bir içerik yazabilir. share_url / shareUrl gibi bu da bir taşıyıcı (bearer) yetkidir — yazan türden.

Büyük Nesneler

SDK aktarım yolunu boyuta göre otomatik olarak seçer — yapılandırılacak bir şey yoktur:

Kesin limit, sunucu tarafından çalışma zamanında catalog() içinde inline_max_bytes / inlineMaxBytes / InlineMaxBytes olarak bildirilir; böylece yeni bir SDK sürümü çıkmadan yükseltilebilir.

Doğrudan yol, URL’leri önceden imzalayabilen (presign) bir dağıtım ve yalnızca yönlendiriciye değil nesne depolama sunucusuna da erişebilen bir cihaz gerektirir. Bunlardan biri eksik olduğunda — katalog dağıtımın önceden imzalayamadığını söylediğinde (varsayılan olarak bir yerinde (on-premises) appliance), okuma URL’sinin üretilmesi NOT_SUPPORTED yanıtını verdiğinde veya herhangi bir bayt gelmeden önce nesne depolamaya erişilemediğinde — get (ve Python’da get_to_file, Go’da GetTo ile GetToFile) bunun yerine nesneyi yönlendirici üzerinden bayt aralıkları halinde okur (FleetFiles v0.1.33 ve sonrası); her aralık en fazla satır içi limit kadardır. Her aralık ayrı bir okumadır: böyle bir okuma sırasında değiştirilen bir nesne okumayı INTERNAL ile başarısız kılar (“object changed while it was read”). Yazmaların böyle bir geri dönüş yolu yoktur.

Yazmalar için geriye iki tavan kalır ve her ikisi de hangisine takıldığınızı belirten bir nedenle TOO_LARGE bildirir:

• 5 GiB — nesne deposunun tek seferlik yükleme limiti. Çok parçalı (multipart) yükleme henüz uygulanmadı.
• Doğrudan uç noktanın bulunmadığı yerlerde satır içi limit — önceden imzalayamayan bir dağıtım (varsayılan olarak bir appliance) daha büyük bir nesneyi hiç saklayamaz. Hiçbir yeniden deneme ya da daha küçük parça işe yaramaz ve mesaj bunu açıkça söyler.

Doğrudan yolun sahada sık görülen iki arızası, yetkilendirme sorunu gibi görünmek yerine kendi kodlarını alır: PRESIGN_UNREACHABLE (yalnızca yönlendiriciye izin veren bir proxy — bir okuma aralıklara geri döner, bir yazma başarısız olur) ve CLOCK_SKEW (nesne deposu, 15 dakikadan fazla sapmış istekleri reddeder — cihazdaki NTP’yi kontrol edin).

Dosya Depolama Hataları

Dosya servisinin veya doğrudan bir aktarımın başarısızlığı, kararlı bir code ve insan tarafından okunabilir bir reason taşıyan bir FileStoreError yükseltir (Python) / fırlatır (JavaScript) / döndürür (Go). reason üzerinde değil, her zaman code üzerinde dallanın. Yerel dosya hataları, iptal edilen bir çağrı ve aşağıda eşlenenler dışındaki yönlendirici düzeyindeki WAMP hataları olduğu gibi yükseltilir.

from ironflock.filestore import FileStoreError
 
try:
    await ironflock.files.put("huge.bin", payload)
except FileStoreError as e:
    if e.code == "QUOTA_EXCEEDED":
        print("Filestore is full:", e.reason)
    else:
        raise

import { FileStoreError } from "ironflock";
 
try {
    await ironflock.files.put("huge.bin", payload);
} catch (e) {
    if (e instanceof FileStoreError && e.code === "QUOTA_EXCEEDED") {
        console.error("Filestore is full:", e.reason);
    } else {
        throw e;
    }
}

_, err := ifl.Files().Put(ctx, "huge.bin", payload)
var ferr *filestore.Error
if errors.As(err, &ferr) && ferr.Code == filestore.CodeQuotaExceeded {
	log.Println("Filestore is full:", ferr.Reason)
} else if err != nil {
	return err
}

Daha yeni bir sunucu, bu SDK sürümünün bilmediği kodlar sunabilir. Bunlar tek bir kategoriye indirgenmeden code olarak geçirilir; bu nedenle tanınmayan bir değeri genel bir hata olarak ele alın.

Dosya çağrıları bağlantıyı bekler (Python ve Go’da en fazla 10, JavaScript’te 6 saniye) ve yeniden denenmez: tablo işlemlerinden farklı olarak bir platform yeniden başlatmasını atlatamazlar; bu yüzden böyle bir yeniden başlatma sırasında bir çağrı, dosya servisi yeniden kaydolana kadar NOT_AVAILABLE ile başarısız olabilir. Böyle bir çağrı hiçbir yerde çalışmamıştır, bu nedenle uygulamanız onu tekrarlayabilir.

Anahtarlar. Anahtarlar konusunda yetkili olan dosya servisidir; SDK’lar anahtarları ve önekleri verildiği gibi gönderir. Hatalı biçimlendirilmiş bir anahtar veya önek — boş; başında veya sonunda / bulunan (iter / iterate için bir klasör öneki hariç); boş, . veya .. segmenti ya da . ile biten veya boşlukla başlayan ya da biten bir segmenti olan; \ : * ? " < > | ^ ~ karakterlerinden birini, bir kontrol karakterini veya bir Unicode biçim karakterini içeren; 900 baytı, 20 segmenti veya segment başına 255 baytı aşan; ya da ayrılmış _sys/ öneki altındaki — anahtar hatalarını sınıflandıran bir dosya servisi tarafından INVALID_KEY ile, FleetFiles v0.2 tarafından ise INTERNAL ile reddedilir. Zaman damgalarına dikkat edin: 2026-10-09T12:00:00Z, : nedeniyle geçerli bir anahtar segmenti değildir.

Python’da FileStoreError, ironflock.filestore içinden içe aktarılır; JavaScript’te ise paket kökünden dışa aktarılır (import { FileStoreError } from "ironflock"); Go’da *filestore.Error’dır (ayrıca ironflock.FileStoreError) ve kodlar filestore.CodeQuotaExceeded gibi sabitlerdir.

Cihazlar Arası İletişim

registerDeviceFunction / register_device_function

Aynı uygulamayı (aynı aşamada) çalıştıran diğer cihazların ve pano widget eylemlerinin çağırabileceği bir prosedür kaydeder. SDK tam URI’yi, <SWARM_KEY>.<DEVICE_KEY>.<APP_KEY>.<STAGE>.<topic>, sizin için oluşturur; burada STAGE, DEV veya PROD olur. Yönlendirici bir uygulamadan başka hiçbir kaydı kabul etmez ve yalnızca tekli (single) kayıtları kabul eder (bkz. Bir Uygulamanın Kullanabileceği URI’ler). Kayıt her yeniden bağlanmadan sonra geri yüklenir.

def add(a, b):
    return a + b
 
await ironflock.register_device_function("com.myapp.add", add)

function add(args) {
    return args[0] + args[1];
}
 
await ironflock.registerDeviceFunction("com.myapp.add", add);

_, err := ifl.RegisterDeviceFunction(ctx, "com.myapp.add", func(ctx context.Context, inv *ironflock.Invocation) (any, error) {
	if len(inv.Args) != 2 {
		return nil, errors.New("add takes two numbers")
	}
	a, ok1 := inv.Args[0].(int64)
	b, ok2 := inv.Args[1].(int64)
	if !ok1 || !ok2 {
		return nil, fmt.Errorf("add takes two integers, got %T and %T", inv.Args[0], inv.Args[1])
	}
	return a + b, nil
})
if err != nil {
	return err
}

callDeviceFunction / call_device_function

Aynı uygulamanın başka bir cihazı tarafından kaydedilmiş bir prosedürü çağırır. SDK, hedef cihazın anahtarını kullanarak tam WAMP konusunu otomatik olarak oluşturur: <SWARM_KEY>.<device_key>.<APP_KEY>.<STAGE>.<topic>; bu, registerDeviceFunction / register_device_function metodunun hedef cihazda kaydettiği URI’nin aynısıdır.

result = await ironflock.call_device_function(
    42,                        # target device key
    "com.myapp.add",           # procedure name
    args=[3, 5]                # arguments
)
print(result)  # 8

const result = await ironflock.callDeviceFunction(
    42,                        // target device key
    "com.myapp.add",           // procedure name
    [3, 5]                     // arguments
);
console.log(result);  // 8

res, err := ifl.CallDeviceFunction(ctx,
	42,              // target device key
	"com.myapp.add", // procedure name
	3, 5,            // arguments
)
if err != nil {
	return err
}
log.Println(res.Value()) // 8

call

Tam bir WAMP URI kullanarak uzak prosedür çağırır. Bir uygulama some.full.wamp.topic gibi bir adı kaydedemez; bu yüzden böyle bir ad yalnızca platform servislerinin uygulamanın veri realm’inde kaydettiği prosedürlere, örneğin veri arka ucunun ve dosya depolamanın prosedürlerine ulaşır. Uygulamanızın başka bir cihazının kaydettiği bir fonksiyonu çağırmak için callDeviceFunction / call_device_function kullanın.

result = await ironflock.call("some.full.wamp.topic", args=[42])

const result = await ironflock.call("some.full.wamp.topic", [42]);

result, err := ifl.Call(ctx, "some.full.wamp.topic", 42)
if err != nil {
	return err
}
log.Println(result.Value())

Bir Uygulamanın Kullanabileceği URI’ler

Uygulama container’ınız kendi veri realm’ine, realm-<SWARM_KEY>-<APP_KEY>-<dev|prod>, app yönlendirici rolüyle katılır. Yönlendirici oradaki her yayımlama, abonelik, çağrı ve kaydı bu rolün izin listesine göre denetler. SDK’nın kendi metotları bu listenin içinde kalır; kurallar, publish, subscribe veya call metotlarına kendi URI’lerinizi verdiğinizde ya da connection nesnesini (Go’da Connection()) doğrudan kullandığınızda önem kazanır. Reddedilen bir eylem wamp.error.not_authorized ile başarısız olur (Go’da ironflock.WampURI(err) bunu döndürür).

Kimliği denetlenen adlar. Bir rakamla başlayan adlar — tablo yazma konuları ve cihaz fonksiyonu URI’leri — ayrıca platformun kimlik denetiminden geçer; bu denetim onları realm’inizin SWARM_KEY değerine bağlar. Bir kayıt yalnızca kendi cihazınıza ait, realm’inizin SWARM_KEY, APP_KEY ve aşama (stage) değerlerini taşıyan bir fonksiyon URI’si için kabul edilir; önek veya joker karakterli bir kayıt ise yalnızca bu dört segmenti sabitlediğinde kabul edilir. Yayımlama ve çağrı yalnızca realm’inizin SWARM_KEY değerini gerektirir: başka bir APP_KEY içeren bir tablo konusuna yayımlanan satır kabul edilir, ancak hiçbir veri arka ucuna ulaşmaz ve kaybolur. Bu URI’leri SDK’nın oluşturmasına bırakın.

Ayrılmış adlar. Yönlendirici, yukarıdaki iki uygulamalar arası prosedür dışında sys. adlarını ve wamp.session.get dışında wamp. adlarını reddeder. Tablodaki diğer adlar platforma aittir: kendi adlarınızı bir rakamla, bulk., transformed., databackend.errors., files., append., appendBulk., history. veya secret. ile başlatmayın. Diğer her ilk segment, uygulamanızın kendi konu alanıdır.

Ham tablo konularına kimse abone olmaz. Bu konular satırı tam olarak gönderildiği gibi, gizli sütunların düz metni dahil taşır; veri arka ucu gizli sütunları ancak satırı saklarken şifreler. subscribeToTable / subscribe_to_table bunun yerine saklanan satırları transformed.<table> konusundan, tiplendirilmiş ve gizli sütunları maskelenmiş olarak okur.

Diğer uygulamaların verileri salt okunurdur. Bir sağlayıcının realm’inde uygulamanız (app_reader yönlendirici rolü), heartbeat için kullanılan wamp.session.get dışında yalnızca transformed.… ve files.events… konularına abone olabilir ve history.transformed.… ile files.read.… prosedürlerini çağırabilir — yayımlama, kayıt, yazma ve gizli değer prosedürleri yoktur.

Cihaz Meta Verisi

setDeviceLocation / set_device_location

Platformdan cihazın GPS konumunu güncellemesini ister; IronFlock haritaları bu konumu gerçek zamanlı olarak gösterir.

Şu anda kullanılamıyor: uygulamanın veri realm’inde bu çağrıyı yanıtlayan bir platform servisi henüz yok, bu yüzden çağrı wamp.error.no_such_procedure ile başarısız olur. O zamana kadar konumları kendi tablonuzda tutun.

await ironflock.set_device_location(long=8.6821, lat=50.1109)

await ironflock.setDeviceLocation(8.6821, 50.1109);

_, err := ifl.SetDeviceLocation(ctx, 8.6821, 50.1109) // long, lat
if err != nil {
	return err // wamp.error.no_such_procedure for now
}

Konum geçmişi saklanmaz. Konumu zaman içinde takip etmek için ayrı bir tablo oluşturun ve publish_to_table / publishToTable kullanın.

getRemoteAccessUrlForPort

Uygulamanın port-template.yml dosyasında tanımlanan bir portun, tüneli etkinleştiğinde erişilebilir olduğu URL’yi döndürür.

url = ironflock.getRemoteAccessUrlForPort(8080)
# "https://<device_key>-<app_name>-8080.app.ironflock.com"
 
vnc = ironflock.getRemoteAccessUrlForPort(5900, protocol="tcp")
# "tcp://app.ironflock.com:<the tunnel's remote port>"

const url = ironflock.getRemoteAccessUrlForPort(8080);
// "https://<device_key>-<app_name>-8080.app.ironflock.com"
 
const vnc = ironflock.getRemoteAccessUrlForPort(5900, "tcp");
// "tcp://app.ironflock.com:<the tunnel's remote port>"

url, ok := ifl.GetRemoteAccessURLForPort(8080, "", "")
// "https://<device_key>-<app_name>-8080.app.ironflock.com", true
 
vnc, ok := ifl.GetRemoteAccessURLForPort(5900, "tcp", "")
// "tcp://app.ironflock.com:<the tunnel's remote port>", true

http ve https portları, cihaz ajanının enjekte ettiği tünel alan adında (TUNNEL_DOMAIN) <device_key>-<app name, lower case>-<port> tünel etiketi altında (https portları platformun secure- önekiyle) her zaman bir https:// URL’si olarak sunulur. Yerinde (on-premises) bir appliance’a ait bir cihazda (ajan INSTANCE_KEY enjekte eder) bunun yerine bulut üzerinden yönlendirilen https://i<INSTANCE_KEY>-<label>.<CLOUD_TUNNEL_DOMAIN> yolu döndürülür.

Bir tcp veya udp URL’si, tünelin atadığı ve cihaz ajanının REMOTE_PORT_FOR_<port> olarak duyurduğu (ajan 0.19.8 ve sonrası) genel portu taşır: <protocol>://<TUNNEL_DOMAIN>:<remote port>. Bir appliance’ın cihazında, ajan duyurduğu sürece internete açık port olan REMOTE_PORT_FOR_<port>_CLOUD tercih edilir; bu port görünmeden önce ve ajan onu kaldırdıktan sonra yeniden (bulut yönlendirmesi kapatıldığında) appliance’ın yerel URL’si döndürülür. 0 değerindeki bir port henüz atanmamıştır.

Değerler /data/env dizininden canlı olarak okunur; bu nedenle sonucu önbelleğe almak yerine metodu yeniden çağırın. URL’nin karşılayamadığı bazı durumlar:

• Cihaz ajanı yalnızca üretim (PROD) kurulumlarının portları için tünel açar. Bir geliştirme (DEV) container’ında http(s) URL’si, bu cihazdaki aynı uygulamanın PROD kurulumunun URL’sidir; tcp/udp ise hiçbir URL vermez. Bir DEV uygulamasına bunun yerine cihazın LAN adresi üzerinden ulaşın (DEVICE_LAN_IP, DEVICE_PORT_FOR_<port>).
• Alan adı olmadan (düz mod) kurulmuş bir appliance’ın uç cihazında ajan TUNNEL_DOMAIN değerini localhost olarak ayarlar; bu yüzden orada oluşturulan URL’ler localhost’u gösterir: böyle bir appliance, uygulama portlarını kendi ana makine portlarında sunar ve bunu bir tünel URL’si ifade edemez.
• Ayarlanmamış veya boş tünel alan adları varsayılan olarak app.ironflock.com olur. Platform bugün CLOUD_TUNNEL_DOMAIN değerini ayarlamaz: uygulama bu değişkeni ortam ayarlarında kendisi ayarlamadıkça bir appliance’ın URL’leri app.ironflock.com kullanır.
• Root dışında bir kullanıcıyla çalışan bir container’da değerler, container’ın başladığı andaki değerlerdir (bkz. Ortam Değişkenleri).

URL oluşturulamadığında metot None / null (Go’da "" ve false) döndürür: cihaz anahtarı veya uygulama adı eksikse, bir tcp/udp portu için henüz uzak port duyurulmamışsa (veya değeri 0 ise), protokol bilinmiyorsa ya da etiket geçerli bir DNS etiketi değilse (63 karakterden uzun veya noktalı bir uygulama adı). Tarayıcıda ortam yoktur: http(s) URL’si deviceKey ve appName seçeneklerinden app.ironflock.com üzerinde oluşturulur.

Bağlantı Özellikleri & Yaşam Döngüsü

Bağlantı Güvenilirliği

SDK kendiliğinden yeniden bağlanır. Bağlantı koptuğunda router geri gelene kadar yeniden dener, ardından her aboneliği ve kayıtlı her cihaz fonksiyonunu geri yükler — yeniden bağlandıktan sonra tekrar abone olmanız gerekmez. Biri geri yüklenemezse diğerleri yine de geri yüklenir; başarısız olan ise oturum sürdüğü müddetçe yeniden denenir — 1 saniye sonra, 30 saniyeye kadar ikiye katlanarak ve her bekleme %15’e kadar değiştirilerek — ve her yeniden bağlanmadan sonra tekrar denenir: router onu daha önce kabul etmişti, dolayısıyla reddi geçicidir; örneğin platformun bir cihaz fonksiyonu için yaptığı kimlik denetiminin bir anlığına güvenli tarafta kalarak reddetmesi (fail closed) gibi. İlk başarısızlık bir uyarı olarak kaydedilir; geri yükleme başarılı olduğunda da kaydedilir.

Tablo işlemleri — yazmalar, geçmiş, seri ve gizli değer okumaları ile tüketilen bir uygulamanın geçmiş okumaları — router veya platform güncellemesi gibi bir platform yeniden başlatmasını da atlatır. Bağlantının geri gelmesi için reconnect_window (Python, saniye cinsinden) / reconnectWindowMs (JavaScript) / WithReconnectWindow (Go, bir time.Duration) kadar, varsayılan olarak 60 saniye beklerler ve veri arka ucu prosedürlerini henüz sunmadığı sürece yeniden denerler: router wamp.error.no_such_procedure yanıtını verir ya da veri arka ucu, kaydının önüne geçen bir çağrıyı “client has no handler for registration” ile reddeder. Böyle bir çağrı hiçbir zaman bir işleyiciye ulaşmamıştır; bu yüzden bir yeniden deneme bir satırı asla iki kez yazmaz; diğer her hata geldiği gibi yükseltilir. Dosya çağrıları yeniden denenmez (bkz. Dosya Depolama Hataları). Oturumu kapandığında (router onu kapattığında, bağlantı koptuğunda ya da stop() çağrıldığında) zaten gönderilmiş olan bir istek, yanıt beklemek yerine hemen başarısız olur ve yeniden denenmez: işleyicisine ulaşmış olabilir. Go’da böyle bir istek — ve beklemesi içinde bağlantı bulamayan her işlem — wamp.ErrNotConnected’ı (Stop’tan sonra wamp.ErrStopped’u) saran bir hatayla başarısız olur. Go’nun diğer işlemleri (Publish, Subscribe, Call, cihaz fonksiyonları, uygulamalar arası keşif) bir bağlantı için en fazla 10 saniye bekler ve yeniden denenmez.

Özel bir durum, erişilebilir olan ancak uygulama için henüz bir realm’i bulunmayan router’dır. Eşzamanlı kurulum yarışında uygulama konteyneri, veri arka ucu realm’ini hazırlamadan önce başlar; bu yüzden ilk katılma denemeleri wamp.error.no_such_realm ile reddedilir. SDK birkaç saniyede bir yeniden dener ve realm oluştuğu anda uygulama ayağa kalkar. Bir dakika sonra hâlâ eksik olan bir realm büyük olasılıkla hiç oluşmayacaktır — uygulama silinmiştir ya da bu stage için bir veri arka ucu yoktur —, bu nedenle SDK o andan itibaren router’a sonsuza kadar her saniye istek göndermek yerine iki dakikada bir denemeye yavaşlar. Realm ortaya çıktığında ya da router’ın kendisi gidip geri geldiğinde hızlı tempo geri döner.

stop(), bir bağlantı için süren her beklemeyi sona erdirir. Örneğin henüz var olmayan bir realm’e ilk katılmasını hâlâ bekleyen bir start(), Connection to realm <realm> stopped before it opened ile başarısız olur. Bir sağlayıcının bağlantısını hâlâ açmakta olan bir connect_to_app / connectToApp, Connection to app '<app>' (<stage>) aborted by stop() ile başarısız olur; bağlantı yine de katılırsa kapatılır ve çağrı Connection to app '<app>' (<stage>) closed by stop() ile başarısız olur. stop() ile yarışan bir ret, kendi CrossAppAccessError hatasını korur. stop() döndüğünde bağlanmaya çalışan hiçbir şey kalmaz; ayrılma isteğine yanıt vermeyen bir router’ın bağlantısı 5 saniye sonra kesilir.

Go’da Stop(ctx) de bu beklemeleri wamp.ErrStopped’u saran hatalarla sonlandırır: hâlâ bekleyen bir Start bu hatayı döndürür, hâlâ açılmakta olan bir ConnectToApp ise ironflock: connection to app '<app>' (<stage>) aborted by Stop ile (bağlantı yine de katıldığında closed by Stop ile) başarısız olur. Stop, ayrılmayı ctx içinde bekler ve ardından soketi kapatır; Run ona 10 saniye tanır.

Daha zor durum, sessizce ölen bir bağlantıdır: boştayken bir NAT ya da proxy iki tarafa da haber vermeden bağlantıyı keser veya bir yük dengeleyicinin arkasındaki router yeniden başlar. Kaybı bildiren hiçbir şey gelmez. Yalnızca veri yayımlayan bir uygulama bunu bir sonraki başarısız yazma işleminde fark eder; ancak yalnızca abone olan bir uygulama hiç yazmaz, dolayısıyla yardım almadan konteyner yeniden başlayana kadar ölü kalır.

Üç SDK da bunu tespit eder. Tespit varsayılan olarak etkindir ve yapılandırma gerektirmez.

const ironflock = new IronFlock();
 
ironflock.connection.heartbeatIntervalMs = 60000; // probe every 60s
ironflock.connection.heartbeatTimeoutMs = 15000;  // allow 15s to answer
 
await ironflock.start();

connectToApp / connect_to_app ile açılan uygulamalar arası bağlantılar genellikle yalnızca abone olur; bu da tam olarak burada korunan durumdur. Otomatik olarak kapsanırlar ve router onları reddettikten sonra da, ret kalıcı hale gelene kadar yeniden bağlanırlar (bkz. connectToApp).

Hata Yönetimi

Her SDK metodu hatayı açıkça bildirir: geçersiz argümanlarda, kopan bir bağlantıda veya platformdan gelen bir reddetmede, işlemi, konuyu ve nedeni belirten bir mesajla bir istisna yükseltir (Python), reddeder (JavaScript) ya da bir hata döndürür (Go). Hiçbir şey sessizce yutulmaz; bu nedenle hayatta kalmasını istediğiniz çağrıları bir try bloğuna sarın — Go’da döndürülen hatayı denetleyin.

try:
    rows = await ironflock.getHistory("sensordata", {"limit": 100})
except ValueError as e:
    # Invalid parameters — e.g. limit out of range, or a malformed filter
    print(f"Bad query: {e}")
except RuntimeError as e:
    # Not connected, table not in the data-template, or the platform rejected the call
    print(f"Query failed: {e}")

import { WampError } from "ironflock";
 
try {
    const rows = await ironflock.getHistory("sensordata", { limit: 100 });
} catch (e) {
    if (e instanceof WampError) {
        // Rejected by the platform — e.error holds the WAMP error URI
        console.error(`Query rejected: ${e.error}`, e.args);
    } else {
        // Invalid parameters, or no connection
        console.error(`Query failed: ${e.message}`);
    }
}

rows, err := ifl.GetHistory(ctx, "sensordata", &ironflock.TableQueryParams{Limit: 100})
var werr *ironflock.WampError
switch {
case errors.Is(err, ironflock.ErrInvalidArgument):
	// Invalid parameters — e.g. limit out of range, or a malformed filter
	log.Println("Bad query:", err)
case errors.As(err, &werr):
	// Rejected by the platform — werr.URI holds the WAMP error URI
	log.Println("Query rejected:", werr.URI, werr.Args)
case errors.Is(err, wamp.ErrNotConnected):
	// No connection within the operation's wait
	log.Println("Query failed:", err)
case err != nil:
	log.Println("Query failed:", err)
default:
	log.Println(len(rows), "rows")
}

JavaScript’te platformdan kaynaklanan hatalar WampError örnekleridir — ek olarak WAMP hata URI’sini error içinde, hata yükünü ise args / kwargs içinde taşıyan normal bir Error alt sınıfı. Bunun dışındaki her şey (hatalı parametreler, bağlantı olmaması) düz bir Error’dır.

Go’da başarısız bir işlem, mesajı işlemi ve nedeni belirten ve bu nedeni saran bir *ironflock.OperationError döndürür; errors.Is ve errors.As onun içini görür. Router’dan veya çağrılan taraftan gelen bir ret, URI, Args ve Kwargs alanlarına sahip bir *ironflock.WampError’dır (*wamp.Error); ironflock.WampURI(err) URI’yi ya da "" döndürür. Diğer sentinel hatalar ironflock.ErrMissingConfig (işlemin ihtiyaç duyduğu kimlik bilgisi eksik), ironflock.ErrAlreadyStarted ve wamp.ErrStopped’tur (Stop’tan sonra).

Yükseltme: Eski Python ve JavaScript SDK sürümleri bir çağrı başarısız olduğunda bir mesaj kaydedip None / null döndürüyordu. Artık bunun yerine hata yükseltiyorlar; bu nedenle if result is None: biçimindeki kodlar hataları artık yakalamaz — try / except (ya da try / catch) kullanın.

Veri Arka Ucu Retleri

Veri arka ucunun reddettiği bir işlem, aşağıdaki WAMP hata URI’lerinden biriyle başarısız olur; neden ilk argümandadır. Üç SDK da bunları sabitler olarak dışa aktarır; Go bunları Go stilinde adlandırır (ironflock.URIRateLimited, ironflock.URIStorageFull, …). Python’da IronFlock metotları, nedeni autobahn’ın ApplicationError hatası olan bir RuntimeError yükseltir (tüketilen bir uygulamanın okumaları doğrudan ApplicationError yükseltir) ve wamp_error_uri(err) URI’yi her ikisinden de okur. JavaScript’te hata, error alanı URI olan bir WampError nesnesidir. Go’da bir *ironflock.WampError’ı saran bir *ironflock.OperationError’dır ve ironflock.WampURI(err) URI’yi okur. SDK’lar bunların hiçbirini yeniden denemez. Veri arka ucunun reddettiği yayımlanmış bir satır hatasız düşürülür — bunu yalnızca append metotları bildirir.

from datetime import datetime, timezone
from ironflock import URI_STORAGE_FULL, wamp_error_uri
 
row = {"tsp": datetime.now(timezone.utc).isoformat(), "temperature": 22.5}
try:
    await ironflock.append_to_table("sensordata", row)
except RuntimeError as err:
    if wamp_error_uri(err) == URI_STORAGE_FULL:
        pending.append(row)  # the appliance's disk is nearly full: append the row later
    else:
        raise

import { WampError, URI_STORAGE_FULL } from "ironflock";
 
const row = { tsp: new Date().toISOString(), temperature: 22.5 };
try {
    await ironflock.appendToTable("sensordata", [row]);
} catch (err) {
    if (err instanceof WampError && err.error === URI_STORAGE_FULL) {
        pending.push(row); // the appliance's disk is nearly full: append the row later
    } else {
        throw err;
    }
}

row := ironflock.Row{"tsp": time.Now(), "temperature": 22.5}
_, err := ifl.AppendToTable(ctx, "sensordata", row)
if ironflock.WampURI(err) == ironflock.URIStorageFull {
	pending = append(pending, row) // the appliance's disk is nearly full: append the row later
} else if err != nil {
	return err
}

Veri arka ucunun neden belirtmeden reddettiği bir ekleme — wamp.error.runtime_error, tsp içermeyen bir satıra verdiği yanıt — türü belirli bir ret değildir: SDK’nın hata mesajı eksik tsp değerine ve veri arka ucunun nedeni kaydettiği, uygulamanın error-logs tablosuna işaret eder.

Tarayıcı Kullanımı (Yalnızca JavaScript)

JavaScript SDK modern tarayıcılarda çalışır. Tarayıcılarda ortam değişkenleri bulunmadığından, tüm yapılandırmayı yapıcı aracılığıyla geçin:

import { IronFlock } from "ironflock";
 
const ironflock = new IronFlock({
    serialNumber: "device-serial-from-server",
    deviceKey: "12",
    appName: "MyWebApp",
    swarmKey: 10,
    appKey: 20,
    env: "PROD",
});
 
await ironflock.start();
await ironflock.publishToTable("sensordata", [{ tsp: new Date().toISOString(), temperature: 22 }]);

Kimlik bilgilerini sabit kodlamak yerine arka ucunuzdan yapılandırma almak için IronFlock.fromServer()’ı kullanın:

const ironflock = await IronFlock.fromServer("/api/ironflock-config");
await ironflock.start();

Arka uç uç noktanız, bağlantı seçenekleriyle (serialNumber, deviceKey, appName, swarmKey, appKey, env) bir JSON nesnesi döndürmelidir.

AI Ajan Fonksiyonlarını Kaydetme

SDK, AI ajanları tarafından çağrılabilecek fonksiyonlar kaydedebilir. Bir prosedür kaydedin ve ai-template.yml dosyanızdaki konusunu referans alın:

def get_sensor_reading(sensor_id):
    """Returns the latest reading from a sensor."""
    reading = read_from_hardware(sensor_id)
    return {
        "sensor_id": sensor_id,
        "temperature": reading.temp,
        "humidity": reading.hum,
        "timestamp": reading.ts
    }
 
await ironflock.register_device_function("sensors.get_latest", get_sensor_reading)