REST API Referansı | Proxus Dokümantasyon

Proxus IIoT platformu; cihazlar, gateway'ler, kurallar, uyarılar ve telemetri dahil platform varlıklarına erişim için kimliği doğrulanmış bir REST yüzeyi sunar. Varlık erişimi için OData, kimlik doğrulama için JWT bearer kullanılır. Güncel varlık ve alan sözleşmesi OData metadata belgesidir; ayrıca kullanıcı izinleri okunabilecek veya değiştirilebilecek içeriği kısıtlayabilir. Kimlik doğrulama yöntemleri hakkında daha fazla bilgi için Kimlik Doğrulama Sağlayıcıları sayfasına bakın.

Kimlik Doğrulama

API, JWT Bearer Token kimlik doğrulaması kullanır. Bir token almak için:

Kimlik bilgilerinizle /api/Authentication/Authenticate uç noktasına bir POST isteği gönderin.
Dönen token'ı sonraki isteklerin Authorization başlığına ekleyin.

API Kimlik Doğrulama Akışı

code

İstemci Uygulama

Kodunuz

key

Kimlik Doğrula

/api/Authentication

api

OData API

Varlık İşlemleri

dashboard

Platform

Cihazlar / Kurallar / Uyarılar

Kimlik doğrulama uç noktası, JWT token'ını düz bir dize (JSON nesnesi değil) olarak döndürür.

# Token al
curl -X POST https://<your-server-url>/api/Authentication/Authenticate \
  -H "Content-Type: application/json" \
  -d '{"userName": "<username>", "password": "<password>"}'

# Sonraki isteklerde token kullan
curl -X GET https://<your-server-url>/api/odata/Device \
  -H "Authorization: Bearer <jwt_token>"

OData Uç Noktaları

Proxus API'si, mevcut sunucunun yayınladığı varlık setleri için OData kullanır. Temel URL: https://<your-server-url>/api/odata. Güncel sözleşmeyi GET /api/odata/$metadata ile okuyun; her platform nesnesinin yayınlandığını varsaymak yerine kimliği doğrulanmış kullanıcının erişebildiği varlık setlerini ve alanları kullanın.

Temel Varlıklar

Varlık	Metotlar	Açıklama
`Device`	Canlı sözleşme ve kullanıcı izinlerinin izin verdiği işlemler	Endüstriyel cihazları ve konfigürasyonlarını yönetin.
`Gateway`	Canlı sözleşme ve kullanıcı izinlerinin izin verdiği işlemler	Edge computing gateway'lerini yönetin.
`Alert`	Canlı sözleşme ve kullanıcı izinlerinin izin verdiği işlemler	Sistem uyarılarına erişin ve yönetin.
`Rule`	Canlı sözleşme ve kullanıcı izinlerinin izin verdiği işlemler	Kural motoru kurallarını yapılandırın ve yönetin.
`RuleAction`	Canlı sözleşme ve kullanıcı izinlerinin izin verdiği işlemler	Kurallar için aksiyonlar tanımlayın.
`TargetProfile`	Canlı sözleşme ve kullanıcı izinlerinin izin verdiği işlemler	Hedef sistem profillerini yapılandırın (MSSQL, PostgreSQL, ClickHouse, vb.).
`DeviceProfile`	Canlı sözleşme ve kullanıcı izinlerinin izin verdiği işlemler	Cihaz iletişim profillerini yönetin.
`NotificationChannel`	Canlı sözleşme ve kullanıcı izinlerinin izin verdiği işlemler	Bildirim kanallarını yapılandırın.

Not: Telemetri (DeviceRawData) OData üzerinden sunulmaz. SELECT sorguları için Telemetri API'sini kullanın. Telemetri depolama sistemi hakkında daha fazla bilgi için ClickHouse Entegrasyonu sayfasına bakın.

Desteklenen OData İşlemleri

Varlık uç noktaları, sunucu tarafından etkinleştirilen ve mevcut istek için izin verilen OData sorgu seçeneklerini destekler:

$filter: Sonuçları filtrele (örn., /api/odata/Device?$filter=Name eq 'MyDevice')
$select: Belirli alanları seç (örn., /api/odata/Device?$select=Name,Status)
$top & $skip: Sayfalama (örn., /api/odata/Device?$top=10&$skip=20)
$orderby: Sonuçları sırala (örn., /api/odata/Device?$orderby=Name)
$count: Toplam sayıyı al (örn., /api/odata/Device/$count)

Sunucu tek bir OData sorgusunun sayfa boyutunu 100 kayıtla sınırlar. Açık bir $select, sınırlı bir $top ve sayfalama kullanın. Başarılı bir okuma, aynı kimliğin varlık oluşturma, güncelleme veya silme yetkisi olduğu anlamına gelmez.

Telemetri API

ClickHouse'ta saklanan telemetri verilerine doğrudan erişim için özel telemetri uç noktasını kullanın:

Telemetri Sorgusu Çalıştır

Uç Nokta: POST /api/Telemetry/execute
Açıklama: ClickHouse telemetri verilerine karşı güvenli SELECT sorguları çalıştırın

İstek Gövdesi:

{
  "query": "SELECT * FROM DeviceRawData WHERE Time > now() - INTERVAL 1 DAY LIMIT 100"
}

Sorgu Parametreleri:
- maxRows: Döndürülecek maksimum satır sayısı (varsayılan: 10000, maks: 50000)

Bu uç nokta SQL enjeksiyon koruması içerir ve sorgu sınırlarını (sadece SELECT) uygular.

Yanıt Formatı: ClickHouse JSONEachRow (NDJSON) döndürür. İstemciler yanıt gövdesini metin olarak okumalı veya satır satır akıtmalıdır. Veri yapısı ve Birleşik İsim Alanı ile ilişkisi hakkında daha fazla bilgi için Birleşik İsim Alanı sayfasına bakın.

Swagger Dokümantasyonu

Tüm mevcut uç noktaların ve şemaların etkileşimli bir gezgini için yerel kurulumunuzdaki Swagger UI'a erişin:

http://<your-server-url>/swagger

Canlı demo, üretilen OpenAPI 3 belgesine karşı doğrulandı. Ekran güncel API kataloğunu, JWT bearer Authorize kontrolünü ve çalışan sunucunun yayınladığı varlık işlemlerini gösterir. Uç nokta listesi sunucu sürümü ve kurulu modüllerle değişebileceği için nihai sözleşme olarak üretilen belgeyi kullanın.

Swagger UI şunları sağlar:

Etkileşimli uç nokta testi
İstek/yanıt şema tanımları
Çalışan sözleşmenin sağladığı yerlerde örneklerle birlikte üretilen istek ve yanıt şemaları
Authorization: Bearer <token> header'ı ile JWT bearer kimlik doğrulama desteği

Kod Örnekleri

Farklı programlama dilleri kullanarak Proxus API ile nasıl etkileşime girileceğine dair örnekler aşağıdadır:

Kimlik Doğrulama

# JWT token al
curl -X POST https://<your-server-url>/api/Authentication/Authenticate \
  -H "Content-Type: application/json" \
  -d '{"userName": "<username>", "password": "<password>"}'

Cihazları Getir

# Tüm cihazları listele
curl -X GET https://<your-server-url>/api/odata/Device \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json"

Gateway'leri Getir

# Tüm gateway'leri listele
curl -X GET https://<your-server-url>/api/odata/Gateway \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json"

Cihaz Oluştur

# Yeni cihaz oluştur
curl -X POST https://<your-server-url>/api/odata/Device \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceName": "Ornek Cihaz",
    "enabled": true,
    "status": "Active"
  }'

Gateway Oluştur

# Yeni gateway oluştur
curl -X POST https://<your-server-url>/api/odata/Gateway \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ornek Gateway",
    "status": "Active"
  }'

Telemetri Verisi Sorgula

# Telemetri sorgusu çalıştır
curl -X POST https://<your-server-url>/api/Telemetry/execute \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM DeviceRawData WHERE Time > now() - INTERVAL 1 DAY LIMIT 100"
  }'

Kimlik Doğrulama

// JWT token al
const authResponse = await fetch('https://<your-server-url>/api/Authentication/Authenticate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userName: '<username>',
    password: '<password>'
  })
});

const token = (await authResponse.text()).replace(/"/g, "");

Cihazları Getir

// Tüm cihazları listele
const devicesResponse = await fetch('https://<your-server-url>/api/odata/Device', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

const devices = await devicesResponse.json();

Gateway'leri Getir

// Tüm gateway'leri listele
const gatewaysResponse = await fetch('https://<your-server-url>/api/odata/Gateway', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

const gateways = await gatewaysResponse.json();

Cihaz Oluştur

// Yeni cihaz oluştur
const createResponse = await fetch('https://<your-server-url>/api/odata/Device', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    deviceName: "Example Device",
    enabled: true,
    status: "Active"
  })
});

Gateway Oluştur

// Yeni gateway oluştur
const createGatewayResponse = await fetch('https://<your-server-url>/api/odata/Gateway', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Example Gateway",
    status: "Active"
  })
});

Telemetri Verisi Sorgula

// Telemetri sorgusu çalıştır
const telemetryResponse = await fetch('https://<your-server-url>/api/Telemetry/execute', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: "SELECT * FROM DeviceRawData WHERE Time > now() - INTERVAL 1 DAY LIMIT 100"
  })
});

const telemetryText = await telemetryResponse.text(); // NDJSON (JSONEachRow)

Kimlik Doğrulama

import requests
import json

# JWT token al
auth_url = "https://<your-server-url>/api/Authentication/Authenticate"
auth_payload = {
    "userName": "<username>",
    "password": "<password>"
}

auth_response = requests.post(auth_url, json=auth_payload)
token = auth_response.text.strip('"')

Cihazları Getir

# Tüm cihazları listele
devices_url = "https://<your-server-url>/api/odata/Device"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

devices_response = requests.get(devices_url, headers=headers)
devices = devices_response.json()

Gateway'leri Getir

# Tüm gateway'leri listele
gateways_url = "https://<your-server-url>/api/odata/Gateway"
gateways_response = requests.get(gateways_url, headers=headers)
gateways = gateways_response.json()

Cihaz Oluştur

# Yeni cihaz oluştur
create_url = "https://<your-server-url>/api/odata/Device"
device_payload = {
    "deviceName": "Example Device",
    "enabled": True,
    "status": "Active"
}

create_response = requests.post(create_url, json=device_payload, headers=headers)

Gateway Oluştur

# Yeni gateway oluştur
gateway_url = "https://<your-server-url>/api/odata/Gateway"
gateway_payload = {
    "name": "Example Gateway",
    "status": "Active"
}

gateway_response = requests.post(gateway_url, json=gateway_payload, headers=headers)

Telemetri Verisi Sorgula

# Telemetri sorgusu çalıştır
telemetry_url = "https://<your-server-url>/api/Telemetry/execute"
telemetry_payload = {
    "query": "SELECT * FROM DeviceRawData WHERE Time > now() - INTERVAL 1 DAY LIMIT 100"
}

telemetry_response = requests.post(telemetry_url, json=telemetry_payload, headers=headers)
telemetry_data = telemetry_response.text  # NDJSON (JSONEachRow)

Kimlik Doğrulama

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

// JWT token al
using var client = new HttpClient();
var authPayload = new {
    userName = "<username>",
    password = "<password>"
};

var json = JsonConvert.SerializeObject(authPayload);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var authResponse = await client.PostAsync("https://<your-server-url>/api/Authentication/Authenticate", content);

var authToken = await authResponse.Content.ReadAsStringAsync();
string token = authToken.Trim().Trim('"');

Cihazları Getir

// Tüm cihazları listele
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);

var devicesResponse = await client.GetAsync("https://<your-server-url>/api/odata/Device");
var devicesJson = await devicesResponse.Content.ReadAsStringAsync();
dynamic devices = JsonConvert.DeserializeObject(devicesJson);

Gateway'leri Getir

// Tüm gateway'leri listele
var gatewaysResponse = await client.GetAsync("https://<your-server-url>/api/odata/Gateway");
var gatewaysJson = await gatewaysResponse.Content.ReadAsStringAsync();
dynamic gateways = JsonConvert.DeserializeObject(gatewaysJson);

Cihaz Oluştur

// Yeni cihaz oluştur
var devicePayload = new {
    deviceName = "Example Device",
    enabled = true,
    status = "Active"
};

var deviceJson = JsonConvert.SerializeObject(devicePayload);
var deviceContent = new StringContent(deviceJson, Encoding.UTF8, "application/json");

var createResponse = await client.PostAsync("https://<your-server-url>/api/odata/Device", deviceContent);

Gateway Oluştur

// Yeni gateway oluştur
var gatewayPayload = new {
    name = "Example Gateway",
    status = "Active"
};

var gatewayJson = JsonConvert.SerializeObject(gatewayPayload);
var gatewayContent = new StringContent(gatewayJson, Encoding.UTF8, "application/json");

var gatewayResponse = await client.PostAsync("https://<your-server-url>/api/odata/Gateway", gatewayContent);

Telemetri Verisi Sorgula

// Telemetri sorgusu çalıştır
var telemetryPayload = new {
    query = "SELECT * FROM DeviceRawData WHERE Time > now() - INTERVAL 1 DAY LIMIT 100"
};

var telemetryJson = JsonConvert.SerializeObject(telemetryPayload);
var telemetryContent = new StringContent(telemetryJson, Encoding.UTF8, "application/json");

var telemetryResponse = await client.PostAsync("https://<your-server-url>/api/Telemetry/execute", telemetryContent);
var telemetryData = await telemetryResponse.Content.ReadAsStringAsync();

lightbulb

Konfigürasyon

JWT token imzalama anahtarlarını, süresini ve issuer/audience ayarlarını Proxus-config.toml dosyasındaki JWT & WebAPI bölümünden yapılandırın.