REST API

Web uygulamasının yaptığı her şey Botream Server'ın REST API'si üzerinden geçer; bu nedenle kendi betiklerinizden ve sistemlerinizden çalıştırma başlatabilir, sonuçları okuyabilir ve kuyrukları yönetebilirsiniz. Bu sayfada nasıl oturum açacağınızı, API'yi nasıl çağıracağınızı ve tam başvuru belgesini nerede bulacağınızı görebilirsiniz.

#Temel adres

API, web uygulamasıyla aynı adres ve bağlantı noktasında /api altında yer alır; örneğin http://rpa-server:3000/api. İstekler ve yanıtlar JSON kullanır.

Uyarı: Erişim belirteçleri ve parolalar her istekte iletilir. İstemciler Botream'e güvenmediğiniz ağlar üzerinden erişiyorsa Botream'i HTTPS arkasında yayımlayın.

#Kimlik doğrulama

Oturum açma, yenileme, oturumu kapatma, sağlık denetimi (GET /api/system/health) ve API belgeleri dışında her uç nokta oturum açmış bir kullanıcı gerektirir. API çağrıları oturum açan kullanıcının izinleriyle çalışır; bu nedenle işi görecek en küçük role sahip, bu amaca ayrılmış bir kullanıcı oluşturun (bkz. Kullanıcılar ve roller).

#Oturum açma

Kullanıcı adını ve parolayı POST /api/auth/login adresine gönderin:

curl -X POST http://rpa-server:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"api-runner","password":"<password>"}'

Yanıt, kısa ömürlü bir erişim belirteci (access token), bu belirtecin saniye cinsinden ömrünü ve kullanıcıyı içerir:

{
  "accessToken": "eyJhbGciOi...",
  "expiresIn": 900,
  "user": { "id": 7, "username": "api-runner", "...": "..." }
}

Sunucu ayrıca bir yenileme belirteci (refresh token) değerini HttpOnly çerez olarak ayarlar (yol /api/auth). Yenileme belirteci hiçbir zaman yanıt gövdesinde yer almaz.

#Belirteç ömürleri

Erişim belirtecinin süresi dolduğunda ya yeniden oturum açın ya da yenileme çereziyle POST /api/auth/refresh çağrısını yapın. Her yenileme yeni bir erişim belirteci döndürür ve yenileme çerezini döndürür (yeniler): eski yenileme belirteci artık çalışmaz. Eski bir yenileme belirtecinin yeniden kullanılması hırsızlık olarak değerlendirilir ve oturumu sonlandırır. POST /api/auth/logout, çerezin arkasındaki oturumu iptal eder.

curl ile çerezi bir dosyada saklayın:

# Sign in and store the refresh cookie
curl -c botream.cookies -X POST http://rpa-server:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"api-runner","password":"<password>"}'

# Later: a new access token (and a new cookie)
curl -b botream.cookies -c botream.cookies -X POST http://rpa-server:3000/api/auth/refresh

Not: Oturum açma denemeleri hız sınırına tabidir (varsayılan olarak dakikada 10, LOGIN_RATE_LIMIT_PER_MINUTE). Bir betik her çağrı için oturum açmamalı; bir kez oturum açıp erişim belirtecini süresi dolana kadar yeniden kullanmalıdır.

#API'yi çağırma

Erişim belirtecini Authorization başlığında gönderin:

TOKEN="eyJhbGciOi..."
curl http://rpa-server:3000/api/auth/me -H "Authorization: Bearer $TOKEN"

PowerShell'de:

$login = Invoke-RestMethod -Method Post -Uri "http://rpa-server:3000/api/auth/login" `
  -ContentType "application/json" -Body '{"username":"api-runner","password":"<password>"}'
$headers = @{ Authorization = "Bearer $($login.accessToken)" }
Invoke-RestMethod -Uri "http://rpa-server:3000/api/agents" -Headers $headers

#Hatalar

Başarısız istekler bir HTTP durum kodu ve JSON gövdesiyle yanıt verir:

{ "statusCode": 409, "code": "CONFLICT", "message": "No agent is online" }

Doğrulama hataları, her geçersiz alanın path ve message değerlerini içeren bir issues listesi ekler. Tipik durum kodları: 400 geçersiz istek, 401 eksik veya süresi dolmuş belirteç, 403 kullanıcının rolü bu işleme izin vermiyor, 404 bulunamadı (kullanıcının göremeyeceği çalıştırmalar için de), 409 istek mevcut durumla çakışıyor.

#Etkileşimli belgeler (Swagger)

Sunucu, API'nin OpenAPI 3.1 açıklamasını bir Swagger UI ile birlikte yayımlayabilir:

Belgeler, üretim ortamı dışında varsayılan olarak açıktır. Kurulu bir Botream Server üretim modunda çalışır; bu nedenle belgeleri kendiniz açın: C:\ProgramData\Botream\Server\server.json dosyasına "API_DOCS": "true" ekleyin (veya hizmet için API_DOCS=true ortam değişkenini ayarlayın) ve BotreamServer hizmetini yeniden başlatın. Swagger UI'daki her rota, istek ve yanıt şemalarını ve onu çağırmaya izin verilen rolleri belirten bir Roles: satırını gösterir; bu satırı olmayan rotalar oturum açmış her kullanıcıyı kabul eder. Sayfadan çağrıları denemek için Authorize düğmesine tıklayın ve bir erişim belirteci yapıştırın.

#Uç nokta grupları

Tablo ana grupları özetler. Swagger UI tüm rotaları listeler.

Canlı güncellemeler (çalıştırma günlükleri, ajan durumu) REST API'nin parçası değildir: web uygulaması bunları Socket.io üzerinden /monitor ile alır.

#Çalıştırma başlatma

POST /api/executions, bir görevin geçerli genel sürümünü, yani zamanlamaların çalıştırdığı sürümün aynısını başlatır.

curl -X POST http://rpa-server:3000/api/executions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"taskId": 42, "agentId": 3, "inputs": {"customer": "ACME Ltd", "maxOrders": 5}}'

Yanıt (201 Created), id değeri de dahil olmak üzere yeni çalıştırmadır. Çalıştırmayı şu şekilde izleyin:

# Status and result
curl http://rpa-server:3000/api/executions/1234 -H "Authorization: Bearer $TOKEN"

# Log lines
curl http://rpa-server:3000/api/executions/1234/logs -H "Authorization: Bearer $TOKEN"

# Stop it
curl -X POST http://rpa-server:3000/api/executions/1234/cancel -H "Authorization: Bearer $TOKEN"

Durum kesinleşene kadar GET /api/executions/{id} uç noktasını yoklayın. Bir çalıştırma başarısız olduğunda GET /api/executions/{id}/failure; hata veren satırı, değişkenleri (gizli değerler maskelenmiş olarak) ve bir ekran görüntüsünün bulunup bulunmadığını (GET /api/executions/{id}/failure/screenshot) döndürür.

İpucu: Bir robotu her öğe için ayrı ayrı başlatmak yerine ona iş beslemek için POST /api/queues/{id}/items ile bir iş kuyruğuna öğe ekleyin ve kuyruğu bir zamanlamanın işlemesini sağlayın.

#Roller ve yetkiler

API çağrıları web uygulamasıyla aynı kurallara uyar: kullanıcının rolleri ve bu rollerin yetkileri belirleyicidir; rol değişikliği bir sonraki çağrıda geçerli olur (yeni belirteç gerekmez). Swagger UI'daki her rota, ona izin veren yetkileri listeler. Varsayılan rollerle:

GET /api/auth/me, oturum açmış kullanıcıyı roles (rol adları) ve permissions (neler yapabileceği) ile döndürür. Kullanıcılar roles: ["Runner", "Finance"] ile oluşturulur ve değiştirilir; eski role: "Runner" biçimi hâlâ kabul edilir ve yanıtlardaki role, roles listesinin ilkidir (kullanımdan kalkıyor).

See all runs yetkisi olmayan kullanıcılar yalnızca kendi başlattıkları çalıştırmaları görür; göremeyecekleri çalıştırmalar için API 404 yanıtı verir. Güvenlikle ilgili her çağrı (oturum açmalar, değişiklikler, kimlik bilgisi erişimi) denetim günlüğüne yazılır. Ayrıntılar için bkz. Kullanıcılar ve roller.