REST API

Bu kılavuzu tamamladığınızda betiğiniz merkez sunucuda oturum açar, bir erişim anahtarı alır ve cihazları bağlı oldukları Edge Gateway'le birlikte okur. Aynı API ile nesne oluşturabilir, değiştirebilir ve silebilirsiniz. Bu işlemlerin sınırını, oturum açan kullanıcının hakları belirler.

Başlamadan önce

Şunlar gereklidir:

• Merkez sunucunun adresi. Yerel kurulumda bu adres örneğin http://localhost:8080 olur. API, merkez sunucu ekranlarıyla aynı porttan çalışır.
• Entegrasyona ayrılmış bir Proxus kullanıcısı. API'nin neyi okuyup neyi değiştirebileceğini, ekranlarda olduğu gibi bu kullanıcının rolü belirler. Ayrıntılar için Kullanıcılar ve roller sayfasına bakın.
• İzleyeceğiniz örneğe göre curl, requests paketi kurulu Python 3 veya .NET.

API uç noktaları

Varlık kümelerinden bazıları şunlardır: Device, DeviceProfile, DeviceProfileRegister (veri noktaları), Gateway, TargetProfile (veri hedefleri), NotificationChannel, Rule, RuleAction, Flow (işlem akışları), Function, Alert, Log, ScheduledDelivery, TrendView ve UnsTopicPermission. Listenin tamamı her zaman /api/odata/ adresinde bulunur.

Adım 1: Erişim anahtarı alın

Kullanıcı adını ve parolayı JSON olarak gönderin. Yanıtta yalnızca erişim anahtarı düz metin olarak döner.

curl -X POST http://localhost:8080/api/Authentication/Authenticate \
  -H "Content-Type: application/json" \
  -d '{"userName":"Admin","password":""}'

Sonraki tüm çağrılarda erişim anahtarını Authorization başlığına ekleyin:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

• Kullanıcı adı veya parola yanlışsa API 401 kodunu ve User name or password is incorrect. metnini döndürür.
• Geçerli bir erişim anahtarı içermeyen /api/... çağrıları 401, kullanıcının yetkisi olmayan çağrılar 403 kodunu alır.
• Erişim anahtarı, TokenExpireTime ile belirlenen süre boyunca geçerlidir. Ürünle gelen yapılandırmada bu süre bir yıldır. Bir çağrı 401 döndürdüğünde yeni bir anahtar alın.

Adım 2: Nesneleri okuyun

TOKEN=$(curl -s -X POST http://localhost:8080/api/Authentication/Authenticate \
  -H "Content-Type: application/json" -d '{"userName":"Admin","password":""}')

curl -s -G http://localhost:8080/api/odata/Device \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "\$filter=startswith(DeviceName,'LYS')" \
  --data-urlencode "\$select=Oid,DeviceName,Enabled" \
  --data-urlencode "\$count=true" \
  --data-urlencode "\$top=3"

Yanıt şöyle görünür:

{
  "@odata.context": "http://localhost:8080/api/odata/$metadata#Device(Oid,DeviceName,Enabled)",
  "@odata.count": 14,
  "value": [
    { "Oid": 66, "DeviceName": "LYS_MILL_01", "Enabled": true },
    { "Oid": 67, "DeviceName": "LYS_LINE1_PLC", "Enabled": true },
    { "Oid": 69, "DeviceName": "LYS_PACKER_04", "Enabled": true }
  ]
}

Standart OData sorgu seçeneklerinin tümü kullanılabilir:

Tek bir nesneyi okumak için anahtarını kullanın: GET /api/odata/Device(69). LatestValues bağlantısını genişletirseniz cihazın son değerleri de yanıta eklenir:

curl -s -G "http://localhost:8080/api/odata/Device(69)" -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "\$select=DeviceName" --data-urlencode "\$expand=LatestValues"

Her son değer Key, Value, DataType, Quality ve LastUpdate alanlarını içerir.

Adım 3: Koddan kullanın

import requests

HUB = "http://localhost:8080"

# 1. Oturum açın ve erişim anahtarı alın
response = requests.post(
    f"{HUB}/api/Authentication/Authenticate",
    json={"userName": "Admin", "password": ""},
    timeout=30,
)
response.raise_for_status()
token = response.text.strip()
headers = {"Authorization": f"Bearer {token}"}

# 2. Bir tesisin cihazlarını Edge Gateway'leriyle birlikte okuyun
response = requests.get(
    f"{HUB}/api/odata/Device",
    params={
        "$filter": "Site eq 'Lyon Foods Plant'",
        "$select": "Oid,DeviceName,Status",
        "$expand": "Gateway($select=Name)",
        "$orderby": "DeviceName",
    },
    headers=headers,
    timeout=30,
)
response.raise_for_status()
for device in response.json()["value"]:
    print(device["Oid"], device["DeviceName"], device["Status"], device["Gateway"]["Name"])

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

var hub = new HttpClient { BaseAddress = new Uri("http://localhost:8080/") };

// 1. Oturum açın ve erişim anahtarı alın
var login = await hub.PostAsJsonAsync("api/Authentication/Authenticate",
    new { userName = "Admin", password = "" });
login.EnsureSuccessStatusCode();
var token = await login.Content.ReadAsStringAsync();
hub.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

// 2. Edge Gateway'leri okuyun
using var gateways = JsonDocument.Parse(
    await hub.GetStringAsync("api/odata/Gateway?$select=Oid,Name"));
foreach (var gateway in gateways.RootElement.GetProperty("value").EnumerateArray())
    Console.WriteLine($"{gateway.GetProperty("Oid")} {gateway.GetProperty("Name")}");

Oluşturma, değiştirme ve silme

Varlık kümeleri standart OData yöntemleriyle POST (oluşturma), PATCH (bazı alanları değiştirme), PUT (nesnenin tamamını değiştirme) ve DELETE çağrılarını da kabul eder. Örneğin bir cihazı devre dışı bırakmak için:

curl -X PATCH "http://localhost:8080/api/odata/Device(69)" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"Enabled": false}'

Hangi işlemlere izin verildiğini kullanıcının rolü belirler. Rolün izin vermediği bir değişiklik, merkez sunucu ekranlarında olduğu gibi API'de de reddedilir.

Sonraki adımlar

• Telemetry API: saklanan veri noktası değerlerini SQL ile sorgulayın.
• MQTT ve UNS konuları: değerleri okundukları anda canlı alın.
• Ağ portları ve uç noktalar: merkez sunucunun ve Edge Gateway'lerin dinlediği tüm adresler.