API Commands

API Commands Nedir?

API Commands, TR7'nin kaynaklarını (vService, Backend Service, profil, ağ, kullanıcı, WAF, AGS, GTM…) komut satırından yöneten komut dalıdır. Pratikte panelin yaptığı işlerin komut satırı karşılığıdır: arayüzde tıklanarak yönetilen nesneler bu dal üzerinden komutlarla listelenir, görüntülenir, oluşturulur, değiştirilir ve silinir.

Dal, panelin REST arayüzünden türetilir: her kaynak komut ağacında bir düğüm, her kaynak üzerindeki işlem bir aksiyon olur. Ağaç Tab ile keşfedilir; alan adları, açıklamaları ve seçenek listeleri arayüzdekiyle aynı tanımlardan gelir.

10 Kaynak Dalı

ags · gtm · lb · network · settings…

Panelin konfigürasyon modülleriyle örtüşen üst düzey komutlar; her biri bir yetki alanına bağlıdır.

5 Standart Aksiyon

list · show · add · update · delete

Her koleksiyon kaynağında aynı, öngörülebilir işlem kümesi; destekleyen kaynaklarda ek olarak update-many.

Hiyerarşik ağaç

Tab ile keşif

Kaynak → alt kaynak → aksiyon → alan olarak dallanır; ezber gerekmez.

Alan Bazlı Yetki

görüntüleme · değiştirme

Okuma komutları alanı görme, yazan komutlar alanı değiştirme yetkisi ister.

Kısa sözdizimi:

<kaynak> [alt-kaynak …] <aksiyon> [<kimlik>] [zorunlu-alan değer …] [--isteğe-bağlı-alan değer …]

Komut Deseni

Bir API komutu, bir kaynağı hedef alan hiyerarşik yol ile o kaynak üzerinde çalıştırılacak bir aksiyondan oluşur. Yol soldan sağa daralır: en genel kaynaktan (lb, ags, network…) alt kaynağa, oradan aksiyona iner. Aksiyondan sonra alanlar yazılır.

Alanlar nasıl yazılır?

Bir aksiyona verilen alanlar iki türlüdür; biçim, alanın zorunlu olup olmadığını gösterir:

alan <değer>

Zorunlu — öneksiz yazılır ve tamamlama listesinde kırmızı görünür. Zorunlu alanlar sırayla istenir: biri verilmeden diğer alanlar listelenmez.

--alan <değer>

İsteğe bağlı — -- öneki ile yazılır. Verilmezse alan varsayılan değeriyle kalır.

Bir kaydı hedefleyen aksiyonlarda kaydın kimliği de zorunludur. show ve delete kimliği aksiyondan hemen sonra, alan adı yazmadan alır; update ise kimliği id alanıyla ister ve kimlik verilmeden diğer alanları listelemez. Kimlik alanı bir seçim listesidir: Tab mevcut kayıtları adlarıyla gösterir.

Alan tipleri

Tip	Yazımı
metin	Serbest metin değeri
sayı / port	Sayısal değer
mantıksal	true ya da false değeri alır
seçim	Önceden tanımlı değerlerden biri (Tab listeler)
çoklu seçim	Her seçim ayrı indeksle: --alan.0, --alan.1
liste	Çok değerli alan; öğeler indeksle yazılır: --alan.0.altAlan
süre	Zaman aralığı değeri
adres	IP adresi, ağ bloğu ya da adres/port çifti (addr.ip, addr.port)
parola	Ekranda gösterilmeden, ayrı bir satırda sorulur

Özel karakter taşıyan değerler tırnak ister

Komut satırı bazı işaretleri ayırıcı sayar. Bu işaretleri içeren bir değer çift tırnak içine alınmadan yazılırsa komut yanlış ayrıştırılır:

İşaret	Tırnaksız yazılırsa
( )	Değer parçalara bölünür; "%AGS_USER_INPUT(username)" biçiminde yazılmalıdır
#	Satırın kalanı yorum sayılır ve yok olur; "#2563eb" biçiminde yazılmalıdır
;	Değer burada bölünür
boşluk	Değer birden çok parçaya ayrılır

Adres, yol ve eğik çizgi içeren değerler tırnaksız yazılabilir.

Keşif

Tab bulunulan konumdaki alt komutları ve alanları tamamlar. Satırın sonuna ? yazılıp Enter'a basıldığında o konumda kullanılabilecek alanlar Parameter / Description sütunlu bir tablo hâlinde listelenir ve komut çalıştırılmaz; hangi alanın zorunlu olduğunu ezberlemek gerekmez.

Aksiyonlar

Koleksiyon tutan her kaynak aynı aksiyon kümesiyle yönetilir. Tek nesneli (ayar) kaynaklarda yalnızca show ve update bulunur; bazı kaynaklarda add ya da delete tanımlı değildir.

Aksiyon	İşlevi	Not
list	Kaynakların tümünü kimlik ve ad sütunlarıyla listeler	Okuma
show <kimlik>	Tek bir kaydın ayrıntısını gösterir	Okuma
add <alanlar>	Yeni kayıt oluşturur	Zorunlu alanlar öneksiz, isteğe bağlı alanlar -- önekli
update id <kimlik> [alanlar]	Var olan kaydı günceller	Yalnızca verilen alanlar değişir, diğerleri korunur
delete <kimlik>	Belirtilen kaydı siler	Aynı komutta birden çok kimlik arka arkaya yazılabilir

update alan yazımının incelikleri. Güncelleme mevcut kaydı okuyup üzerine yazar; bu yüzden yalnız değişecek alanlar verilir. İki ek bayrak yalnızca güncellemede görünür: --alan.delete alanı boşaltır, çoklu seçim alanlarında --alan.all kullanılabilir tüm seçenekleri işaretler. Parola alanları eski kayıttan geri okunmadığı için güncellemede de yeniden istenir.

Toplu Güncelleme (update-many)

update-many, aynı değişikliği birçok kayda birden uygular. Sekiz kaynakta bulunur: lb service, lb backend, lb backend-group, lb hc, lb threat-protection, network ip, waf host-groups, waf options.

Yazım. Komuttan sonra ilk yazılan alan target'tır; tek zorunlu alan odur.

Alan	Durum	Değer
target	Zorunlu	selected — listeden seçilen kayıtlar · all — koleksiyonun tamamı
--ids.N	Koşullu	target selected için hedef kimlikleri. Tab listesinde önerilmez: hedefler seçim listesinden işaretlenir. Betikte ve boru hattında elle yazılır.
--onError	İsteğe bağlı	abort (varsayılan) — hedeflerden biri bile doğrulamadan geçmezse hiçbir şey yazılmaz · skip — geçen hedefler yazılır

Hedef seçim listesi. target selected yazılıp hiç kimlik verilmediğinde, komut çalışmadan hemen önce onay kutulu bir liste açılır. Boşluk tuşu işaretler, Ctrl+A ekrandakilerin tümünü işaretler, harf yazmak listeyi süzer, Esc önce süzgeci temizler sonra listeden çıkar. En az bir kayıt işaretlenmelidir. Terminali olmayan bir çalıştırmada (betik ya da boru hattı) liste açılamaz; hedeflerin --ids.0 --ids.1 … biçiminde yazılması gerekir.

Onay. Her toplu güncelleme, uygulamadan önce onay ister. Uyarı başlığı target all için "Bu işlem koleksiyondaki TÜM nesneleri güncelleyecek", seçim için "N nesne güncellenecek" biçimindedir; ikinci satır seçilen kayıtları adlarıyla sayar (on beşten sonrası "+N tane daha" olarak toplanır). Onay sözcüğü yazılmadan hiçbir şey yazılmaz; yanlış bir şey yazıldığında işlem iptal edilir.

Hangi alanlar toplu yazılabilir. update-many düğümünde yalnız tek bir değerin birçok kayda güvenle yazılabildiği alanlar bulunur. Şunlar bu komutta yer almaz:

Dışarıda kalan	Nedeni
Kimlik, ad ve benzersiz değerler	Aynı değer birden çok kayda yazılamaz
Tür ayıracı ve salt okunur alanlar	Kaydın kimliğini belirler, sonradan toplu değiştirilemez
Kendi kimliğini taşıyan liste öğeleri	Bir kaydın öğe kimlikleri ötekilere kopyalanamaz
Değeri başka bir alana bağlı alanlar	Geçerli değer, kardeş alanın değerine göre değişir
Dosya ve serbest biçimli nesne alanları	Değer değil, yapı taşırlar

Koşula bağlı alanlar bu listede değildir: bir hedefte alan aktif değilse yalnız o hedefte atlanır, işlem hata vermez.

Sonuç raporu. Yanıt her hedefi ayrı ayrı bildirir: sonuç (applied, unchanged, skipped, failed), uygulanan alanlar, o nesnede aktif olmayan alanlar ve varsa hatalar.

CRUD dışı aksiyonlar. Ağaçta yalnızca kayıt yönetimi yoktur; bazı kaynaklar kendi işlemlerini de komut olarak sunar.

Örnek komut	İşlevi
lb service restart · lb service status list	Servisi yeniden başlatır, çalışma durumunu listeler
lb certificate create-csr · lb certificate renew-internal	Sertifika isteği üretir, dahili üretilmiş sertifikayı yeniler
settings backup create · settings backup apply	Yedek oluşturur, yedeği uygular
settings update files · settings update apply	Güncelleme dosyalarını listeler, güncellemeyi uygular
profile info · profile change-password	Oturum açan kullanıcının bilgisini gösterir, parolasını değiştirir
hw-mgmt configure	Donanım yapılandırmasını uygular

Onay isteyen komutlar

Sistem üzerinde geri alınması güç etkisi olan komutlar (donanım yapılandırması, güncelleme uygulama, dahili sertifika yenileme, WAF kural sıfırlama ve tüm toplu güncellemeler) çalışmadan önce onay ister. Onay ekranı sarı bir uyarı başlığı ve Devam etmek için "evet" yazın: satırından oluşur; onay sözcüğü tam olarak yazılmadan hiçbir değişiklik yapılmaz. Ekran dili oturum açan kullanıcının tercihine bağlıdır: İngilizce arayüzde onay sözcüğü yes olur.

Komut Ağacı

Aşağıdaki üst düzey komutlar API dalını oluşturur. Parantezsiz açıklamalar, komutun ? çıktısında görünen arayüz karşılıklarıdır.

Komut	Yönettiği alan
ags	AGS - AAM (Application Access Management) yönetimi — gateway, kimlik doğrulama, MFA, formlar, güvenlik politikaları, SSO
exit	Oturumu kapatır (Ctrl + D ile aynı)
gtm	Global Traffic Manager — DNS tabanlı küresel trafik yönetimi
help	CLI kullanım kılavuzunu gösterir
history	Komut geçmişini gösterir
hw-mgmt	Donanım yönetimi
lb	Load Balancer yönetimi — vService, Backend Service, gruplar, koşullar, aksiyonlar, profiller, sertifikalar
network	Ağ yönetimi — arayüzler, adresler, route tabloları, güvenlik duvarı kuralları
profile	Profil yönetimi — oturum açan kullanıcının kendi bilgileri
settings	Genel ayarlar — erişim, yedekleme, dizin/log aktarımı, NTP, bildirim
users	Kullanıcı yönetimi — cihaz yöneticisi hesapları
v-device	vDevice yönetimi
waf	WAF yönetimi — korunan servisler, sunucu grupları, kural kütüphanesi

INFO

Kök seviyede ayrıca logout (CLI kullanıcı çıkışı) ve sistem araçlarını çalıştıran sys-cmd bulunur.

Çıktı Biçimi ve Süzme

Yanıt döndüren komutların çıktısı istenen biçimde alınır ve süzülür:

Seçenek	İşlev
--info	Komutu çalıştırmadan, ne yaptığının açıklamasını gösterir
--output json	Tek satırlık JSON
--output jsonp	Girintili, okunaklı JSON
--output tab · comma · semicolon	Sütunları sekme, virgül ya da noktalı virgülle ayrılmış düz metin
--output compact	Daralmış tablo
--output default	Çerçeveli tablo (varsayılan görünüm)
--filter <kalıp>	Çıktıyı kalıba göre süzer; eşleşen metin yeşil vurgulanır, eşleşmeyen satırlar gösterilmez

TIP

Çıktıyı daha ileri süzmek, dönüştürmek ya da dosyaya yazmak için Pipe Commands kullanılır (| grep, | jq, | to-file…); bir satırda en çok 8 süzgeç zincirlenebilir.

Örnek Senaryolar

TR7 WEB-CLI · A) Görüntüleme ve süzme

admin@TR7LBWAF01> lb service list # tüm vService'leri listele

admin@TR7LBWAF01> lb service show <kimlik> # birinin ayrıntısını göster

admin@TR7LBWAF01> lb service list --output jsonp # çıktıyı okunaklı JSON olarak al

admin@TR7LBWAF01> lb service list --filter portal # sonucu kalıba göre süz

admin@TR7LBWAF01>  

TR7 WEB-CLI · B) Yeni kayıt oluşturma

# zorunlu alanlar öneksiz, sırayla yazılır

admin@TR7LBWAF01> lb backend add name web-01 zoneId <vDevice> namespace <route-tablosu> \

addr.ip 10.20.0.15 addr.port 8080

admin@TR7LBWAF01> lb backend list # oluştuğunu doğrula

admin@TR7LBWAF01>  

TR7 WEB-CLI · C) Güncelleme, toplu güncelleme ve silme

admin@TR7LBWAF01> lb backend update id <kimlik> --name web-02 # yalnız değişen alan

admin@TR7LBWAF01> lb service update-many target selected --waf true

admin@TR7LBWAF01> lb backend delete <kimlik> <kimlik-2> # bir ya da çok kaydı sil

admin@TR7LBWAF01>  

TR7 WEB-CLI · D) Keşif ve açıklama

admin@TR7LBWAF01> lb service add --info # komut ne yapar, çalıştırmadan gör

admin@TR7LBWAF01> lb ? # alt komutları açıklamalı listele

admin@TR7LBWAF01> lb service add ? # bu konumdaki alanları listele

admin@TR7LBWAF01>  

Erişim ve Yetkiler

Her üst düzey komut bir yetki alanına eşlenir; komutun çalışıp çalışmayacağına kullanıcının o alandaki yetkisi karar verir.

Komut dalı	Yetki alanı
ags · lb	Load Balancer
network	Network
waf	WAF
gtm	GTM
users	Users
settings · hw-mgmt	Settings
profile · v-device	Eşlenmez; yetkiye sunucu karar verir

Aksiyon türü	Gereken yetki
Okuma (list, show, durum sorguları)	Alanı görüntüleme
Yazma (add, update, update-many, delete ve işlem çalıştıran komutlar)	Alanı değiştirme

• superAdmin rolü bu denetimlerin dışındadır; tüm dallarda okuma ve yazma yapabilir.
• readOnly rolü tüm alanları okur, hiçbir alanda yazamaz.
• Alan rolleri (ör. networkManager, trafficUser, wafManager) yalnızca kendi alanlarına giren dalları kullanır; değiştirme yetkisi olanlar o alanda yazabilir.
• lb dalı yük dengeleme, WAF ve sertifika alanlarını birlikte kapsar; bu alanlardan birinde yetkisi olan kullanıcı dala girebilir, hangi kaynağa erişebileceğine sunucu karar verir.

INFO

Yetki dışı bir komut çalıştırılmaz ve Permission denied. uyarısı döner (arayüz dili Türkçe olan kullanıcıda Yetkiniz bulunmamaktadır.). Erişim modelinin tamamı, kanal anahtarları ve oturum sınırları için Web CLI ana sayfasına bakılabilir.