REST API Veri Kaynağı Ekleme

Bu sayfa, Pirivision Port modülünde REST API veri kaynağı ekleme sürecini anlatır.

REST API bağlantısı oluşturulduktan sonra veri kaynağı Compass modülünde HTTP endpoint'lerine sorgu göndermek için kullanılabilir. Compass'ta hazırlanan sorgular daha sonra Cartography tarafında chart / KPI formatına dönüştürülür ve Horizon veya Atlas dashboardlarında kullanılır.

Ön Koşul

REST API veri kaynağı eklemeden önce şunlar hazır olmalıdır:

Erişilebilir bir Base URL (örn. https://api.example.com/v1)
Authentication türü ve kimlik bilgileri (None, Basic, Bearer Token, API Key)
Gerekiyorsa Global Headers değerleri

→ Port — REST API Genel Bakış

Ekleme Öncesi Gerekli Bilgiler

Bilgi	Açıklama	Varsayılan	Örnek
Name	Pirivision içinde veri kaynağına verilecek görünen isim	—	`REST-API`
Description	Veri kaynağının kullanım amacı	—	`REST-API for Example`
Base URL	Tüm isteklerin temel adresi	—	`https://pirivision.digitheta.dev`
Timeout	İstek zaman aşımı süresi (ms)	`5000`	`10000`
Retries	Başarısız istek yeniden deneme sayısı	`3`	`5`
Proxy	Proxy sunucu adresi (opsiyonel)	—	`https://proxy.example.com:8080`
SSL Verify	SSL sertifikasını doğrula	`OFF`	`ON`, `OFF`

Base URL

Base URL; tüm Compass sorgularının temelini oluşturur. Spesifik path'ler (örn. /api/v1/products) Compass ekranında sorgu tanımı sırasında eklenir.

1. Port Modülüne Girin

Sol menüden Port modülüne tıklayın. Port, Pirivision'da veri kaynaklarının eklendiği, listelendiği, düzenlendiği ve test edildiği modüldür.

Eğer daha önce veri kaynağı eklenmediyse ekranda Connect Your Factory Data mesajı görünür.

Bu ekrandan veri kaynağı eklemek için:

Add New Data Sources
Add Your First Data Source

butonlarından biri kullanılabilir.

2. Yeni Veri Kaynağı Ekleme Akışını Başlatın

Sağ üstteki Add New Data Sources butonuna tıklayın.

Boş liste ekranındaysanız orta bölümdeki Add Your First Data Source butonu da aynı akışı başlatır.

3. REST API Veri Kaynağı Tipini Seçin

Açılan ekranda Select Your Data Source Type başlığı altında veri kaynağı tipleri listelenir.

REST API eklemek için:

Web Services & Files bölümüne gidin.
RestAPI kartını seçin.
Sağ üstteki Next butonuna tıklayın.

Info

Pirivision'da web servislerine erişim için RestAPI seçeneği kullanılır. Excel dosyaları için Excel Offline, gerçek zamanlı IoT akışları için MQTT seçilmelidir.

4. REST API Formunu Doldurun

RestAPI seçildikten sonra Add a New RestAPI Data Source ekranı açılır.

Form dört ana bölümden oluşur:

Display Info
Essential Connection
Client Options
Location

5. Display Info

Display Info, veri kaynağının Pirivision arayüzünde nasıl görüneceğini belirler.

Alan	Zorunlu	Açıklama	Varsayılan	Örnek
Name	Evet	Veri kaynağını Pirivision içinde tanımak için kullanılan isimdir.	—	`REST-API`
Description	Hayır	Veri kaynağının ne işe yaradığını açıklayan kısa nottur.	—	`REST-API for Example`

Name

Bu veri kaynağını panellerde ve listelerde tanımak için kullanılır.

İyi örnekler:

REST-API
ERP_REST_API
OEE_Service
Production_API_v2

Description

Bu bağlantının ne işe yaradığını açıklayan isteğe bağlı alandır.

Örnek:

ERP sistemine bağlanan üretim planlama REST API'si.

6. Essential Connection

Essential Connection, REST API servisine bağlanmak için gereken temel yapılandırmayı içerir.

Alan	Zorunlu	Açıklama	Varsayılan	Örnek
Base URL	Evet	Tüm API isteklerinin ortak taban adresidir.	—	`https://pirivision.digitheta.dev`
Global Headers	Hayır	Tüm isteklere otomatik eklenen başlıklar (anahtar-değer çiftleri).	—	`Authorization: Bearer <token>`

Base URL

Tüm Compass sorgularının başlangıç noktasıdır. Spesifik API yolları (/api/v1/orders gibi) sorgu tanımında belirtilir.

Örnekler:

https://pirivision.digitheta.dev
https://erp.company.local:8080
http://192.168.1.200/api

Warning

Base URL, path içermemelidir. Doğru: https://api.example.com — Yanlış: https://api.example.com/v1/data.

Ping URL — Bağlantı Testi

Base URL alanının sağındaki Ping ikonu, formu kaydetmeden önce REST API sunucusuyla bağlantı doğrulaması yapmaya yarar. Aynı kontrol Test & Save sırasında da otomatik olarak çalışır; ancak Ping butonu, formu hâlâ doldururken hızlı geri bildirim vermek için tasarlanmıştır.

Ne yapar?

Pirivision backend'i (/restapi endpoint, type=ping_url) Base URL'e bağlantı yalnızca (connectivityOnly=true) modunda istek gönderir:

Aşama	Davranış
Hedef URL	Form'da girilen Base URL — değişiklik yapılmadan
Headers	O an form'a yazılı Global Headers satırları (boş key satırları atılır)
Method	`GET` — yanıt gövdesi okunmaz; yalnızca TCP/TLS handshake ve HTTP yanıtı doğrulanır
SSL	Form'daki SSL Verify anahtarı uygulanır (`OFF` → self-signed kabul edilir)
Timeout	Form'daki Timeout değeri (varsayılan 5000 ms)
Proxy	Form'da Proxy alanı doluysa istek proxy üzerinden geçer
Auth	Headers içine yazılı `Authorization`, `X-API-Key` gibi başlıklar otomatik gönderilir

Sonuç yorumu

Geri bildirim	Anlam	Yapılacak
🟢 `Connection successful!`	Sunucu yanıt verdi (2xx veya 3xx/4xx)	Bağlantı kurulabiliyor — kaydedebilirsiniz
🟠 `Connection successful!` ama beklenen API yanıtı değil	Reverse proxy / login sayfası dönmüş olabilir	URL'in API kökü olduğundan emin olun (`/api/...` Compass'ta verilir)
🔴 `Connection refused`	Sunucu portu kapalı veya servis ayakta değil	Servis durumu, port ve firewall kontrol edin
🔴 `i/o timeout`	Ağ erişimi yok veya yanıt yavaş	Timeout'u artırın; VPN / DNS doğrulayın
🔴 `x509: certificate signed by unknown authority`	Self-signed sertifika ve SSL Verify `ON`	SSL Verify'ı `OFF` yapın veya sertifikayı sisteme tanımlayın
🔴 `401` / `403` döndü	URL erişilebilir ama kimlik doğrulama başarısız	Global Headers'a `Authorization` ekleyin / değerini düzeltin
🔴 `404` döndü	Base URL path içeriyor olabilir	Path'i kaldırın; `/api/...` Compass'ta tanımlanır

Ping başarılı = sunucu erişilebilir

Pirivision 2xx olmayan yanıtları da bağlantı açısından "başarılı" sayar — çünkü amaç erişilebilirlik (host + port + TLS). Kimlik doğrulama hatasını (401/403) bağlantı testi geçemese de Pirivision yine "successful" gösterebilir; gerçek API çağrıları Compass'ta yapılır ve orada doğru endpoint + auth ile test edilmelidir.

Ne zaman manuel basılır, ne zaman otomatik çalışır?

Senaryo	Davranış
Base URL henüz boşsa Ping butonuna basılırsa	Uyarı: `Base URL alanını doldurun`
Ping butonuna art arda basıldığında	İkinci tıklama yok sayılır (`isPinging` koruması) — sonucu bekleyin
Test & Save butonu basıldığında	Önce aynı ping testi otomatik çalışır; başarılıysa kayıt yapılır, başarısızsa kaydetme durur
Form'u sadece kaydetmek istiyorsanız	Yine de Test & Save çalıştırılır — Pirivision bağlantı testi geçmemiş bir REST API kaydı oluşturmaz

Ping ne zaman güvenli alternatif?

Servis ayağa kalkma süresi uzun olan API'lerde (cold start), Test & Save'in ilk tıklamada timeout vermesi olağandır. Önce Ping ile ısıtın (cache açar, DNS çözer); ardından Test & Save ile kayıt edin.

Global Headers

Tüm Compass sorgularına otomatik olarak eklenen HTTP başlıklarıdır. Her satır bir anahtar-değer çiftidir.

Yaygın kullanım örnekleri:

Anahtar	Değer Örneği	Açıklama
`Authorization`	`Bearer eyJhbGci...`	JWT token kimlik doğrulaması
`Content-Type`	`application/json`	İstek gövdesi formatı
`X-API-Key`	`abc123def456`	API anahtar doğrulama
`Accept`	`application/json`	Yanıt formatı tercihi

Yeni başlık eklemek için + Add Header butonuna tıklanır.

Senaryo Örnekleri

Senaryo 1 — JWT Bearer Token ile kimlik doğrulama

ERP veya MES gibi token tabanlı API'lerde kullanılır. Token genellikle https://api.ornek.com/token gibi bir endpoint'ten alınır ve süresi dolana kadar geçerlidir.

Anahtar	Değer
`Authorization`	`Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI0MiJ9.abc123`

Senaryo 2 — API Key ile kimlik doğrulama

Sabit bir anahtar kullanan servislerde (hava durumu API'leri, bulut platformları vb.) kullanılır.

Anahtar	Değer
`X-API-Key`	`sk-prod-abc123def456ghi789`

Senaryo 3 — İçerik türü ve kabul başlıkları

POST isteklerinde gövdenin JSON formatında olduğunu ve yanıtta da JSON beklendiğini belirtir.

Anahtar	Değer
`Content-Type`	`application/json`
`Accept`	`application/json`

Senaryo 4 — Çok kiracılı (multi-tenant) ERP entegrasyonu

Aynı API endpoint'i birden fazla tesis veya şirket için kullanıldığında hangi kiracıya ait verinin döneceğini belirler.

Anahtar	Değer
`Authorization`	`Bearer eyJhbGci...`
`X-Tenant-ID`	`fabrika-001`
`Accept`	`application/json`

Override Headers

Global Headers bu veri kaynağı için varsayılan başlıkları belirler. Compass'ta bireysel sorgular için bu başlıklar geçersiz kılınabilir veya ek başlıklar eklenebilir.

7. Client Options

Client Options, REST API istemcisinin davranışını kontrol eden gelişmiş ayarları içerir.

Alan	Zorunlu	Açıklama	Varsayılan	Örnek
Timeout	Hayır	İstek zaman aşımı süresi (milisaniye)	`5000`	`10000`, `30000`
Retries	Hayır	Başarısız isteklerin yeniden deneme sayısı	`3`	`5`, `0`
Proxy	Hayır	Tüm isteklerin geçirileceği proxy sunucu adresi	—	`https://proxy.example.com:8080`
SSL Verify	Hayır	Sunucu SSL sertifikasının doğrulanması	`OFF`	`ON`, `OFF`

Timeout

API yanıtı bekleme süresidir. Bu süre aşılırsa istek zaman aşımı hatası döner.

Varsayılan değer:

Önerilen değerler:

5000   (hızlı API'ler için yeterli)
10000  (orta hızlı API'ler)
30000  (yavaş veya toplu veri döndüren API'ler)

Retries

Ağ hatası veya geçici servis kesintisi durumunda isteğin kaç kez yeniden deneneceğini belirler.

Varsayılan değer:

Proxy

İstekler bir proxy üzerinden yönlendirilecekse bu alan doldurulur.

Örnek:

https://proxy.example.com:8080

SSL Verify

REST API sunucusunun SSL sertifikasının doğrulanıp doğrulanmayacağını belirler.

Varsayılan değer:

OFF

SSL Verify

Üretim ortamında güvenilir SSL sertifikaları olan API'ler için ON kullanılması önerilir. Self-signed sertifika kullanan iç servisler için OFF bırakılabilir.

8. Location

Location, oluşturulan veri kaynağının Pirivision klasör yapısında nerede saklanacağını belirtir.

Alan	Açıklama	Varsayılan
Target Folder	Veri kaynağının kaydedileceği klasör	`Root Directory`

Target Folder alanına tıklandığında klasör seçim diyaloğu açılır:

Örnek klasörleme:

PORT/
├── Tesis 1/
│   ├── REST APIs/
│   ├── SCADA/
│   └── ERP/
├── Tesis 2/
│   └── REST APIs/
└── Test Sources/

9. Test & Save ile Bağlantıyı Kaydedin

Tüm zorunlu alanlar doldurulduktan sonra sağ alttaki Test & Save butonuna tıklayın.

Bu işlem iki aşamalı çalışır:

REST API Base URL'e bir ping isteği gönderilir ve erişilebilirlik test edilir.
Test başarılıysa veri kaynağı otomatik olarak kaydedilir.

Ekranda şu bilgi yer alır:

Connection will be saved automatically if the test is successful

Success

Test başarılı olursa REST API veri kaynağı Port ekranında listelenir ve Compass içinde HTTP sorgusu oluşturmak için kullanılabilir hale gelir.

Failure

Test başarısız olursa Base URL, ağ erişimi, SSL Verify ayarı ve Global Headers bilgilerini kontrol edin.

10. Veri Kaynağını Listede Kontrol Edin

Başarılı kayıt işleminden sonra Port ana ekranına dönüldüğünde oluşturulan REST API veri kaynağı listede görünür.

Liste kartında aşağıdaki bilgiler ve aksiyonlar yer alır:

Alan / Aksiyon	Açıklama
Veri kaynağı ikonu	REST API veri kaynağı olduğunu gösterir.
Name	Veri kaynağı adı.
Description	Açıklama metni.
Kullanım durumu	`In Use` veya `Not in Use` bilgisi.
Edit	Bağlantı bilgilerini günceller.
More	Ek işlemler menüsünü açar.
↳ Move	Veri kaynağını farklı bir klasöre taşır. → Veri Kaynağı Taşıma
↳ Duplicate	Aynı ayarlarla yeni bir kopya oluşturur. → Veri Kaynağı Çoğaltma
↳ Delete	Veri kaynağını kaldırır. → Veri Kaynağı Silme

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

Hata / Belirti	Olası Neden	Çözüm
Bağlantı kurulamıyor	Base URL yanlış veya erişilemiyor	URL'i tarayıcıda açarak erişilebilirliği doğrulayın.
`Connection refused`	Hedef servis çalışmıyor	API servisinin ayakta olduğunu kontrol edin.
Timeout hatası	Ağ gecikmesi veya servis aşırı yüklü	Timeout değerini artırın veya ağ bağlantısını kontrol edin.
`401 Unauthorized`	Kimlik doğrulama başarısız	Global Headers'taki Authorization değerini kontrol edin.
`403 Forbidden`	Yetersiz izin	API token'ının yeterli yetkiye sahip olduğunu doğrulayın.
`404 Not Found`	Base URL yanlış path içeriyor	Base URL'in path içermediğinden emin olun.
SSL sertifika hatası	Self-signed sertifika veya sertifika uyumsuzluğu	SSL Verify'ı `OFF` yapın veya sertifikayı doğrulayın.
JSON parse hatası	API JSON formatında yanıt vermiyor	API'nin `Content-Type: application/json` döndürdüğünü kontrol edin.
Proxy üzerinden bağlanamıyor	Proxy yapılandırması yanlış	Proxy URL ve port bilgisini kontrol edin.
Kaydedilmiyor	Test başarısız	Test başarılı olmadan bağlantı kaydedilmez.

12. Sonraki Adım

REST API veri kaynağı Port modülünde oluşturulduktan sonra süreç Compass, Cartography, Horizon ve Atlas adımlarıyla devam eder.

flowchart LR
    A["Port<br/>REST API Veri Kaynağı"] --> B["Compass<br/>HTTP Sorgusu"]
    B --> C["Cartography<br/>Chart / KPI"]
    C --> D["Horizon<br/>Sayfa / Board Hazırlama"]
    D --> E["Atlas<br/>Dashboard Görünümü"]

Dynamic Paths

Compass'ta REST API sorguları yazarken Base URL üzerine spesifik path eklenebilir (örn. /api/v1/orders?status=active). Böylece tek bir Base URL veri kaynağından farklı endpoint'lere birden fazla sorgu oluşturulabilir.

Özet

REST API veri kaynağı ekleme süreci:

Port modülüne girilir.
Add New Data Sources butonuna tıklanır.
Veri kaynağı tipi olarak RestAPI seçilir (Web Services & Files bölümü).
Display Info alanları doldurulur.
Essential Connection bölümünde Base URL ve Global Headers girilir.
Client Options ayarları yapılandırılır (Timeout, Retries, Proxy, SSL Verify).
Target Folder seçilir.
Test & Save ile bağlantı test edilir ve kaydedilir.
Veri kaynağı Port listesinde kontrol edilir.
Compass modülünde HTTP sorgusu oluşturulur.