Web otomasyonu

Botream, web uygulamalarını Chrome, Edge veya Firefox'ta Playwright aracılığıyla yönetir: browser komutuyla bir tarayıcı açar, sayfa elementleriyle de capture komutu üzerinden çalışırsınız.

#Tarayıcılar

browser --action:open, ajan makinesinde bir tarayıcı başlatır. Tarayıcıyı --browser ile seçin:

Chrome ve Edge, makinede zaten kurulu olan tarayıcıları kullanır; bu nedenle güncel tutmanız gereken bir tarayıcı sürücüsü yoktur. Bir görevin açtığı her tarayıcı yeni bir profille başlar: kendi gezintinizden kalan çerezler, kayıtlı oturum açma bilgileri veya eklentiler bulunmaz.

browser --action:open --url:"https://shop.example.com" --browser:edge --output:shop

#Görünmez (headless) tarayıcılar

--headless:true, tarayıcıyı pencere olmadan çalıştırır. Arka planda veri okumak için kullanışlıdır, ancak ajanın ekranında hiçbir şey görünmez.

#Görünür tarayıcılar açık kalır

Görünür bir Chrome veya Edge penceresi çalıştırma bittiğinde açık bırakılır; böylece görevin nerede durduğunu görebilir ve bu pencerede başka elementler yakalayabilirsiniz. Görevin kendi ardını toplaması gerekiyorsa pencereyi browser --action:close ile kapatın (örneğin bir finally bölümünde). Görünmez tarayıcılar ve Firefox, çalıştırma bittiğinde her zaman kapatılır.

İpucu: Bir görev oluştururken ilk birkaç satırı bir kez çalıştırın, ardından sonraki elementleri doğrudan görevin açık bıraktığı tarayıcıda yakalayın.

Görünür tarayıcılarda ajan ne yaptığını gösterir: her element eyleminden önce bir işaretçi elemente doğru kayar ve element yaklaşık bir saniye boyunca eylemin adını ("Click", "Type") taşıyan turuncu bir çerçeveyle işaretlenir. Gerçek fare hareket ettirilmez.

#Tarayıcı değişkenleri

browser --action:open üzerindeki --output, sayfayı bir değişkende saklar. Diğer tüm web komutları --browser:$name$ ile bu değişkene işaret eder; böylece aynı anda birden çok sayfayla çalışabilirsiniz:

browser --action:open --url:"https://shop.example.com" --output:shop
browser --action:open --url:"https://erp.local" --output:erp
capture --browser:$shop$ --action:gettext --dompath:"#price" --output:price
capture --browser:$erp$ --action:settext --dompath:"#amount" --value:$price$
browser --browser:$shop$ --action:close

--browser belirtilmezse komut en son kullanılan sayfada çalışır.

Diğer browser eylemleri navigate, refresh, back, forward, scroll, screenshot (görünmez modda da tüm sayfa), getcurrenturl, gettitle, executejs ve close ile aşağıdaki sekme, iletişim kutusu ve çerez eylemleridir.

#capture komutu

capture, bir sayfanın tek bir elementiyle çalışır. Eylemi --action ile seçin:

capture --browser:$shop$ --action:settext --dompath:"//input[@name='email']" --value:"user@test.com"
capture --browser:$shop$ --action:select --dompath:"//select[@id='country']" --value:"Turkey"
capture --browser:$shop$ --action:getproperty --dompath:"//h1" --property:text --output:pageTitle
capture --browser:$shop$ --action:exists --dompath:"//div[@class='error']" --output:hasError

getproperty için --property; text, value, innerhtml, outerhtml veya herhangi bir HTML özniteliğini alır. Her element eylemi elementi --timeout süresine kadar (varsayılan 30 saniye) bekler ve --retry ile --retryinterval kullanılarak tekrarlanabilir.

#Elementleri yakalama

Seçicileri nadiren kendiniz yazarsınız. Düzenleyicide bir capture komutu seçin ve Selector yanındaki Capture düğmesine tıklayın; Capture web element iletişim kutusu açılır ve tarayıcıya geçip elemente tıklamanızı ister.

• Elementler vurgulanır: fareyi hareket ettirdikçe elementler vurgulanır. İptal etmek için Esc tuşuna basın: Botream önce Yakalama iptal edilsin mi? diye sorar (Enter iptal eder, yeniden Esc yakalamaya devam eder).
• Nerede yakalayabilirsiniz: Botream Element Capture eklentisinin kurulu olduğu Chrome veya Edge'de (bkz. Eklentiyi kurma) ve görevlerinizin açtığı Chrome ve Edge pencerelerinde. Bu pencereler eklenti içermeyen yeni bir profille çalıştığından seçiciyi ajan kendisi gösterir.
• Hangi sayfa öne gelir: komutta, browser --action:open komutu sabit bir adrese sahip bir --browser:$page$ varsa o sekme öne getirilir.
• Gereksinimler: Botream Agent, üzerinde çalıştığınız bilgisayarda çalışıyor olmalıdır. Birden çok ajan çevrimiçiyse iletişim kutusu bu bilgisayardakini seçmenizi ister.

Yakalama işlemi Selector (--dompath) alanını, Object properties tablosunu ve elementin kırmızı bir çerçeveyle işaretlendiği bir sayfa ekran görüntüsünü doldurur; tam boyutunu görmek için ekran görüntüsüne tıklayın.

Not: Eski ajanlardan veya eklentilerden gelen yakalamalar nesne özellikleri içermez. Bu durumda iletişim kutusu bulduğu seçicileri Recommended veya Not unique olarak işaretleyip listeler; birini seçin ve Use selected düğmesine tıklayın.

#UI teknolojisi

Bir capture komutunda Capture düğmesine tıklamadan önce yanındaki kutudan teknolojiyi seçin. Seçim komutta --technology olarak saklanır.

UI Automation öğesi bir masaüstü öğesi gibi saklanır:

• Selector (--dompath) name=Open, automationid=… gibi bir masaüstü bulucusu veya bir XPath tutar.
• Window (--window) tarayıcı penceresi ya da iletişim kutusu için bir pencere değişkenidir, örneğin set --name:window1 --type:window --path:chrome.exe --title:"* - Google Chrome". Ana pencerenin başlığı her sayfada değiştiği için tarayıcının adıyla eşleştirilir.
• Object properties masaüstü özellikleridir (Name, AutomationId, kontrol türü…).

Görev çalışırken komut bir desktop komutu olarak çalışır; bu yüzden her agent çalıştırabilir. Tıklama, çift tıklama, sağ tıklama, metin yazma, metin ekleme, temizleme, işaretleme, işareti kaldırma, üzerine gelme, odaklanma, kaydırarak gösterme, bekleme, seçme, özellik okuma/yazma, metin okuma ve exists desteklenir. Yalnızca HTML'de olan eylemler (tablolar, extract, upload, download, ekran görüntüleri…) editörde reddedilir.

capture --action:click --technology:uia --window:$window1$ --dompath:"name=Open"

Not: Otomatik ile tarayıcının kendi pencerelerini yakalamak güncel Botream Agent'ı gerektirir; eski agent'lar yalnızca sayfa öğelerini yakalar. UI Automation her agent ile çalışır.

#Nesne özellikleri

Object properties tablosu, yakalama sırasında elementten okunan her şeyi, her biri bir onay kutusuyla birlikte listeler. Tablonun üstündeki Object type, elementin ne olduğunu gösterir (Text box, Button, Check box, Drop-down list, Link, Table cell…). Element, işaretli özelliklere göre bulunur: her biri elementinkine eşit olmalıdır.

• Joker karakterler: değişen kısımlar için * yazın; her şeyle eşleşir. Invoice* olan bir inner text "Invoice 2026-10-06" ile, *total* total içeren her metinle, *.pdf .pdf ile biten bir bağlantıyla eşleşir.
• Eski görevler: daha önce seçilmiş karşılaştırmalar (Contains, Starts with, Not equal to…) çalışmaya devam eder ve özelliğin yanında bir etiket olarak görünür; eşittir olarak karşılaştırmak için etiketi kapatın.
• Değişkenler: değerlerde $variables$ kullanılabilir; örneğin $customerName$ şeklinde bir inner text.
• Daha fazla öznitelik: Another attribute, e.g. data-id alanına bir ad yazın ve Add düğmesine tıklayın.
• Varsayılan seçim: yakalama işlemi etiketi ve tanımlayıcı özellikleri (önce kararlı bir id, name veya test id) işaretler, element benzersiz olmadığı sürece başka özellikler ekler ve index'i yalnızca son adım olarak kullanır.

Selector, her değişiklikte işaretli özelliklerden yeniden oluşturulur. Seçiciyi elle düzenlerseniz tablo artık kullanılmaz; seçiciyi tablodan yeniden oluşturmak için Use properties düğmesine tıklayın.

İpucu: Elementin nerede olduğunu değil, ne olduğunu tanımlayan özellikleri (etiketi, adı veya test id'si) işaretleyin. Bkz. Elementleri güvenilir şekilde bulma.

#Çerçeveler

Bir çerçeve (iframe) içindeki element, çerçevenin seçicisiyle birlikte --frame gerektirir. İç içe çerçeveleri >> ile ayırın:

capture --browser:$shop$ --action:click --frame:"#payment" --dompath:"#pay"
capture --browser:$shop$ --action:settext --frame:"#checkout >> #card" --dompath:"#number" --value:$cardNo$

--frame belirtilmezse element sayfanın kendisinde aranır. wait --type:element ve wait --type:elementgone da --frame alır.

#Sekmeler ve açılır pencereler

browser --browser:$shop$ --action:newtab --url:"https://shop.example.com/orders"
browser --browser:$shop$ --action:switchtab --title:"*Invoice*" --timeout:10
browser --browser:$shop$ --action:switchtab --url:"*orders/new*"
browser --browser:$shop$ --action:gettabs --output:tabs
browser --browser:$shop$ --action:closetab

• newtab ve switchtab ilgili sekmeyi geçerli sekme yapar: bundan sonra --browser:$shop$ o sekmeyi ifade eder.
• switchtab, tarayıcının sekmeleri ve açılır pencereleri arasında --title ve/veya --url (joker karakterlerle) eşleştirmesi yapar ve sekmenin görünmesini --timeout süresine kadar bekler.
• closetab geçerli sekmeyi kapatır; önceki sekme geçerli olur. Son sekmede başarısız olur (bunun yerine close kullanın).
• gettabs, Title, Url ve IsCurrent içeren kayıtlar döndürür.

#Beklemeler

wait, sayfada bir şey gerçekleşene kadar her 250 ms'de bir kontrol eder:

wait --type:element --browser:$shop$ --dompath:"//div[@id='loaded']" --timeout:30
wait --type:elementgone --browser:$shop$ --dompath:".spinner"
wait --type:pageload --timeout:60
wait --type:url --value:"*dashboard*" --timeout:30 --failontimeout:true

Süre dolduğunda görev, günlüğe bir uyarı yazılarak devam eder ve --output değişkenine false atanır. --failontimeout:true ile bunun yerine komut başarısız olur ve en yakın catch hatayı işler. capture --action:waitfor, bir elementi bir element eylemiyle aynı şekilde bekler.

#Sayfayı bir koşulda denetleme

Sayfada görünene göre dallanmak için if veya elseif bloğuna elementexists (element görünüyor) ya da elementnotexists (gizli veya sayfada yok) koşul türünü verin. Bu, capture --action:exists ve ardından gelen if --type:boolean ikilisinin yerini alır:

if --type:elementexists --browser:$shop$ --dompath:"//div[@class='error']" --timeout:3
    capture --browser:$shop$ --action:gettext --dompath:"//div[@class='error']" --output:problem
    throw --type:business --message:"The shop refused the order: $problem$"
endif
if --type:elementnotexists --browser:$shop$ --dompath:".spinner" --timeout:30
    log --message:"The page is ready"
endif

Özellikler panelinde capture komutundaki Capture düğmesi, Object properties tablosu ve --frame aynen görünür; tablodan türetilen yedek konumlayıcılar da denenir. --timeout (varsayılan 0), karar vermeden önce elementin görünmesi veya kaybolması için en fazla o kadar saniye bekler; bulunamayan bir element bir hata değil, bir yanıttır. Tüm koşul türleri için if / elseif / else bölümüne bakın.

#İndirmeler ve yüklemeler

capture --browser:$shop$ --action:download --dompath:"#export" --path:"C:\Downloads" --output:file
capture --browser:$shop$ --action:upload --dompath:"input[type=file]" --file:"C:\a.pdf, C:\b.pdf"

• download elemente tıklar ve sitenin indirdiği dosyayı kaydeder. --path bir dosya adı veya bir klasördür (klasör verilirse sitenin dosya adı kullanılır). --output kaydedilen yolu alır.
• upload bir dosya girişine bir veya daha fazla dosya (virgülle ayrılmış) atar ya da bunları elemente tıklandığında açılan dosya iletişim kutusuna iletir.

#İletişim kutuları

Sayfaların alert, confirm ve prompt iletişim kutuları, aksini belirtmediğiniz sürece kapatılır (Cancel):

browser --action:ondialog --accept:true --text:"duplicate order"
capture --browser:$shop$ --action:click --dompath:"#save"
browser --action:getlastdialog --output:message

ondialog bundan sonrası için geçerlidir: --accept OK (true, varsayılan) veya Cancel (false) ile yanıt verir; --text prompt iletişim kutularına yazılır. getlastdialog son iletişim kutusunun iletisini döndürür.

#Çerezler

browser --browser:$shop$ --action:setcookie --name:session --value:$token$ --domain:"example.com"
browser --browser:$shop$ --action:getcookies --output:cookies
browser --browser:$shop$ --action:clearcookies

getcookies, Name, Value, Domain, Path ve Expires içeren kayıtlar döndürür. --domain belirtilmezse setcookie, çerezi geçerli sayfanın sitesi için ayarlar.

#Bir tabloyu datatable'a okuma

gettable, bir HTML tablosunu bir datatable değişkenine okur. Tabloyu, hücrelerinden herhangi birini veya tabloyu içeren bir elementi yakalayın:

capture --browser:$shop$ --action:gettable --dompath:"#orders" --output:orders
loop --type:datatable --table:$orders$ --variable:row
    log --message:"Order $row.Number$: $row.Total$"
endloop

• --header:true (varsayılan) ile sütunları tablo başlığının son satırı, yoksa ilk satır adlandırır. Boş adlar ColumnN olur; yinelenen adlara _2 eklenir.
• --header:false ile sütunlar Column1, Column2… olur ve her satır veridir.
• Hücre metinlerinin başındaki ve sonundaki boşluklar kırpılır. Birden çok sütuna veya satıra yayılan bir hücre her birinde tekrarlanır.
• O elementte bir tablo yoksa komut başarısız olur.

#Listelerden ve birden çok sayfadan veri çıkarma

Birçok sayfa verisini bir HTML tablosu yerine tekrarlanan öğeler olarak gösterir: ürün kartları, arama sonuçları, div'lerden oluşan liste satırları; çoğu zaman da Sonraki düğmesiyle birkaç sayfaya yayılır. extract bunları sayfa sayfa, her öğe için bir satır olmak üzere bir datatable'a okur — UiPath'teki Data scraping veya Automation Anywhere'deki Extract data gibi. Bunu Veri çıkar sihirbazıyla oluşturursunuz; seçici yazmanız gerekmez.

Sihirbazı başlatma. Ctrl+K tuşlarına basıp veri çıkar yazın ya da paletin Web grubunu açıp Veri çıkar'a tıklayın. Bir capture --action:extract bloğu eklenir ve sihirbaz açılır. Mevcut bir blokta Columns altındaki Sihirbazda düzenle'ye (veya Selector yanındaki Sihirbaz'a) tıklayın. Sihirbazın sayfada ne bulduğunu gösterebilmesi için önce sayfayı Chrome'da açın (veya görevi o sayfaya kadar çalıştırın).

1. Öğeler. İlk öğeye tıklayın düğmesine tıklayın, tarayıcıya geçin ve bir öğeye tıklayın — ürün kartının tamamına, arama sonucunun tamamına. Sihirbaz ardından aynı türden ikinci bir öğe ister. İkisinden her öğeyle eşleşen bir seçici oluşturur: …/ul/li[1]/div ve …/ul/li[3]/div, …/ul/li/div olur. Öğeler ortak bir sınıfa sahipse veya id'si olan bir elementin altındaysa bu seçenekler de, her biri sayfada bulduğu öğe sayısıyla birlikte sunulur. "Sayfada N öğe bulundu" seçimi doğrular.
2. Değerler. Değerlere tıklayın düğmesine tıklayın ve bir öğenin içinde istediğiniz her değere tıklayın: başlık, fiyat, bağlantı, resim. Her tıklama; önerilen bir ad (elementin etiketinden veya sınıfından), değerin öğe içindeki yeri ve neyin okunacağıyla birlikte bir sütun ekler: metin, bir resmin adresi (src) veya bir alanın değeri. Bir bağlantının metni okunur; adresini almak için Bağlantı adresi (href) seçin. Hepsini seçtiğinizde sayfada Esc tuşuna basın. Listede sütunları yeniden adlandırabilir (harf, rakam ve _; böylece $row.Price$ olur), neyin okunacağını değiştirebilir (herhangi bir öznitelik adı da olur), yolu düzenleyebilir, sütunları yukarı veya aşağı taşıyabilir ve kaldırabilirsiniz. Sayfanın ilk satırları aşağıda önizleme olarak görünür.
3. Sayfalar (isteğe bağlı). Veriler birkaç sayfada seçeneğini seçin, Sonraki düğmesine tıklayın'a tıklayın ve sayfanın Sonraki düğmesine veya bağlantısına tıklayın. En fazla kaç sayfa okunacağını belirleyin (varsayılan 10).
4. Önizleme. İlk satırları kontrol edin, ardından Bitir'e tıklayın. Sihirbaz --dompath, --columns, --next ve --maxpages alanlarını yazar ve sonucu results olarak adlandırır (isterseniz Output alanını değiştirin).

capture --browser:$shop$ --action:extract --dompath:"//div[@id='results']/ul/li/div" --columns:[{"name":"Title","path":".//h3","read":"text"},{"name":"Price","path":".//span[@class='price']","read":"text"},{"name":"Link","path":".//a","read":"href"}] --next:"//a[normalize-space()='Next']" --maxpages:10 --output:products
loop --type:datatable --table:$products$ --variable:row
    log --message:"$row.Title$ costs $row.Price$"
endloop

• Sütunlar bir JSON listesidir: name, path (değerin öğe içindeki yeri: . ile başlayan bir XPath — . öğenin kendisidir — veya bir CSS seçici) ve read (text, value, href, src, html veya herhangi bir öznitelik adı). Özellikler paneli bunları liste olarak gösterir; Edit as text JSON'u gösterir.
• Eksik değerler boş hücre olur, asla hata değildir. Hiç öğe bulunamazsa sonuç, sütunları olan boş bir tablodur ve günlük bunu belirtir.
• Sayfalar: robot her sayfadan sonra --next'e tıklar ve öğeler değişene kadar bekler (yeni bir sayfa yüklendiğinde veya sayfa listeyi yeniden çizdiğinde). Sonraki düğmesi yoksa, gizliyse veya devre dışıysa, --maxpages sayfadan sonra, öğeler --timeout içinde değişmezse ya da bir sayfa aynı satırları yeniden gösterirse durur. Önceki satırların altına yenilerini ekleyen bir Daha fazla yükle düğmesi de çalışır: her satır bir kez okunur.
• --maxrows satır sayısını sınırlar (varsayılan 0, hepsini okur). --frame bir iframe içindeki öğeleri okur.
• Canlı önizleme, Botream eklentisinin kurulu olduğu Chrome veya Edge'de ve görevlerinizin açtığı tarayıcılarda çalışır; tıkladığınız sayfanın sekmesini okur. Önizleme olmadan da sihirbaz çalışır — sonucu görmek için görevi çalıştırın.
• extract güncel bir Botream Agent gerektirir; eski bir ajan görevi, güncellenmesini isteyen bir iletiyle reddeder.

İpucu: Birkaç sayfadaki arama sonuçlarını Excel’e topla şablonu (Yeni görev → Şablondan başla) hazır bir örnektir: arama sayfasını açar, veriyi çıkarır, Excel'e yazar.

#Kaydırma

--amount, yaklaşık 100 piksellik tekerlek adımı cinsindendir: pozitif değerler yukarı, negatif değerler aşağı kaydırır. Her iki tekerlek komutu da kaydırma duruncaya kadar bekler.

#Tuş gönderme

capture --action:sendkeys elemente odaklanır ve tuşlara klavyeden basılıyormuş gibi orada basar:

capture --browser:$shop$ --action:sendkeys --dompath:"#search" --keys:"laptop[ENTER]"
capture --browser:$shop$ --action:sendkeys --dompath:"#grid" --keys:"[CTRL+A][CTRL+C]"

• Özel tuşlar ve kısayollar köşeli parantez içinde yazılır: [TAB], [ESC], [DOWN], [CTRL+A]. Değişmez bir [ için [[ kullanın. Keys to send yanındaki Insert key menüsü yaygın olanları listeler.
• settext'ten farklı olarak alan önce temizlenmez.
• Odağı taşıyan bir tuştan (örneğin [TAB]) sonraki tuşlar, odağın gittiği yere gönderilir.

İpucu: Bir alanı doldurmak için settext kullanın; kısayollar, zengin metin düzenleyicileri ve her tuş vuruşuna tepki veren alanlar için sendkeys kullanın.

#İlgili sayfalar

• Elementleri güvenilir şekilde bulma: yedek seçiciler, çapalar ve self-healing (kendi kendini onarma).
• Kayıt: kendi tıklamalarınızı ve yazdıklarınızı komutlara dönüştürün.
• Hata işleme: try/catch, yeniden denemeler ve hata ayrıntıları.