KPI API Entegrasyonu (Pull)
Hedef Kitle: Admin, Geliştirici
Sayfa Türü: Nasıl Yapılır + Referans
Plan Özelliği: kpi_api_integration (tenant'ınız için etkinleştirilmiş olmalı)
Genel Bakış
COS, dış API'lerden KPI ölçüm verilerini otomatik olarak belirli zamanlarda çekebilir. Bu pull entegrasyon modelidir — COS, tanımlanan aralıklarla API uç noktalarınızı çağırır ve elde edilen değerleri KPI ölçümü olarak yazar.
Nasıl Çalışır
Dış API ←──── COS (cron zamanlama) ────→ KPI Ölçüm Tablosu
(BI aracınız, HTTP GET/POST (otomatik doldurulur)
veri ambarınız, + auth header'ları
izleme sisteminiz) + JSONPath çıkarma
- Bir Entegrasyon Uç Noktası tanımlarsınız (base URL + auth bilgileri)
- Belirli KPI'ları API yanıt alanlarına bağlayan KPI Bağlantıları oluşturursunuz
- COS, API'yi cron zamanlamasına göre çağırır ve JSONPath ile değerleri çıkarır
- Çıkarılan değerler ilgili KPI'ya ölçüm olarak yazılır
Ön Koşullar
- Plan Özelliği: Tenant'ınız için
kpi_api_integrationetkinleştirilmiş olmalı - İzin: Kullanıcının
integration:manageiznine sahip olması gerekir (genellikle Admin veya Strateji Yöneticisi) - Dış API: Veri kaynağınız HTTP/HTTPS üzerinden erişilebilir olmalı
Adım 1: Entegrasyon Uç Noktası Oluşturma
Uç nokta, dış API bağlantı detaylarını tanımlar.
Yol: KPI Detay → Entegrasyon Paneli → Uç Noktaları Yönet
Gerekli Alanlar
| Alan | Açıklama | Örnek |
|---|---|---|
| Ad | Açıklayıcı isim | "BI Dashboard API" |
| Base URL | API temel URL'i | https://api.example.com/v1 |
| Auth Türü | Kimlik doğrulama yöntemi | Bkz. Auth Türleri |
| Kimlik Bilgileri | Auth bilgileri (şifreli saklanır) | Auth türüne göre değişir |
Desteklenen Auth Türleri
| Auth Türü | Kimlik Bilgileri | Gönderilen Header |
|---|---|---|
| NONE | — | Auth header'ı yok |
| BEARER_TOKEN | { token: "..." } | Authorization: Bearer {token} |
| BASIC_AUTH | { username: "...", password: "..." } | Authorization: Basic {base64} |
| API_KEY_HEADER | { headerName: "X-API-Key", headerValue: "..." } | {headerName}: {headerValue} |
| API_KEY_QUERY | { queryName: "api_key", queryValue: "..." } | URL'ye ?{queryName}={queryValue} eklenir |
Adım 2: KPI Bağlantısı Oluşturma
Bağlantı, belirli bir KPI'yı yanıt eşleme kurallarıyla bir API uç noktasına bağlar.
Gerekli Alanlar
| Alan | Açıklama | Örnek |
|---|---|---|
| KPI | Ölçüm alacak KPI | (bağlamdan otomatik seçilir) |
| Uç Nokta | Çağrılacak entegrasyon uç noktası | "BI Dashboard API" |
| Path Eki | Base URL'ye eklenir | /metrics/revenue |
| Yanıt Eşleme | Değer çıkarmak için JSONPath ifadeleri | Aşağıya bakın |
| Cron İfadesi | Zamanlama (ör. saatlik, günlük) | 0 */6 * * * (her 6 saatte) |
Yanıt Eşleme (JSONPath)
Yanıt eşleme, COS'a API yanıtı JSON'ından sayısal değerlerin nasıl çıkarılacağını söyler.
| Alan | Açıklama | JSONPath Örneği |
|---|---|---|
actual | Zorunlu. Mevcut metrik değeri | $.value, $.data.metrics.current |
target | İsteğe bağlı. Hedef/ulaşılmak istenen değer | $.target, $.data.metrics.target |
forecast | İsteğe bağlı. Tahmin değeri | $.forecast |
statusNote | İsteğe bağlı. Metin notu | $.status |
Örnek API Yanıtı:
{
"metric": "revenue",
"value": 1250000,
"target": 1500000,
"unit": "USD"
}
Yanıt Eşleme:
{
"actual": "$.value",
"target": "$.target"
}
Yaygın Formatlar İçin JSONPath Desenleri
| API Formatı | actual için JSONPath |
|---|---|
Düz: { "value": 42 } | $.value |
İç içe: { "data": { "metrics": { "current": 42 } } } | $.data.metrics.current |
Dizi (son): { "series": [{ "value": 40 }, { "value": 42 }] } | $.series[-1:].value |
İsimli anahtar: { "kpis": { "revenue": { "actual": 42 } } } | $.kpis.revenue.actual |
Sayfalanmış: { "results": [{ "measurement": 42 }] } | $.results[0].measurement |
Adım 3: Test Et ve Aktifleştir
- Bağlantıyı oluşturduktan sonra doğrulamak için Test (Kuru Çalışma) düğmesine tıklayın:
- API erişilebilir mi
- Auth bilgileri geçerli mi
- JSONPath çıkarma beklenen değerleri döndürüyor mu
- Test sonucundaki çıkarılan değerleri inceleyin
- Onaylandıktan sonra bağlantı, tanımlanan cron zamanlamasına göre otomatik çalışacaktır
Çalışma Günlükleri
Her entegrasyon çalışması aşağıdaki bilgilerle bir log kaydı oluşturur:
- HTTP durum kodu
- Yanıt süresi
- Çıkarılan değerler
- Hata mesajı (başarısızsa)
- İstek/yanıt detayları (temizlenmiş)
Plan Özellik Limitleri
| Özellik Anahtarı | Açıklama | Varsayılan |
|---|---|---|
kpi_api_integration | Pull entegrasyonu etkinleştir/devre dışı bırak | Devre dışı |
max_api_integrations | Tenant başına maksimum bağlantı sayısı (-1 = sınırsız) | -1 |
min_cron_interval_minutes | İzin verilen minimum cron aralığı | 60 dk |
Mock API ile Test
COS, gerçek bir dış sisteme ihtiyaç duymadan entegrasyonları test etmek için yerleşik bir mock API sunar.
Konum: tools/mock-kpi-api/
cd tools/mock-kpi-api && npm install && npm start
# → http://localhost:4444
Mock API, 5 auth türünün tamamını ve çeşitli yanıt formatlarını destekler. Detaylar için Mock API Test Rehberi sayfasına bakın.
Desteklenen KPI Türleri
Pull entegrasyon, COS'taki tüm KPI türleriyle çalışır:
| KPI Varlık Türü | Kaynak Modül |
|---|---|
THEME_KPI | Stratejik Tema KPI'ları |
BSC_KPI | Balanced Scorecard KPI'ları |
ASIS_KPI | Mevcut Durum (As-Is) KPI'ları |
SWOT_KPI | SWOT Analizi KPI'ları |
PESTLE_KPI | PESTLE Analizi KPI'ları |
KPI_DEFINITION | KPI Kütüphanesi KPI'ları |
OKR_KEY_RESULT | OKR Key Result ölçümleri |
PRODUCT_SCORECARD_KPI | Ürün Skor Kartı KPI'ları |