SysML v2
SysML v2 projelerinde API ve MCP
SysML v2 modellerini kişisel erişim belirteciyle betiklerden ve YZ araçlarından okuyun, arayın ve denetleyin; Holarch'ta inceleyip uyguladığınız değişiklikler önerin ve dalların değişiklik talepleri olduğu Systems Modeling API üzerinden okuyup commit edin.
Bu sayfada
Genel bakış
SysML v2 projeleri, LML projeleriyle aynı REST API, MCP uç noktası ve kişisel erişim belirteçleriyle çalışır. Betikler ve YZ araçları modeli öğeler ve SysML metni olarak okur, herhangi bir şeyi değiştirmeden önce metni denetler ve değişiklik önerir. Bir kişi öneriyi Holarch'ta inceleyip uygulayana kadar modelde hiçbir şey değişmez.
Üç giriş yolu:
- REST API: betikler ve panolar için
https://app.holarch.app/api/v1/projects/<project>/…. Öğeleri, gereksinimleri, tanılamaları ve SysML metnini okur ve bir öneriye değişiklik ekler. - MCP: Claude gibi YZ araçları için
https://app.holarch.app/mcp. SysML v2 araçları modeli okur, arar, denetler ve değişiklik önerir. - Systems Modeling API: diğer SysML v2 araçları için OMG Systems Modeling API biçimlerinde
https://app.holarch.app/api/v1/sysml/….maindalı canlı modeldir ve salt okunurdur; diğer her dal bir değişiklik talebidir ve commit'ler ona gider. Canlı model yalnızca bir onaylayıcı değişiklik talebini Holarch'ta uyguladığında değişir.
Belirteçler, kapsamlar, proje listeleri, kuruluş değiştirme, hız sınırları ve Claude'u bağlama LML projelerindekiyle aynıdır. Belirteç oluşturma ve bir YZ aracını bağlama için bkz. API ve MCP. Program Haritası çağrıları (GET /api/v1/program-map, GET /api/v1/projects/<project>/items/<item>/trace ve program_map ile trace_chain MCP araçları) SysML v2 projelerini ve öğelerini içerir.
Kavramlar
- Öğe: SysML v2 modelinin bir öğesi; örneğin bir part definition, bir port veya bir gereksinim. Her öğenin bir kimliği (UUID) vardır. Bir rota veya araç kimlik istediğinde
Vehicles::Car::powertraingibi bir nitelikli ad da çalışır. - Özet: listelerde bir öğenin kısa biçimi:
id,type(PartUsagegibi metasınıf),name,shortName,qualifiedNameveowner. - En üst düzey paket: başka bir öğenin içinde olmayan bir paket. Bir projenin SysML metni, her en üst düzey paket için bir metin ve paketlerin dışındaki öğeler için bir metinden oluşur.
- Tanılama: dil çekirdeğinin bulduğu bir sorun;
code,severity(errorveyawarning),elementId,elementveargsiçerir. Sözdizimi tanılamaları bir öğe yerinelinevecolverir. - Öneri: bir API istemcisinin veya YZ aracının inceleme için topladığı değişiklikler. Her belirteç ve proje için bir öneri açıktır. İstemci onu bir başlık ve özetle incelemeye gönderir.
- Sayfalı yanıtlar: listeler sayfalar hâlinde gelir (
limit,offset). Uzun SysML metni satır sayfaları hâlinde gelir (line,lines). Bir şeyi dışarıda bırakan yanıttruncated: truebelirtir.
Nasıl kullanılır
Bir betiğin veya YZ aracının modele ihtiyacı olduğunda API'yi kullanın: karşılayan veya doğrulayan öğesi olmayan gereksinimleri raporlamak, bir ekibin SysML metnini modele göre denetlemek veya bir YZ aracının daha sonra bir mühendisin incelediği model değişikliklerini taslak olarak hazırlamasını sağlamak için.
curl ile bir SysML v2 projesini okuma
- Hesap ayarları → API belirteçleri altında bir belirteç oluşturun (bkz. API ve MCP).
- Projelerinizi listeleyin:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
SysML v2 projelerinde "language": "sysml2" bulunur.
- Model özetini alın:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects/<project>/model
Metasınıf başına öğe sayılarını, en üst düzey paketleri ve hata ile uyarı sayısını görürsünüz.
- Öğeleri bulun, örneğin tüm part definition'ları:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/elements?type=part%20def&limit=100"
- Bir paketin SysML metnini okuyun:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/sysml?root=Vehicles"
Uzun bir metin "truncated": true ve "next" ile biter: sonraki istekte line ile istenecek satır.
SysML metnini önermeden önce denetleme
- Bir paketin yeni metnini denetleme rotasına gönderin:
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
-d '{"root": "Vehicles", "text": "package Vehicles { … }"}' \
https://app.holarch.app/api/v1/projects/<project>/sysml/check
- Yanıtı okuyun. Metinde sözdizimi hatası olmadığında
okdeğeritrueolur.diagnostics, sözdizimi hatalarınılinevecolile ve metnin modele ekleyeceği hataları listeler.changes, metnin yaptığı model değişikliklerinin sayısıdır.
Denetleme hiçbir şeyi değiştirmez. Yalnızca bir okuma belirteci gerektirir.
Bir değişiklik önerme ve uygulama
Bir yazma belirteci, belirtecin açık önerisine değişiklik ekler. İstemci ardından öneriyi incelemeye gönderir.
- Bir değişiklik ekleyin. Bir paketin tam yeni metnini veya öğe düzenlemelerini gönderin:
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
-d '{"edits": [{"op": "create", "kind": "attribute", "owner": "Vehicles::Car", "name": "range", "typedBy": ["LengthValue"]}]}' \
https://app.holarch.app/api/v1/projects/<project>/proposal/changes
Öneri, değişikliğin özeti ve değişikliğin eklediği, değiştirdiği ve kaldırdığı öğelerle birlikte 201 alırsınız. Hata tanılamaları ekleyen bir değişiklik reddedilir (bkz. SysML v2 projelerinde öneriler).
- Daha fazla değişikliği aynı şekilde ekleyin. Her değişiklik, önerinin önceki değişiklikleri uygulanmış modele göre denetlenir.
- Öneriyi incelemeye gönderin:
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
-d '{"title": "Add range attribute", "summary": "Adds Car::range for the range requirement."}' \
https://app.holarch.app/api/v1/projects/<project>/proposal
- Holarch'ta projeyi açın, ardından ✦ YZ ▾ → “Add range attribute” incele… seçeneğini (veya zilin altındaki bildirimi) açın.
- Satırları denetleyin ve Seçilenleri uygula düğmesine tıklayın.
İşaretli değişiklikler geçmişte adınızla birlikte uygulanır ve tek bir Geri al ile hepsi geri alınır.
Bir YZ aracını bir SysML v2 projesine bağlama
- YZ aracını bir belirteçle veya oturum açarak
https://app.holarch.app/mcpadresine bağlayın (bkz. API ve MCP). - Model hakkında soru sorun, örneğin “Holarch'taki Hybrid Car modelini özetle” veya “Hybrid Car projesindeki hangi gereksinimler doğrulanmadı?”.
YZ aracı
model_summary,list_elements,list_requirementsve diğer okuma araçlarını kullanır. - Bir değişiklik isteyin, örneğin “
Carüzerinde birrangeözniteliği öner”.YZ aracı paketi
get_sysmlile okur, metin veya öğe düzenlemeleri önerir ve denetlemenin döndürdüğü tanılamaları düzeltir. - Öneriyi Holarch'ta inceleyin ve Seçilenleri uygula düğmesine tıklayın.
Çalışılmış örnek: Hybrid Car demosu
Demoyu Projeleri yönet → Proje dosyaları ▾ → Yeni demo proje → Hybrid Car (SysML v2) ile oluşturun, ardından onun için okuma ve yazma belirteci oluşturun.
GET /api/v1/projects/<project>/model, aralarındaVehicles,HybridCarArchitectureveVehicleBehaviorbulunan en üst düzey paketleri listeler.GET /api/v1/projects/<project>/elements?query=Engine&type=part%20def,Vehicles::Engineöğesini bulur.GET /api/v1/projects/<project>/elements/Vehicles::Engine, part definition'ı SysML metni, üyeleri (displacement,cylinders,maxPower,fuelIn,outputveecuport'ları) ve onunla türlenen usage'larla birlikte döndürür.GET /api/v1/projects/<project>/elements/Vehicles::Car/connections,powertrain.outputilefrontAxle.inputarasındakidriveShaftinterface'ini listeler.GET /api/v1/projects/<project>/requirements?status=unverified, hiçbir verification case'in doğrulamadığı gereksinimleriVR-4.1gibi kimlikleriyle listeler.{"edits": [{"op": "update", "id": "Vehicles::Engine", "doc": "Gasoline engine of the hybrid powertrain."}]}ilePOST /api/v1/projects/<project>/proposal/changesdeğişikliği öneriye ekler. Bir başlıklaPOST /api/v1/projects/<project>/proposalöneriyi gönderir.- Holarch'ta ✦ YZ ▾ → “…” incele, part definition ve
docalanıyla Değiştirildi: bölümünü veVehiclespaketinin metin farkını gösterir. Seçilenleri uygula değişikliği uygular.
İpuçları
- Bir paket için yeni metin önermeden önce onu
get_sysml(veyaGET …/sysml?root=) ile okuyun. Önerilen metinde yer almayan öğeler kaldırılır. - Küçük değişiklikler için öğe düzenlemelerini tercih edin. Bunlar yalnızca adı verilen öğeleri değiştirir ve paket metninin geri kalanını olduğu gibi bırakır.
- Metni önce
check_sysml(veyaPOST …/sysml/check) ile denetleyin. Bir önerinin reddedileceği tanılamaların aynısını döndürür. - Betiklerde öğeleri nitelikli adla adlandırın. Bir öğe yeniden adlandırıldığında kimlikler aynı kalır; nitelikli adlar kalmaz.
- Bir YZ aracı yalnızca model hakkındaki soruları yanıtlıyorsa ona salt okunur bir belirteç verin.
SysML v2 projeleri için REST rotaları
Temel adres: https://app.holarch.app/api/v1. Yanıtlar JSON'dur. /api/v1/openapi.json (OpenAPI 3.1) bu rotaları diğerleriyle birlikte tanımlar.
| Yöntem ve yol | Ne yapar |
|---|---|
GET /projects/<project>/model | Metasınıf başına öğe sayıları, öğe sayılarıyla en üst düzey paketler ve hata ile uyarı sayısı |
GET /projects/<project>/elements | Arama: query (veya q; ad, kısa ad, nitelikli ad veya doc içindeki metin), type, owner, limit (1–500, varsayılan 50), offset; nitelikli ada göre sıralanır |
GET /projects/<project>/elements/<id> | Alanları, doc'u, SysML metni, üyeleri ve onunla türlenen usage'larla tek bir öğe; members (0–200, varsayılan 100) |
GET /projects/<project>/elements/<id>/connections | Öğede veya özelliklerindeki connection'lar, interface'ler, binding'ler, flow'lar (item ile), succession'lar, transition'lar, allocation'lar ve dependency'ler ile öğenin içinde sahip olunanlar; limit (varsayılan 100) |
GET /projects/<project>/requirements | Kimlik, ifade (doc), satisfiedBy ve verifiedBy ile gereksinimler; owner, status (unsatisfied veya unverified), limit (varsayılan 100), offset |
GET /projects/<project>/diagnostics | Modelin tanılamaları, önce hatalar; ids (virgülle ayrılmış: yalnızca bu öğeler ve üyeleri), limit (varsayılan 200, en fazla 500) |
GET /projects/<project>/sysml | Bir en üst düzey paketin (root), paketlerin dışındaki öğelerin (root olmadan) veya tek bir öğenin (element) SysML metni; line (ilk satır, 1'den), lines (varsayılan 2000, en fazla 5000) |
POST /projects/<project>/sysml/check | text değerini root (veya paketlerin dışındaki öğeler) için yeni metin olarak denetler; hiçbir şeyi değiştirmez |
POST /projects/<project>/proposal/changes | Açık öneriye bir değişiklik ekler: {text, root} veya {edits} |
GET /projects/<project>/proposal | Açık öneri veya proposal kimliğiyle belirtilen bir öneri, durumu ve değişiklikleriyle |
POST /projects/<project>/proposal | Açık öneriyi incelemeye gönderir: title, summary |
DELETE /projects/<project>/proposal | Açık öneriyi gönderilmeden önce atar |
GET /projects ve GET /projects/<project> SysML v2 projelerinde de çalışır. "language": "sysml2" verirler ve proje yanıtı elements ile types (metasınıf başına öğe sayıları) ekler.
LML nesne rotaları (/entities, /relationships, /schema, Model denetimleri ve kalite denetimi) bir SysML v2 projesinde 409 wrong-project-type yanıtı verir. SysML v2 rotaları da bir LML projesinde aynı yanıtı verir.
Değerler
- type:
PartUsageveyaRequirementDefinitiongibi bir metasınıf ya da SysML metninde yazıldığı biçimiyle bir anahtar sözcük:part,part def,attribute,port,requirement,action,packageve diğer öğe anahtar sözcükleri. - owner, id, element, root: bir kimlik veya nitelikli ad.
rootbir en üst düzey paketin adını da kabul eder.rootbir en üst düzey paket olmalıdır; tek bir öğenin metnini okumak içinelementkullanın. - Uzun değerler: bir listedeki doc 4,000 karakterde, tek bir öğenin doc'u 20,000 karakterde ve bir öğenin kendi SysML metni 16,000 karakterde kesilir.
SysML v2 projeleri için MCP araçları
MCP uç noktası bu araçları LML araçlarının yanında listeler. Bir YZ aracı SysML v2 projelerini list_projects (language: sysml2) ile bulur. Her araç project alır.
Okuma araçları ayrıca, modeli o değişiklik talebinin oluşturacağı hâliyle okumak için isteğe bağlı bir change_request (CR-12 veya kimliği) alır; propose_sysml ve propose_element_changes değişikliği talebin modeline göre hesaplamak ve incelemeden sonra o taslağa uygulamak için bir değişiklik talebi alır. Kurallar için bkz. Değişiklik talepleri.
| Araç | Erişim | Ne yapar |
|---|---|---|
model_summary | Okuma | Metasınıf başına öğe sayıları, en üst düzey paketler ve tanılama sayısı |
list_elements | Okuma | Öğeleri metne (query), type ve owner değerine göre bulur; limit ve offset ile sayfalanır |
get_element | Okuma | Türleri, özelleştirmeleri, çokluğu, değeri, uçları, doc'u, SysML metni, üyeleri (members, en fazla 200) ve onunla türlenen usage'larla tek bir öğe (id) |
get_connections | Okuma | Bir öğenin connection'ları, interface'leri, binding'leri, flow'ları, succession'ları, transition'ları, allocation'ları ve dependency'leri (id, limit) |
list_requirements | Okuma | Kimlik, ifade, satisfy ve verify ile gereksinimler; owner, status (unsatisfied, unverified), limit, offset |
get_sysml | Okuma | Bir en üst düzey paketin (root), paketlerin dışındaki öğelerin veya tek bir öğenin (element) SysML metni; line, lines (en fazla 5000); yanıt next verir |
get_sysml_text | Okuma | Tüm modelin (her en üst düzey paket, ardından paketlerin dışındaki öğeler) veya tek bir package değerinin SysML metni, yanıt başına en fazla 200,000 karakter; yanıt dışarıda bırakılan paketleri adlandırır |
check_sysml | Okuma | text olmadan: modelin tanılamaları (ids, limit). text (ve root) ile: satır ve sütunla sözdizimi hataları ve metnin ekleyeceği hatalar. Hiçbir şeyi değiştirmez |
propose_sysml | Okuma ve yazma | Bir en üst düzey paketin (root) veya paketlerin dışındaki öğelerin (root olmadan; yeni bir paket de buraya gider) tam yeni text değerini önerir |
propose_element_changes | Okuma ve yazma | Metni yeniden yazmadan edits (en fazla 100) önerir: oluşturma, güncelleme, taşıma veya kaldırma |
list_diagrams, get_diagram ve get_matrix SysML v2 projelerinde de çalışır: list_diagrams görünümleri (InterconnectionView gibi türleriyle) ve bir öğenin altında tutulan analiz diyagramlarını listeler; get_diagram bir görünümün filtrelerinden sonra gösterdiği öğeleri (öğe kimliğine veya nitelikli ada göre) verir; get_matrix her gereksinimi onu karşılayan ve doğrulayan öğelerle verir.
LML projelerinin öneri araçları burada da aynı şekilde çalışır: propose_changes öneriyi bir başlık ve özetle gönderir, discard_proposal onu atar, get_proposal ve list_proposals durumunu gösterir. Salt okunur bir belirteç yalnızca okuma araçlarını listeler.
Araç hataları, ileti ve tanılamalarla birlikte bir araç sonucu olarak döner; böylece YZ aracı metnini düzeltip yeniden deneyebilir.
Öğe düzenlemeleri
edits (MCP) veya {"edits": […]} (REST) içindeki her düzenleme op içeren bir nesnedir:
| op | Alanlar |
|---|---|
create | kind (part, part def, attribute, port, requirement, action, package gibi bir anahtar sözcük) veya type (bir metasınıf); owner (atlanırsa: en üst düzey); name (zorunlu); isteğe bağlı shortName, typedBy, specializes, subsets, redefines, multiplicity, value, doc, direction (in, out, inout) |
update | id ve oluşturmadaki gibi değiştirilecek alanlar; null veya "" bir alanı temizler |
move | id ve yeni owner |
remove | id; öğeyi üyeleriyle birlikte kaldırır |
typedBy,specializes,subsetsveredefinesen fazla 20 adlık listelerdir: kimlikler, nitelikli adlar veya metinde yazıldığı biçimiyle adlar (MassValuegibi kitaplık adları çalışır).- Sonraki düzenlemeler, aynı çağrıda daha önce oluşturulan öğeleri oluşturulma sırasına göre
new:1,new:2… olarak adlandırabilir; örneğinownerolarak. Yanıt bunları yeni kimlikleriylecreatedaltında listeler. - Bir öğeyi yeniden adlandırmak, onu eski adıyla anan başvuruları da günceller.
Önerilen metin
propose_sysmlpaketin tüm metnini değiştirir. Öğeler, metnin onları hâlâ bildirdiği yerlerde kimliklerini korur. Metinde yer almayan öğeler kaldırılır.- Metin, uygulanmadan kalan hiçbir şey olmadan ayrıştırılmalıdır. Modeli değiştirmeyen metin reddedilir (
no-change).
SysML v2 projelerinde öneriler
Önerilen her değişiklik, öneriye katılmadan önce dil çekirdeği tarafından denetlenir:
- Metin sözdizimi hatası olmadan ayrıştırılır ve öğe düzenlemeleri uygulanır.
- Değiştirilen paketler hâlâ SysML metni olarak yazdırılır ve yeniden ayrıştırılır.
- Değişiklik modele çözümlenmemiş adlar veya tür hataları gibi hata tanılamaları eklemez. Modelde zaten olan hatalar sayılmaz.
Başarısız olan bir değişiklik, düzeltilecek tanılamalarla (en fazla 50) reddedilir. Hiçbir şey saklanmaz. Uyarılar bir değişikliği reddettirmez.
Öneride bulunmak, okuma ve yazma belirteci ile projede düzenleyici veya sahip rolü gerektirir. Bir öneri en fazla 200 değişiklik ve 8 MB içerir.
Bir SysML v2 önerisini inceleme
Projeyi açın, ardından ✦ YZ ▾ → “<title>” incele…. Her değişiklik onay kutusu olan bir satırdır:
- Eklendi, Değiştirildi ve Kaldırıldı, öğeleri değişen alanlarla listeler (her birinin ilk 20'si; geri kalanı için “ve n tane daha”).
- Paketle etiketlenen bir metin farkı, SysML metninin önceki ve sonraki hâlini gösterir.
- Öğe kaldıran bir değişiklik işaretlenir ve işaretsiz başlar.
- Bu değişikliği uygulamak için SysML v2 modelini açın. Model yüklenmedi; projenin bir SysML v2 sayfasını açın.
- Paket artık modelde değil; atlandı. Paket, değişiklik önerildikten sonra kaldırıldı.
Seçilenleri uygula, her metin değişikliğini mevcut modele göre yeniden eşitler ve öğeleri hâlâ var olan düzenlemeleri korur. Tüm kümeyi denetler ve tek bir geri alma adımı olarak uygular. Artık uymayan değişiklikler atlanır ve bir bildirimde adlandırılır. Reddet ve Daha sonra, LML önerilerindeki gibi çalışır; roller, süre sonu (7 gün) ve saklama da öyle (bkz. YZ istemcilerinden gelen öneriler).
Systems Modeling API
Diğer SysML v2 araçları Holarch modellerini OMG Systems Modeling API (REST/HTTP) biçimlerindeki rotalar üzerinden okur ve değiştirir. Temel adres https://app.holarch.app/api/v1/sysml'dir. Aynı belirteçleri kullanır; her proje rolü okuyabilir, düzenleyiciler ve sahipler commit edebilir.
- Projeler: yalnızca SysML v2 projeleri listelenir. Bir projenin
@iddeğeri bu API'nin ona verdiği bir UUID'dir; Holarch proje kimliği de çalışır. YanıtholarchIdveurliçerir. - Dallar:
maincanlı modeldir ve API üzerinden değiştirilemez. Diğer her dal, “CR-12 Title” biçiminde adlandırılan veholarchChangeRequest(id,label,status,url) taşıyan, devam eden bir değişiklik talebidir. Son 30 günde uygulanan veya geri çekilen değişiklik taleplerideletedayarlı olarak listelenmeye devam eder. - Commit'ler: bir commit, değişiklikleri bir değişiklik talebinin dalına yazar. Yalnızca dal başları sunulur:
maindalının başı canlı modeldir, bir değişiklik talebi dalının başı talebin değişiklikleriyle birlikte canlı modeldir. Daha eski commit kimlikleri404yanıtı verir; geçerli başı daldan alın. - Öğeler: her öğe, türetilenler dahil (
owner,ownedElement,qualifiedName,feature,typeve benzerleri) OMG JSON şemasındaki metasınıfının her özelliğine sahiptir. Standart kitaplık öğelerine standart kimlikleriyle, yani diğer SysML v2 araçlarının aynı kitaplık öğesi için kullandığı kimliklerle başvurulur. - Etiketler ve kayıtlı sorgular: yok; listeleri boştur.
| Yöntem ve yol | Ne yapar |
|---|---|
GET /sysml/projects | SysML v2 projeleriniz |
POST /sysml/projects | Boş bir SysML v2 projesi oluşturur (name, description) |
GET /sysml/projects/<projectId> | Varsayılan dalıyla tek bir proje |
GET /sysml/projects/<projectId>/branches | main ve değişiklik talebi dalları |
POST /sysml/projects/<projectId>/branches | Bir dal oluşturur: yeni bir Taslak değişiklik talebi (name başlığı, description gerekçesidir) |
GET /sysml/projects/<projectId>/branches/<branchId> | head ile dal (@id değeri veya main) |
DELETE /sysml/projects/<projectId>/branches/<branchId> | Değişiklik talebini geri çeker |
GET /sysml/projects/<projectId>/commits | Başlar ve dallara gönderilen commit'ler, en yenisi önce |
POST /sysml/projects/<projectId>/commits?branchId=<branchId> | Değişiklikleri bir dala commit eder (aşağıda) |
GET /sysml/projects/<projectId>/commits/<commitId> | Bir baş commit |
GET /sysml/projects/<projectId>/commits/<commitId>/changes | Dalın canlı modele göre değiştirdikleri: her öğe için bir DataVersion |
GET /sysml/projects/<projectId>/commits/<commitId>/elements | Commit'in tüm öğeleri, sayfalı |
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId> | Tek bir öğe |
GET /sysml/projects/<projectId>/commits/<commitId>/roots | En üst düzey öğeler, sayfalı |
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>/relationships | Öğenin kaynak veya hedef olduğu ilişkiler; direction değeri in, out veya both (varsayılan), sayfalı |
POST /sysml/projects/<projectId>/query-results | Bir sorguyla eşleşen öğeler (gövde aşağıda), sayfalı; commitId bir baş olmalıdır |
GET /sysml/projects/<projectId>/tags, /queries, /commits/<commitId>/elements/<elementId>/projectUsages | Boş listeler |
Liste yanıtları JSON dizileridir. Listeler page[size] (varsayılan 100, en fazla 1000) ve page[after] (önceki sayfanın son öğesinin @id değeri) veya page[before] (sonraki sayfanın ilk öğesinin @id değeri) ile sayfalanır. Link üst bilgisi sonraki sayfayı rel="next" ile, öncekini rel="prev" ile verir.
Sorgu; isteğe bağlı bir where (property, operator (=, in, <, <=, >, >= veya instanceOf), value ve inverse içeren bir PrimitiveConstraint ya da and veya or operator değeri ve constraint içeren bir CompositeConstraint), scope (öğe kimlikleri: arama onları ve sahip olduklarını kapsar) ve select (döndürülecek özellikler; @id ve @type her zaman döner) içeren bir JSON nesnesidir:
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
"https://app.holarch.app/api/v1/sysml/projects/<projectId>/query-results" \
-d '{"@type": "Query", "where": {"@type": "PrimitiveConstraint", "property": "@type", "operator": "=", "value": "PartDefinition", "inverse": false}, "select": ["name", "qualifiedName"]}'
Bir modelin öğelerini okuyun:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/sysml/projects
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/sysml/projects/<projectId>/branches/main
curl -i -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/sysml/projects/<projectId>/commits/<head id>/elements?page[size]=500"
Değişiklikleri commit etme
Yazma; okuma ve yazma erişimli bir belirteç, düzenleyici veya sahip rolü, Team planı (akademik ve sınıf hesapları için de) ve proje için açık dal incelemesi (Değişiklik talepleri → Ayarlar) gerektirir. Bir onaylayıcı değişiklik talebini Holarch'ta inceler ve uygular; belirteçler hiçbir zaman oy vermez veya uygulamaz.
- Bir dal oluşturun:
{"@type": "Branch", "name": "Cabin heater"}ile POST/branches. Yanıt,holarchChangeRequestile birlikte daldır. - Dalın başını ve öğelerini okuyun.
- Bir
DataVersionlistesiyle POST/commits?branchId=<branch @id>:
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
"https://app.holarch.app/api/v1/sysml/projects/<projectId>/commits?branchId=<branch id>" \
-d '{"@type": "Commit", "description": "Add the heater",
"previousCommit": {"@id": "<head id>"},
"change": [{"@type": "DataVersion", "identity": {"@id": "<new uuid>"},
"payload": {"@type": "PartDefinition", "declaredName": "CabinHeater", "owner": {"@id": "<package id>"}}}]}'
- Bir öğeyi değiştirme: öğeyi okuduğunuz gibi, özellikleri değiştirilmiş olarak gönderin. Yalnızca sahip olunan özellikler sayılır (
declaredName,ownedRelationship,isAbstractve benzerleri); türetilenler yok sayılır, bu nedenle okuduğunuzu geri göndermek hiçbir şeyi değiştirmez. Dışarıda bıraktığınız bir özellik değerini korur; temizlemek içinnullveya[]gönderin. - Yeni öğeler: öğeye yeni bir UUID ve sahiplik üyeliğini (aynı commit'te gönderilir) ya da üyeliği sizin için oluşturan
ownerdeğerini verin. - Bir öğeyi kaldırma:
payload: nullöğeyi sahip olduğu her şeyle birlikte kaldırır. - Denetimler: commit'in dokunduğu her paket yeniden yazdırılıp ayrıştırılabilmeli ve commit hata tanılamaları eklememelidir; aksi takdirde düzeltilecek
diagnosticsile422döner. - previousCommit: değişikliğinizin yapıldığı baş. Dal o zamandan beri ilerlediyse yanıt geçerli
headile409stale-headolur; yeniden okuyun ve onun üzerine commit edin. - Yeniden denemeler: bir
Idempotency-Keyüst bilgisi gönderin. 24 saat içinde aynı anahtar ve gövdeyle yapılan bir yeniden deneme ilk yanıtı yeniden alır. maindalına commit'ler:branchIdolmadan veyamainile yapılan bir commit, belirtecinizin kendi taslak değişiklik talebine (“API changes from <token name>”) gider; bu talep ilk böyle commit'te oluşturulur. Yanıt hangisi olduğunuholarchChangeRequestiçinde ve birWarningüst bilgisinde belirtir.- Yeni projeler: POST
/sysml/projectsile oluşturulan bir projede dal incelemesi açıktır. Projenin tek üyesi sizkenmaindalına yapılan ilk commit bir kez doğrudan modele yazılır; sonraki commit'ler değişiklik taleplerinden geçer.
Değişiklik talebini POST /api/v1/projects/<project>/change-requests/<CR-12>/submit ile incelemeye gönderin (API ve MCP). Etiketler, birleştirmeler ve bir projeyi yeniden adlandırma veya silme, bunun yerine ne yapılacağını belirten 405 yanıtı verir. Hatalar, OMG API'nin tanımladığı gibi @type Error ve bir description taşır.
İletiler
API ve MCP kodları geçerlidir. SysML v2 rotaları ve araçları şunları ekler:
| Kod | Durum | Anlamı |
|---|---|---|
wrong-project-type | 409 | Bir SysML v2 projesinde LML işlemi veya bir LML projesinde SysML v2 işlemi |
syntax | 422 | Önerilen metinde sözdizimi hataları var; tanılamalar satır ve sütun verir |
invalid-model | 422 | Değişiklik modele hata tanılamaları ekliyor; bunlar listelenir |
not-printable | 422 | Değişiklik SysML metni olarak yazılamıyor |
invalid | 422 | Değişiklik modele uygulanamadı |
no-change | 400 | Metin modeli değiştirmiyor |
too-large | 413 | Metin 1,000,000 karakterden uzun veya öneri 8 MB'tan büyük |
too-many | 413 veya 409 | Tek bir çağrıda 100'den fazla düzenleme (413) veya öneride zaten 200 değişiklik var (409) |
stale | 409 | Önerinin önceki bir metin değişikliği artık modele uygulanmıyor |
not-found | 404 | Böyle bir proje, öğe, dal veya commit yok (Systems Modeling API yalnızca dal başlarını sunar) |
not-writable | 405 | Systems Modeling API üzerinden etiketler, birleştirmeler, bir projeyi yeniden adlandırma veya silme; bunu Holarch'ta yapın |
main-protected | 405 | main dalını silme; bunun yerine bir değişiklik talebi dalını silin |
stale-head | 409 | Dal previousCommit değerinden bu yana ilerledi; head değerini okuyun ve yeniden commit edin |
branch-base | 409 | Yeni bir dal main dalının başından başlamalıdır |
branch-review-off | 409 | Proje dal incelemesi kullanmıyor; bir sahip bunu Değişiklik talepleri → Ayarlar içinde açar |
cr-not-draft | 409 | Değişiklik talebi gönderilmiş veya kapatılmış; yalnızca Taslak veya Reddedildi durumundayken yazılabilir |
cr-full | 409 | Değişiklik talebi 5,000 değişmiş öğe içeriyor veya projede 20 MB değişiklik talebi taslağı var |
plan-limit | 403 | Değişiklik taleplerine yazma Team planını gerektirir |
orphan | 422 | Yeni bir öğenin sahibi yok; sahiplik üyeliğini veya owner değerini gönderin |
unknown-metaclass | 422 | Bir payload'ın @type değeri bir SysML v2 metasınıfı değil |
idempotency-key-reused | 422 | Idempotency-Key başka bir gövdeyle kullanıldı; yeni bir anahtar gönderin |
token-projects | 403 | Bir proje listesiyle sınırlı bir belirteç proje oluşturamaz |
bad-request | 400 | Eksik veya yanlış bir değer; örneğin en üst düzey paket olmayan bir root, bilinmeyen bir op veya adı olmayan yeni bir öğe |
Sınırlar
| Ne | Sınır |
|---|---|
| Sayfa başına öğe, gereksinim veya connection | 500 |
| Bir öğeyle listelenen üyeler | 200 |
| Yanıt başına tanılama | 500 |
| Yanıt başına SysML metni satırı | 5,000 ve en fazla 400,000 bayt (bir satırda kesilir) |
| Doc metni | Listelerde 4,000 karakter, tek bir öğe için 20,000 |
| Bir öğenin kendi SysML metni | 16,000 karakter |
Tek bir propose_sysml çağrısındaki metin | 1,000,000 karakter |
| Tek bir çağrıdaki düzenlemeler | 100 |
| Tek bir değişiklikte eklendi, değiştirildi veya kaldırıldı olarak listelenen öğeler | Her biri 300 |
| Tek bir önerideki değişiklikler | 200 ve 8 MB |
| Systems Modeling API sayfası | 1,000 öğe (varsayılan 100) |
| Tek bir commit'teki DataVersion'lar | 5,000 |
| Tek bir değişiklik talebindeki değişmiş öğeler | 5,000 |
| Commit gövdesi | 32 MB |
Hız sınırları, istek boyutu ve belirteç kuralları API ve MCP sayfasındakilerle aynıdır.
İlgili sayfalar
- API ve MCP
- SysML v2 projelerine başlarken
- Metin düzenleyici ve Gezgin
- SysML v2 modellerinin alışverişi
- SysML v2 projelerinde gereksinimler ve doğrulama
SysML® ve OMG®, Object Management Group, Inc.'in Amerika Birleşik Devletleri'nde ve diğer ülkelerde tescilli ticari markalarıdır.