Entegrasyonlar (API)
Organizasyon › Entegrasyonlar sayfası dış sistemleri API ile kommuns'a bağlar: envanteri ve iş emirlerini eşitleyen bir ERP, alarm verdiğinde geri bildirim açan bir bina otomasyonu (BMS) ya da sensör, bir raporlama aracı veya bir servis firmasının kendi yazılımı. Her entegrasyonun kendi kimlik bilgileri vardır ve organizasyonunuzun verisinde, verdiğiniz yetkiler içinde çalışır.
Entegrasyon yetkisini nereden alır?
Entegrasyon, organizasyonunuzda bir çalışan gibi bir kimliktir; ayrı bir "API kullanıcısı" yoktur:
- Oluşturulurken organizasyona bir Organizasyon yetkisi tanımıyla (ör. Organizasyon Çalışanı) eklenir.
- Lokasyonlardaki, sistemlerdeki ve ekipmanlardaki yetkisini bir kişininki gibi Yetkili Ata ile alır (bkz. Yetki modeli). Yetkili Ata'da ENTEGRASYON olarak listelenir; Danışman seçeneği yoktur. Lokasyonun Yetkililer sekmesinde Entegrasyonlar altında görünür.
- Kapsamlar yetkiyi ayrıca daraltır. Etkin yetki, kapsamlarla hesaplanmış yetkinin birlikte izin verdiğidir:
inventory:readkapsamı olan ama yalnızca tek bir lokasyona atanmış bir entegrasyon yalnızca o lokasyonu okur. people:readad, e-posta ve telefon bilgilerini verir — kişisel veridir. Yalnızca dış sistem gerçekten ihtiyaç duyuyorsa seçin.
Entegrasyonlar sayfası
- Mavi şerit paketinizin sınırlarını (dakikadaki istek sayısı, en fazla entegrasyon), dış sisteme vereceğiniz API adresini ve API belgeleri bağlantısını gösterir. Paketiniz API içermiyorsa şerit bunu söyler: yeni entegrasyon ekleyemezsiniz, var olanlar da API içeren bir pakete geçene kadar çalışmaz (Paketler ve ödeme).
- Her satırda entegrasyonun yetki tanımı, sırrının son karakterleriyle İstemci kimliği, kapsamları, son kullanımı ve bugünkü API çağrı sayısı ile Aktif olup olmadığı görünür.
Entegrasyon oluşturma
- Yeni entegrasyon'a tıklayın.
- Bir Ad girin — entegrasyon listelerde ve log kayıtlarında bu adla görünür (ör. ERP bağlantısı (SAP)) — ve isterseniz bir açıklama.
- Kapsamları (1) ve Organizasyon yetkisini (2) seçip Kaydet'e tıklayın.
Ardından kommuns İstemci kimliğini ve İstemci sırrını gösterir — sırrı yalnızca bu kez:
kommuns sırrı saklamaz, bu yüzden yeniden gösteremez; kaybolursa yenileyin (aşağıda). Dış sistem bu bilgilerle bir saatlik erişim token'ı alır (OAuth 2 "client credentials") ve API'yi çağırır — teknik ayrıntılar geliştirici belgelerinde. Son olarak entegrasyona çalışacağı lokasyonlardaki yetkisini Yetkili Ata ile verin.
Düzenleme, sırrı yenileme, pasifleştirme, silme
- Düzenle (kalem): ad, açıklama ve kapsamlar. Oluştururken seçilen organizasyon yetkisi burada değişmez; envanterdeki yetkileri Yetkili Ata ile yönetilir.
- Sırrı yenile: eski sır ve onunla alınmış token'lar hemen çalışmaz; yeni sırrı dış sisteme girin.
- Pasifleştir / Aktifleştir: pasif entegrasyon token alamaz, token'ları çalışmaz; hiçbir şey silinmez.
- Sil: entegrasyonu, kimliğini ve bütün atamalarını kaldırır. Geri alınamaz.
Kapsamları daraltmak da entegrasyonun mevcut token'larını sonlandırır. kommuns kapattı etiketi olan bir entegrasyonu kommuns devre dışı bırakmıştır (ör. kötüye kullanım ya da sızan bir sır nedeniyle); yeniden açılması için destekle iletişime geçin.
Webhook'lar: dış sistemi kommuns haberdar etsin
Dış sistem "bir şey değişti mi?" diye kommuns'a tekrar tekrar sormak yerine haberdar edilebilir: bir olay olunca kommuns belirlediğiniz adreslere imzalı bir istek gönderir. Adresleri ⋮ › Webhook'lar ile açın.
- Yeni webhook: adres (
https://ile başlamalı ve internetten erişilebilir olmalı) ve alacağı olaylar: iş emri oluşturuldu, güncellendi, durumu değişti, tamamlandı, denetime gönderildi, iptal edildi, yetkilileri değişti; geri bildirim oluşturuldu ya da çözüldü. Bir entegrasyonun en çok 5 adresi olabilir. - İmza sırrı, istemci sırrı gibi bir kez gösterilir; alıcı sistem isteğin gerçekten kommuns'tan geldiğini onunla doğrular (bkz. geliştirici belgeleri).
- Entegrasyon yalnızca okuyabildiği kayıtların olaylarını alır (kapsamlar ve yetkiler).
- ⋮ › Test gönder bir deneme olayı (ping) gönderir ve sonucu satırda gösterir.
- Başarısız bir teslim yaklaşık iki gün boyunca yeniden denenir. Üç gündür hiçbir teslimi başarılı olmayan adres pasifleştirilir ve nedeni altında yazar; alıcıyı düzeltip adresi yeniden Aktifleştirin.
- ⋮ › Teslimler son teslimleri (30 gün saklanır) durumu, deneme sayısı ve yanıt koduyla listeler; Yeniden gönder bir teslimi tekrar gönderir.
Dış sistem numarası
ERP ve bakım sistemleri envantere kendi numaralarını verir (ör. SAP'deki teknik yer numarası). Bu numarayı lokasyonun, sistemin ya da ekipmanın detay panelindeki Dış Sistem Numarası alanına girin (panel, resmin yanındaki okla açılır; alan etiketlerin altındadır, ⓘ ikonu ne olduğunu açıklar): kaleme tıklayın, numarayı yazın (1) ve Kaydet'e tıklayın. Entegrasyonlar envanteri API'de bu numarayla bulur.
Numara organizasyon içinde tekil olmalıdır. Envanteri düzenleme yetkisi olanlar değiştirebilir.
Entegrasyonların yaptıkları uygulamada nasıl görünür?
Bir entegrasyonun API ile yaptıkları adının sonuna "(API)" eklenerek gösterilir — ör. ERP bağlantısı (SAP) (API): oluşturduğu iş emirleri ve geri bildirimler, iş emrinin Güncellemeler'indeki değişiklikleri ve log kayıtları. Bir entegrasyon iş emrinin yetkilisi de olabilir ve iş emrini tamamlayabilir.
Geliştiriciler için
Kimlik doğrulama, kapsamlar, uç noktalar, webhook imzaları ve kod örnekleri geliştirici belgelerindedir; uç noktaların tam başvuru belgesine oradan ve Entegrasyonlar sayfasındaki API belgeleri bağlantısından ulaşılır.