Başlangıç
Robot API Dokümantasyonu
Saha Robotics Robot API dokümantasyonuna hoş geldiniz. Bu RESTful API ile servis robotlarını kendi yazılımınızdan kontrol edebilir, yönetebilir ve izleyebilirsiniz. İster tabletten sipariş sistemi, ister merkezi bir kontrol paneli geliştirin, ister robotları mevcut altyapınıza entegre edin; ihtiyacınız olan her şey bu API'de.
Robot API'ye Bağlanma
İstekler robota Saha Robotics Robot Ağ Geçidi (Robot Gateway) üzerinden ulaşır. Ağ geçidi API anahtarınızı doğrular ve isteği URL'de belirtilen robota iletir.
Temel URL
https://robots.saharobotik.com/api/v1/{robotId}/robot{robotId} yerine istek göndereceğiniz robotun ID'sini yazın. API sayfalarında bunu sunucu seçicisine bir kez girdiğinizde tüm örnekler ve istekler bu ID'yi kullanır. Bu dokümandaki tüm uç nokta yolları bu adresin sonuna eklenir. Örneğin robotun güncel durumunu almak için:
curl -H "x-api-key: YOUR_API_KEY" \
https://robots.saharobotik.com/api/v1/YOUR_ROBOT_ID/robot/statusTest (staging) ortamının ağ geçidi adresi: https://robots.staging.saharobotik.com/api/v1/{robotId}/robot. Sunucu listesindeki Robotun yerel sunucusu (http://localhost:7242/api/v1) ise aynı API'nin robotun kendi üzerindeki adresidir.
Kimlik Doğrulama
API anahtarınızı her istekte x-api-key başlığıyla gönderin. Anahtar, robotun projesinde Robot Gateway Client rolü tanımlı bir API istemcisine ait olmalıdır.
Robotlarınızı Listeleme
GET https://robots.saharobotik.com/api/v1/robots, API anahtarınızla erişebileceğiniz robotları ve temel URL'de kullanacağınız robot_id değerlerini döndürür. İstek ve yanıtın ayrıntıları için Ağ Geçidi API sayfasına bakın.
curl -H "x-api-key: YOUR_API_KEY" https://robots.saharobotik.com/api/v1/robotsAğ Geçidi Hataları
Robottan gelen yanıtlar olduğu gibi iletilir. Ağ geçidinin kendi döndürdüğü hatalar aşağıdadır; yanıt gövdesi statusCode ve message alanlarını içeren bir JSON'dur:
| Durum Kodu | Mesaj | Açıklama |
|---|---|---|
| 400 | Invalid robot id | Robot ID'si geçersiz: 2–32 karakter olmalı ve yalnızca harf, rakam, _ veya - içermeli |
| 401 | Unauthorized request | x-api-key başlığı eksik veya anahtar geçersiz |
| 403 | Forbidden | API istemcisinin robotun projesinde Robot Gateway Client rolü yok |
| 404 | Robot not found | Bu ID'ye sahip aktif bir robot yok |
| 404 | Unknown service | URL'de robot ID'sinden sonraki bölüm robot değil |
| 413 | İstek gövdesi 10 MiB'tan büyük | |
| 429 | Robot rate limit exceeded | İçinde bulunulan dakikada bu robota izin verilenden fazla istek gönderildi. Sınır robot başına uygulanır; bu robota istek gönderen tüm istemcilerin istekleri birlikte sayılır |
| 502 | Robot unreachable | Ağ geçidi robottan yanıt alamadı |
| 503 | Robot is not enrolled in the overlay | Robot henüz ağ geçidinin ağına kayıtlı değil |
Hızlı Başlangıç
Robot API işlevlerine göre bölümlere ayrılmıştır. Başlamak için aşağıdan bir bölüm seçin:
Robot Durumu
Robotun bataryasını, sensörlerini, donanımını ve çalışma durumunu izleyin
Navigasyon
Robotun hareketini kontrol edin, hedef nokta belirleyin ve konumunu anlık takip edin
Haritalama
Mekânların haritasını çıkarın, haritaları yönetin ve haritalar arasında geçiş yapın
Hedefler
Masa, istasyon gibi isimli konumları tanımlayın ve yönetin
Dolaşım
Birden fazla ara noktadan oluşan dolaşım rotaları oluşturun
Görevler
Görev atayın ve görevlerin ilerleyişini takip edin
Profil ve Mod
Robotun davranışını, hızını ve çalışma modlarını ayarlayın
Kullanıcı Arayüzü
Robotun ekranını, konuşmasını ve kullanıcı etkileşimlerini yönetin
Katman
Harita katmanlarını ve haritada gösterilen verileri yönetin
Sık Kullanılan Senaryolar
Robot Durumunu İzleme
Görev atamadan önce Robot Durumu API ile robotun hazır olup olmadığını kontrol edin. Batarya seviyesini, acil stop durumunu ve sensörlerin durumunu izleyin.
Robotu Hareket Ettirme
Navigasyon API ile robotu belirli konumlara gönderin. Doğrudan koordinat gönderebilir veya önceden tanımlı hedefleri kullanabilirsiniz.
Çalışma Alanını Hazırlama
- Haritalama API ile harita oluşturun
- Hedefler API ile konumları tanımlayın
- Dolaşım API ile dolaşım rotaları oluşturun
Görev Atama
Görev API ile robota görev gönderin. Her görev bir hedef konumdan ve bir görev türünden (masa servisi, teslimat gibi) oluşur.
Davranışı Özelleştirme
Profil ve Mod API ile robotun çalışma şeklini ayarlayın. Yoğun saatlerde hızı değiştirin veya asansör modu gibi özellikleri etkinleştirin.
Müşteri Etkileşimi
Müşteri deneyimini iyileştirmek için Kullanıcı Arayüzü API ile robotun ekranını ve konuşmasını yönetin.
Uygulamalı Örnekler
Sık yapılan işlemler için adım adım anlatımları Rehberler bölümünde bulabilirsiniz:
- Hedefe Git ve Konuş - Robotu bir konuma gönderin ve anons yaptırın
- Dolaşımı Başlat - Bir dolaşım rotası başlatın