نام (NAME)

urlwatch-jobs - انواع وظایف و پیکربندی برای urlwatch

خلاصه دستور (SYNOPSIS)

urlwatch --edit

توضیحات (DESCRIPTION)

وظایف (Jobs) مواردی هستند که urlwatch(1) می‌تواند بر آن‌ها نظارت کند.

فهرست وظایف جهت اجرا در فایل پیکربندی urls.yaml قرار دارد که با دستور urlwatch --edit قابل دسترسی است و هر وظیفه با خطی که تنها شامل --- است از وظیفه دیگر جدا می‌شود. دستور urlwatch --list نام هر وظیفه را به همراه شماره اندیس آن (1, 2, 3, ...) که بر اساس موقعیت آن در فایل پیکربندی به صورت خودکار تخصیص داده می‌شود، چاپ می‌کند.

هرچند اختیاری است، اما توصیه می‌شود که هر وظیفه با یک مدخل name شروع شود:

name: "این یک نام/برچسب خوانا برای انسان از وظیفه است"

انواع وظایف زیر در دسترس هستند:

نشانی وب (URL)

این نوع اصلی وظیفه است -- سندی را از یک کارساز وب دریافت می‌کند:

name: "urlwatch homepage"
url: "https://thp.io/2008/urlwatch"

کلیدهای الزامی:

•: url: نشانی وب سندی که باید برای تغییرات پایش شود

کلیدهای اختیاری مختص این نوع وظیفه:

cookies: کوکی‌هایی که همراه با درخواست ارسال می‌شوند (به مباحث پیشرفته مراجعه کنید)
method: متد HTTP مورد استفاده (پیش‌فرض: GET)
data: داده‌های HTTP POST/PUT
ssl_no_verify: اعتبارسنجی نکردن گواهی‌های SSL (true/false)
ignore_cached: استفاده نکردن از مقادیر کنترل حافظه موقت (ETag/Last-Modified) (true/false)
http_proxy: سرور پروکسی مورد استفاده برای درخواست‌های HTTP (می‌تواند http:// یا socks5:// باشد)
https_proxy: سرور پروکسی مورد استفاده برای درخواست‌های HTTPS (می‌تواند http:// یا socks5:// باشد)
headers: هدرهای HTTP که باید همراه با درخواست ارسال شوند
encoding: بازنویسی رمزگذاری نویسه‌ها از سمت سرور (به مباحث پیشرفته مراجعه کنید)
timeout: بازنویسی مهلت زمانی (timeout) پیش‌فرض سوکت (به مباحث پیشرفته مراجعه کنید)
ignore_connection_errors: نادیده گرفتن خطاهای اتصال (موقتی) (به مباحث پیشرفته مراجعه کنید)
ignore_http_error_codes: فهرستی از کدهای خطای HTTP برای نادیده گرفته شدن (به مباحث پیشرفته مراجعه کنید)
ignore_timeout_errors: گزارش نکردن خطا در زمان رسیدن به مهلت زمانی (timeout)
ignore_too_many_redirects: نادیده گرفتن حلقه‌های تغییر مسیر (redirect loops) (به مباحث پیشرفته مراجعه کنید)
ignore_incomplete_reads: نادیده گرفتن پاسخ‌های ناقص HTTP (به مباحث پیشرفته مراجعه کنید)

(توجه: وجود url بیانگر kind: url است)

مرورگر (BROWSER)

این نوع وظیفه نوعی منبع‌بر از وظیفه "URL" است که برای مدیریت صفحاتی به کار می‌رود که نیازمند جاوااسکریپت برای رندر محتوای تحت پایش هستند.

بسته اختیاری playwright باید نصب باشد تا بتوان وظایف مرورگر را اجرا کرد. همچنین باید مرورگرها را با استفاده از playwright install نصب کنید (برای جزئیات به مستندات پلی‌رایت مراجعه کنید).

name: "یک صفحه دارای جاوااسکریپت"
navigate: "https://example.org"

کلیدهای الزامی:

•: navigate: نشانی وب برای پیمایش با مرورگر

کلیدهای اختیاری مختص این نوع وظیفه:

wait_until: یکی از موارد load، domcontentloaded، networkidle، یا commit (به مباحث پیشرفته مراجعه کنید)
wait_for: یک انتخاب‌گر CSS یا XPath. این وظیفه به اندازه مهلت زمانی پیش‌فرض ۳۰ ثانیه منتظر خواهد ماند.
useragent: هدر User-Agent برای درخواست‌ها (در غیر این صورت از پیش‌فرض مرورگر استفاده می‌شود)
browser: یکی از گزینه‌های chromium، chrome، chrome-beta، msedge، msedge-beta، msedge-dev، firefox، webkit (باید از طریق playwright install نصب شده باشند)

از آنجا که این نوع وظیفه از Playwright برای رندر صفحه در یک مرورگر بدون رابط کاربری (headless) استفاده می‌کند، منابع به مراتب بیشتری نسبت به وظیفه "URL" مصرف می‌کند. تنها در صفحاتی از آن استفاده کنید که url نتایج صحیح را برنمی‌گرداند. در بسیاری از موارد، به جای استفاده از وظیفه "Browser"، می‌توانید از خروجی یک API که صفحه هنگام بارگذاری فراخوانی می‌کند استفاده کنید که اطلاعات مورد نظر شما را در بر دارد و از طریق وظیفه بسیار سریع‌تر "URL" قابل دریافت است.

(توجه: وجود navigate بیانگر kind: browser است)

پوسته (SHELL)

این نوع وظیفه به شما امکان می‌دهد بر خروجی دستورات دلخواه پوسته نظارت کنید، که مثلاً برای مانیتور کردن پوشه آپلودر FTP، خروجی اسکریپت‌هایی که دستگاه‌های خارجی (RPi GPIO) را بررسی می‌کنند و غیره مفید است...

name: "محتویات دایرکتوری خانگی من چیست؟"
command: "ls -al ~"

کلیدهای الزامی:

•: command: دستور پوسته‌ای که باید اجرا شود

کلیدهای اختیاری مختص این نوع وظیفه:

•: stderr: تغییر نحوه برخورد با خروجی خطای استاندارد، به بخش زیر مراجعه کنید

(توجه: وجود command بیانگر kind: shell است)

پیکربندی رفتار stderr برای وظایف پوسته

به طور پیش‌فرض urlwatch خروجی stderr را برای گزارش خطا (کد خروج غیر صفر) ضبط می‌کند، اما در صورتی که وظیفه پوسته با کد خروج 0 خارج شود، این خروجی را نادیده می‌گیرد.

این رفتار با استفاده از کلید stderr قابل سفارشی‌سازی است:

ignore: ضبط stderr، گزارش در صورت کد خروج غیر صفر، و نادیده گرفتن در غیر این صورت (پیش‌فرض)
urlwatch: خروجی stderr وظیفه پوسته به stderr فرآیند urlwatch ارسال می‌شود؛ هیچ پیام خطایی در خروجی خطای استاندارد در پیام خطای گزارشگر نمایش داده نخواهد شد (رفتار پیش‌فرض قدیمی urlwatch نسخه 2.24 و قبل‌تر)
fail: ناموفق قلمداد کردن وظیفه در صورت وجود هرگونه خروجی در stderr، حتی با کد وضعیت خروج 0
stdout: ادغام خروجی stderr در stdout، به این معنی که خروجی خطای استاندارد نیز در بخش تشخیص تغییرات/diff برنامه urlwatch لحاظ می‌شود (مشابه 2>&1 در پوسته)

برای مثال، این تعریف وظیفه باعث می‌شود وظیفه ناموفق به نظر برسد، حتی اگر اسکریپت با کد خروج 0 پایان یابد:

command: |
  echo "خروجی استاندارد معمولی."
  echo "مقداری متن در stderr که باعث شکست این وظیفه می‌شود." 1>&2
  exit 0
stderr: fail

از طرف دیگر، اگر می‌خواهید هر دو خروجی استاندارد و خطای استاندارد وظیفه را مقایسه (diff) کنید، از این پیکربندی استفاده نمایید:

command: |
  echo "یک خط مهم در stdout."
  echo "یک خط مهم دیگر در stderr." 1>&2
stderr: stdout

کلیدهای اختیاری برای تمام انواع وظایف

name: نام/برچسب خوانا برای انسان از وظیفه
tags: آرایه‌ای از برچسب‌ها، یا یک تک‌برچسب به عنوان رشته متنی
filter: فیلترها (در صورت وجود) برای اعمال روی خروجی (با --test-filter قابل آزمایش است)
max_tries: پس از این تعداد اجرای ناموفق متوالی، خطا به جای نادیده گرفته شدن گزارش خواهد شد
diff_tool: دستور ابزار سفارشی برای تولید متن تغییرات (diff)
diff_filter: فیلترها (در صورت وجود) برای اعمال روی نتیجه تغییرات (با --test-diff-filter قابل آزمایش است)
treat_new_as_changed: وظایفی که هیچ داده تاریخی قبلی ندارند را به جای NEW به عنوان CHANGED در نظر می‌گیرد (و برای وظایف جدید فایل تغییرات ایجاد می‌کند)
compared_versions: تعداد نسخه‌ها برای مقایسه شباهت
kind (تکراری/افزونه): یکی از مقادیر url، shell یا browser. به صورت خودکار از روی کلید اختصاصی نوع وظیفه (url، command یا navigate) مشتق می‌شود
user_visible_url: نشانی وب متفاوتی برای نمایش در گزارش‌ها (مثلاً زمانی که نشانی مورد پایش یک REST API است، و می‌خواهید یک صفحه وب را نشان دهید)
enabled: می‌تواند روی false تنظیم شود تا یک وظیفه منفرد غیرفعال گردد (پیش‌فرض true است)

تنظیم کلیدها برای همه وظایف به طور همزمان

فایل اصلی پیکربندی شامل کلیدی به نام job_defaults است که می‌تواند برای پیکربندی کلیدها برای تمام وظایف به صورت یکجا استفاده شود.

برای نحوه پیکربندی مقادیر پیش‌فرض وظایف، به urlwatch-config(5) مراجعه کنید.

مثال‌ها (EXAMPLES)

برای مشاهده مثال‌های پیکربندی وظایف به urlwatch-cookbook(7) مراجعه کنید.

فایل‌ها (FILES)

$XDG_CONFIG_HOME/urlwatch/urls.yaml

همچنین ببینید (SEE ALSO)

urlwatch(1), urlwatch-intro(5), urlwatch-filters(5)

حق نشر (COPYRIGHT)

2024 Thomas Perl