Ana içeriğe geç

REST Endpoint Tanımlama

Bu sayfa, Pirivision Compass modülünde bir REST API veri kaynağı üzerine HTTP endpoint tanımlayıp Compass kaydı olarak saklama sürecini anlatır.

Kaydedilen REST endpoint, Cartography modülünde chart / KPI widget'ı oluşturmak için kullanılır.

Ön Koşul — Port Veri Kaynağı

Bu endpoint'i tanımlamak için Port modülünde bir REST API veri kaynağı tanımlı olmalıdır. Henüz eklenmemişse önce Port'a gidin ve Base URL ile kimlik doğrulama bilgilerini tanımlayın.

→ Port: REST API Veri Kaynağı Ekleme

Tanımlama Öncesi Gerekli Bilgiler

Bu sayfadaki örnekler Demo Fabrika REST akışının sunduğu mock endpoint'leri ve Port'taki Demo Fabrika - REST veri kaynağını kullanır. Endpoint'leri kendi ortamınızda başlatmak için bkz. Sentetik Veri Üretimi — REST API.

Bilgi Açıklama Varsayılan Örnek
Veri Kaynağı Port modülünde eklenmiş REST API bağlantısı — Demo Fabrika - REST
Endpoint Path Base URL'ye göreli endpoint yolu — /api/sayac/anlik
HTTP Metodu İstek yöntemi GET GET
Kayıt Adı Compass listesinde görünen isim — Anlık Üretim Sayacı
Hedef Klasör Kaydın yerleştirileceği Compass klasörü Kök (Root) Demo Fabrika / REST

Base URL ve Path Ayrımı

Base URL Port modülünde veri kaynağına tanımlanır (ör. http://<sunucu>:1880). Endpoint path Compass'ta kayıt bazında tanımlanır (ör. /api/sayac/anlik). Birlikte: http://<sunucu>:1880/api/sayac/anlik

1. Compass Modülüne Girin

Sol menüden Compass modülüne tıklayın.

Compass listesi

2. Yeni REST Kaydı Oluşturun

Sağ üstteki Add New Query butonuna tıklayın. (UI'da "Query" terimi yer alır; REST API için bu eylem Compass'a yeni bir endpoint tanımı eklemek anlamına gelir.)

3. REST API Veri Kaynağı Seçin

Select Your Data Source ekranında REST API kategorisindeki veri kaynağını seçin.

Next butonuna tıklayın.

Veri kaynağı seçim ekranı — REST API tipi

4. REST Endpoint Formu Açılır

REST API veri kaynağı seçildikten sonra REST endpoint formu açılır.

REST endpoint formu — genel görünüm

Formun bölümleri:

Bölüm Açıklama
Endpoint Path Base URL'ye eklenecek göreli yol
HTTP Method GET / POST
Query Parameters URL'ye eklenen key-value parametreler
Headers Endpoint'e özel HTTP başlıkları (Port global headers'a ek)
Body POST isteği için istek gövdesi (JSON / form)
Response Preview Test yanıtı önizlemesi

5. Endpoint Path'i Girin

Endpoint Path alanına Base URL'ye göreli yolu girin.

Alan Zorunlu Açıklama Varsayılan Örnek
Endpoint Path Evet Göreli URL yolu; / ile başlamalı — /api/sayac/anlik
HTTP Method Evet GET veya POST GET GET

Demo Fabrika endpoint'leri

/api/sayac/anlik, /api/oee/today, /api/vardiya/dun, /api/alarm/son50 — query parametresi yok. /api/sicaklik/trend (hat={{hat_id}}, hours={{hours}}), /api/durus/dagilim (gun={{day}}), /api/recete (makine={{makine_id}}) — query parametresi var (aşağıya bakın).

6. Query Parameters Ekleyin (İsteğe Bağlı)

URL'e eklenecek key-value parametreleri tanımlayın. (Demo Fabrika'da /api/sayac/anlik için bu adım atlanır; /api/sicaklik/trend veya /api/recete için kullanılır.)

Alan Zorunlu Açıklama Varsayılan Örnek
Key — Parametre adı — hat
Value — Parametre değeri ({{param}} sözdizimi desteklenir) — {{hat_id}}

Örnek (sıcaklık trendi): Key: hat → Value: {{hat_id}} ve Key: hours → Value: {{hours}}.

+ Add Parameter butonuyla yeni satır eklenebilir.

Dinamik Parametreler

{{param_adi}} sözdizimi kullanılan parametreler (örn. {{hat_id}}, {{makine_id}}), kayıt panelinde Global Değişken olarak tanımlanır ve dashboard filtrelerine bağlanabilir. REST'te değer düz string olarak yerine konur.

7. Endpoint'e Özel Headers Ekleyin (İsteğe Bağlı)

Port'taki global başlıklara ek olarak bu endpoint için özel başlıklar tanımlanabilir. (Demo Fabrika Node-RED mock endpoint'leri kimlik doğrulama / başlık gerektirmez; bu adım kimliği korunan gerçek API'ler içindir.)

Alan Zorunlu Açıklama Varsayılan Örnek
Header Key — Başlık adı — X-Source
Header Value — Başlık değeri ({{param}} desteklenir) — pirivision

REST endpoint formu — doldurulmuş

8. Transform Code Ekleyin (İsteğe Bağlı)

API yanıtını Pirivision chart'larına göndermeden önce JavaScript ile dönüştürmek istiyorsanız form sağ üst köşesindeki Enable Transform butonuna tıklayın. Bir kod editörü açılır.

Script Ortamı

Değişken Tür Açıklama
data object \| array \| null API'den gelen, JSON olarak parse edilmiş yanıt
runtimeParams object Compass'ta {{param}} sözdizimi ile tanımlanan dinamik parametreler

Script mutlaka bir değer döndürmelidir (return zorunlu). Yürütme süresi 200 ms ile sınırlıdır; fetch, setTimeout veya I/O erişimi desteklenmez.

Yardımcı fonksiyonlar:

Fonksiyon Açıklama
Safe.parseJSON(str) JSON parse eder; hata durumunda null döner
Safe.toJSON(val) JSON.stringify wrapper'ı

Senaryo Örnekleri

Senaryo 1 — Temel geçiş (veri düzenleme gerekmiyorsa)

API zaten Pirivision'ın beklediği formatta veri döndürüyorsa dönüşüm gerekmez; ancak null koruması eklenebilir.

if (!data) return null;
return data;

Senaryo 2 — İç içe geçmiş nesneden dizi çekme

API yanıtı { "result": { "items": [...] } } biçimindeyse ve chart yalnızca items dizisini bekliyorsa:

if (!data) return null;
return data.result.items;

Senaryo 3 — Alan filtreleme (yalnızca belirli sütunlar)

Her satırdan yalnızca ts, deger ve hat alanlarını chart'a gönder:

if (!Array.isArray(data)) return data;

return data.map(row => ({
  ts:    row.ts,
  deger: row.deger,
  hat:   row.hat,
}));

Senaryo 4 — Türetilmiş alan hesaplama

API oee değerini 0–1 aralığında döndürüyorsa bunu yüzdeye çevir ve chart'ta göster:

if (!data) return null;

return {
  ...data,
  oee_pct: Math.round((data.oee ?? 0) * 100),
};

Senaryo 5 — Dizi filtreleme

Alarm listesinden yalnızca aktif alarm kayıtlarını döndür:

if (!Array.isArray(data)) return data;

return data.filter(item => item.durum === 'aktif');

Senaryo 6 — runtimeParams ile istemci tarafı filtreleme

Compass'ta {{hat_id}} parametresi tanımlandığında, API tüm hatları döndürse bile script'te seçilen hat'a göre filtreleme yapılabilir:

if (!Array.isArray(data)) return data;

return data.filter(row => row.hat === runtimeParams.hat_id);

Senaryo 7 — Duruş tipi dağılımı: yüzde alanı ekleme

/api/durus/dagilim gibi bir endpoint aşağıdaki diziyi döndürdüğünde, her satıra toplam içindeki yüzde payını ekleyerek Pie / Doughnut chart'ta etiket olarak kullanabilirsiniz:

[
  { "adet": 128, "duris_tipi": "Ayar Değişimi" },
  { "adet": 107, "duris_tipi": "Arıza" },
  { "adet": 98,  "duris_tipi": "Vardiya Devri" },
  { "adet": 79,  "duris_tipi": "Planlı Bakım" },
  { "adet": 29,  "duris_tipi": "Malzeme Bekleme" }
]

if (!Array.isArray(data) || data.length === 0) return data;

var toplam = data.reduce(function(acc, row) {
  return acc + (row.adet || 0);
}, 0);

return data.map(function(row) {
  return {
    duris_tipi: row.duris_tipi,
    adet:       row.adet,
    yuzde:      toplam > 0
                  ? Math.round((row.adet / toplam) * 1000) / 10  // 1 ondalık
                  : 0,
  };
});

Çıktı: her satırda duris_tipi, adet, yuzde (%) alanları — Pie/Doughnut chart'ta duris_tipi kategori, adet veya yuzde değer ekseni olarak kullanılır.

Senaryo 8 — Top-N: yalnızca en yüksek N tipi göster

Çok fazla duruş tipi varsa grafik kalabalıklaşır. Yalnızca en yüksek N adetli tipleri döndürün:

if (!Array.isArray(data) || data.length === 0) return data;

var n = 3; // kaç tip gösterilecek

return data
  .slice()                                          // orijinal diziyi bozmamak için kopyala
  .sort(function(a, b) { return b.adet - a.adet; }) // büyükten küçüğe sırala
  .slice(0, n);                                     // ilk N'i al

Çıktı: [ Ayar Değişimi(128), Arıza(107), Vardiya Devri(98) ] — "Planlı Bakım" ve "Malzeme Bekleme" gösterilmez.

Senaryo 9 — Eşik altı tipleri "Diğer" grubunda birleştirme

Az adetli tipleri tek bir "Diğer" kalemi altında toplayarak grafik okunabilirliğini artırın:

if (!Array.isArray(data) || data.length === 0) return data;

var esik = 50; // bu adet altındakiler "Diğer"e gider

var buyukler  = [];
var digerAdet = 0;

data.forEach(function(row) {
  if (row.adet >= esik) {
    buyukler.push(row);
  } else {
    digerAdet += row.adet;
  }
});

if (digerAdet > 0) {
  buyukler.push({ duris_tipi: "Diğer", adet: digerAdet });
}

return buyukler.sort(function(a, b) { return b.adet - a.adet; });

Çıktı: Ayar Değişimi(128), Arıza(107), Vardiya Devri(98), Planlı Bakım(79), Diğer(29) — eşik 50 olduğunda yalnızca "Malzeme Bekleme" "Diğer"e düşer.

Yürütme süresi aşılırsa

Script 200 ms içinde tamamlanamazsa transform timeout/interrupt hatası alınır. Büyük diziler için filter ve map yerine erken dönüş (return) tercih edin ya da ağır hesaplamayı API tarafında yapın.

9. Endpoint'i Test Edin

Send veya Test butonuna tıklayın.

İstek gerçek API'ye gönderilir ve yanıt aşağıda gösterilir:

Bilgi Açıklama
HTTP Durum Kodu 200 OK, 401 Unauthorized, 404 Not Found vb.
Yanıt Süresi Milisaniye cinsinden yanıt süresi
Yanıt İçeriği JSON / XML formatında syntax-highlighted önizleme

Demo Fabrika /api/sayac/anlik yanıtı

/api/sayac/anlik endpoint'i test edildiğinde aşağıdakine benzer bir JSON yanıt gelir (200 OK):

{
  "sayac": 18342,
  "ts": "2026-05-06T11:47:03.000Z",
  "hat": "HAT-1",
  "birim": "adet"
}

REST test yanıtı — JSON önizleme

10. Endpoint Kaydını Saklayın

Test başarılıysa sağ üstteki Save butonuna tıklayın. Kayıt paneli açılır.

Kayıt paneli

11. Display Info — Ad ve Açıklama

Alan Zorunlu Açıklama Varsayılan Örnek
Name Evet Compass listesinde görünen kayıt adı — Anlık Üretim Sayacı
Description Hayır Endpoint'in amacını açıklayan metin — Node-RED /api/sayac/anlik mock endpoint — anlık sayaç verisi

12. Location — Hedef Klasör

Kayıt panelinde Target Folder alanından klasörü seçin. Seçilmezse kök dizine kaydedilir.

13. Kaydet Butonuna Tıklayın

Panelin alt kısmındaki Save butonuna tıklayın.

14. Listede Kontrol

Compass listesinde yeni REST endpoint kartı görünmelidir.

Compass listesi — REST endpoint kartı

15. Sık Karşılaşılan Hatalar

Hata / Belirti Olası Neden Çözüm
"could not open target DB: ..." REST API veri kaynağı bağlantı hatası Port modülünde REST API bağlantısını test edin
HTTP 401 Unauthorized API kimlik doğrulama başarısız Port veri kaynağında Authorization header'ını ve değerini kontrol edin
HTTP 403 Forbidden Erişim yetkisi yok API anahtarının veya tokenın erişim iznini kontrol edin
HTTP 404 Not Found Endpoint path yanlış Path'i doğrulayın; Base URL + Path kombinasyonunu test edin
HTTP 408 / timeout Yanıt süresi aşıldı Port'taki Timeout değerini artırın (varsayılan: 5000 ms)
Demo Fabrika endpoint'leri 404 veriyor Node-RED akışı başlatılmadı Bkz. Sentetik Veri Üretimi — REST API
Boş yanıt API veri döndürmüyor API dokümantasyonunu kontrol edin; parametreler doğru mu?
"you already have a query named '...'" Aynı isimde Compass kaydı mevcut Farklı bir ad seçin
transform error: ... Transform script çalışma hatası Script sözdizimini ve return ifadesini kontrol edin
transform timeout/interrupt Script 200 ms sınırını aştı Büyük veriyi API tarafında filtreleyin; script'i sadeleştirin

Sonraki Adım

REST endpoint Compass'a kaydedildikten sonra Cartography modülünde bu kaydı kullanan bir chart veya KPI widget oluşturulabilir.

→ Cartography