نام (NAME)

urlwatch-reporters - گزارش‌دهنده‌ها برای اعلان‌های تغییر

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

urlwatch --edit-config

توضیحات (DESCRIPTION)

به‌طور پیش‌فرض urlwatch(1) اطلاعات مربوط به تغییرات را در خروجی استاندارد چاپ می‌کند که در صورت اجرای تعاملی، همان ترمینال شماست. در صورت اجرا از طریق cron(8) یا سرویس زمان‌بندی دیگر، نحوه نمایش به پیکربندی زمان‌بند بستگی دارد.

می‌توانید یک یا چند گزارش‌دهنده الحاقی را فعال کنید که برای ارسال اعلان‌های تغییر به کار می‌روند. لطفاً توجه داشته باشید که اکثر گزارش‌دهنده‌ها نیازمند نصب وابستگی‌های جانبی هستند.

برای تنظیمات عمومی پیکربندی، urlwatch-config(5) را ببینید.

برای ارسال یک اعلان آزمایشی، از گزینه خط فرمان --test-reporter به همراه نام گزارش‌دهنده استفاده کنید:

urlwatch --test-reporter stdout

این دستور یک گزارش آزمایشی با اعلان‌های new، changed، unchanged و error ایجاد می‌کند (فقط مواردی که در بخش display در پیکربندی تنظیم شده‌اند نمایش داده خواهند شد) و آن را از طریق گزارش‌دهنده stdout (در صورت فعال بودن) ارسال می‌نماید.

برای آزمایش صحت پیکربندی گزارش‌دهنده ایمیل، می‌توانید از دستور زیر استفاده کنید:

urlwatch --test-reporter email

هر گزارش‌دهنده‌ای که پیکربندی و فعال شده باشد، قابل آزمایش است.

اگر ارسال اعلان کار نکرد، پیکربندی خود را بررسی کرده و/یا گزینه خط فرمان --verbose را برای نمایش گزارش‌های اشکال‌زدایی با جزئیات اضافه کنید.

گزارش‌دهنده‌های توکار (BUILT-IN REPORTERS)

فهرست گزارش‌دهنده‌های توکار را می‌توان با استفاده از دستور زیر دریافت کرد:

urlwatch --features

در حال حاضر، گزارش‌دهنده‌های زیر به‌صورت توکار موجود هستند:

discord: ارسال پیام به کانال دیسکورد
email: ارسال خلاصه از طریق ایمیل / SMTP / sendmail
gotify: ارسال پیام به سرور gotify
ifttt: ارسال خلاصه از طریق IFTTT
mailgun: ارسال ایمیل از طریق سرویس Mailgun
matrix: ارسال پیام به یک اتاق با استفاده از پروتکل Matrix
mattermost: ارسال پیام به کانال Mattermost
prowl: ارسال اعلان دقیق از طریق prowlapp.com
pushbullet: ارسال خلاصه از طریق pushbullet.com
pushover: ارسال خلاصه از طریق pushover.net
shell: هدایت (pipe) پیام به یک دستور شل
slack: ارسال پیام به کانال اسلک
stdout: چاپ خلاصه در خروجی استاندارد (کنسول)
telegram: ارسال پیام با استفاده از تلگرام
xmpp: ارسال پیام با استفاده از پروتکل XMPP

سرویس PUSHOVER

می‌توانید urlwatch را برای ارسال اعلان‌های بی‌درنگ درباره تغییرات از طریق Pushover https://pushover.net پیکربندی کنید. برای فعال‌سازی، مطمئن شوید که بسته پایتون chump نصب شده است. سپس فایل پیکربندی خود را ویرایش کرده (urlwatch --edit-config) و pushover را فعال کنید. همچنین باید کلید کاربری Pushover و یک کلید اختصاصی برنامه (تولیدشده با ثبت urlwatch در حساب کاربری Pushover در https://pushover.net/apps/build) را به پیکربندی اضافه نمایید.

می‌توانید با استفاده از نام دستگاه (همان‌طور که در کنسول Pushover هنگام افزودن یا مشاهده دستگاه‌ها نمایش داده می‌شود)، پیام را به یک دستگاه خاص بفرستید؛ برای مثال device: 'MyPhone' یا device: 'MyLaptop'. برای ارسال به تمام دستگاه‌ها، مقدار device: null را در پیکربندی (urlwatch --edit-config) تنظیم کنید یا پیکربندی device را به‌طور کامل حذف نمایید.

تنظیم اولویت از طریق گزینه پیکربندی priority امکان‌پذیر است که می‌تواند lowest، low، normal، high یا emergency باشد. هر مقدار دیگری (شامل خالی گذاشتن آن) به normal نگاشت می‌شود.

سرویس PUSHBULLET

اعلان‌های Pushbullet مشابه Pushover پیکربندی می‌شوند (به بالا مراجعه کنید). شما باید توکن دسترسی Pushbullet خود را که می‌توانید در نشانی https://www.pushbullet.com/#settings تولید کنید، به فایل پیکربندی بیفزایید.

تلگرام (TELEGRAM)

اعلان‌های تلگرام با استفاده از رابط برنامه‌نویسی ربات تلگرام (Telegram Bot API) پیکربندی می‌شوند. برای این کار به یک توکن Bot API و شناسه چت (chat id) نیاز دارید (به https://core.telegram.org/bots مراجعه کنید). نمونه پیکربندی:

telegram:
  bot_token: '999999999:3tOhy2CuZE0pTaCtszRfKpnagOG8IQbP5gf' # your bot api token
  chat_id: '88888888' # the chat id where the messages should be sent
  enabled: true

در صورتی که اعلان‌های بی‌صدا را ترجیح می‌دهید، پیام‌ها می‌توانند به‌صورت بی‌صدا (silent) و همچنین با قالب قلم با عرض ثابت (monospace) ارسال شوند. به‌طور پیش‌فرض اعلان‌ها بی‌صدا نیستند و هیچ قالب‌بندی انجام نمی‌شود.

telegram:
  # ...
  silent: true # message is sent silently
  monospace: true # display message as pre-formatted code block

برای راه‌اندازی تلگرام، از درون برنامه تلگرام خود، با BotFather گفتگو را آغاز کنید (پیام جدید، جستجوی “BotFather”)، سپس عبارت /newbot را بفرستید و دستورالعمل‌ها را دنبال کنید. در نهایت توکن ربات به شما داده می‌شود (در قالب <number>:<random string> همان‌طور که در بالا دیده می‌شود)؛ این مقدار را به فایل پیکربندی خود اضافه کنید.

سپس می‌توانید روی لینک ربات خود کلیک کنید تا پیام /start ارسال شود. در این مرحله می‌توانید از دستور urlwatch --telegram-chats برای فهرست کردن چت‌های خصوصی که ربات در آن‌ها عضو است استفاده نمایید. این همان شناسه چتی است که باید در فایل پیکربندی تحت عنوان chat_id قرار دهید. همچنین می‌توانید چندین شناسه چت را در قالب یک فهرست YAML وارد کنید:

telegram:
  bot_token: '999999999:3tOhy2CuZE0pTaCtszRfKpnagOG8IQbP5gf' # your bot api token
  chat_id:
    - '11111111'
    - '22222222'
  enabled: true

فراموش نکنید که گزارش‌دهنده را نیز فعال نمایید.

اسلک (SLACK)

اعلان‌های اسلک با استفاده از وب‌هوک‌های ورودی اسلک (“Slack Incoming Webhooks”) پیکربندی می‌شوند. نمونه‌ای از پیکربندی:

slack:
  webhook_url: 'https://hooks.slack.com/services/T50TXXXXXU/BDVYYYYYYY/PWTqwyFM7CcCfGnNzdyDYZ'
  enabled: true

برای راه‌اندازی اسلک، از تیم اسلک خود یک برنامه جدید ایجاد کرده و “Incoming Webhooks” را روی یک کانال فعال کنید؛ نشانی اینترنتی وب‌هوک را دریافت کرده و همان‌طور که در بالا نشان داده شده در پیکربندی کپی کنید.

ماترموست (MATTERMOST)

اعلان‌های Mattermost به همان شیوه اعلان‌های Slack راه‌اندازی می‌شوند، نشانی وب‌هوک متفاوت است:

mattermost:
  webhook_url: 'http://{your-mattermost-site}/hooks/XXXXXXXXXXXXXXXXXXXXXX'
  enabled: true

برای جزئیات بیشتر به بخش مستندات ماترموست در https://developers.mattermost.com/integrate/incoming-webhooks مراجعه فرمایید.

دیسکورد (DISCORD)

اعلان‌های دیسکورد با استفاده از وب‌هوک‌های ورودی دیسکورد (“Discord Incoming Webhooks”) پیکربندی می‌شوند. نمونه‌ای از پیکربندی:

discord:
   webhook_url: 'https://discordapp.com/api/webhooks/11111XXXXXXXXXXX/BBBBYYYYYYYYYYYYYYYYYYYYYYYyyyYYYYYYYYYYYYYY'
   enabled: true
   embed: true
   colored: true
   subject: '{count} changes: {jobs}'

برای راه‌اندازی دیسکورد، از بخش تنظیمات سرور دیسکورد خود (Server Settings)، بخش Integration را انتخاب کرده و سپس یک “New Webhook” بسازید، نامی برای انتشار پیام‌ها به آن اختصاص دهید، یک کانال را برگزینید، گزینه “Copy Webhook URL” را بزنید و آن را همانند بالا در فایل پیکربندی جای‌گذاری کنید.

محتوای تعبیه‌شده (Embedded) ممکن است خواندن و تشخیص گزارش‌های مجزا را ساده‌تر سازد. موضوع (Subject) قبل از گزارش تعبیه‌شده قرار می‌گیرد و تنها زمانی استفاده می‌شود که embed برابر با true باشد.

هنگامی که colored برابر true باشد، گزارش‌ها در یک بلوک کد (با ساختار دستوری diff) تعبیه می‌شوند تا رنگ‌ها فعال شوند.

گروه GOTIFY

گروه Gotify در نشانی https://gotify.net سروری برای ارسال و دریافت پیام‌ها به‌صورت بی‌درنگ از طریق وب‌سوکت است.

برای ارسال اعلان‌ها به یک سرور gotify به یک توکن برنامه (application token) نیاز دارید.

می‌توانید یکی از آن‌ها را به این صورت برای urlwatch ایجاد کنید:

1.: به رابط کاربری وب سرور gotify خود وارد شوید.
2.: به برگه “APPS” بروید.
3.: روی دکمه “CREATE APPLICATION” کلیک کنید.

۴. فیلدها را پر کرده و دکمه “CREATE” را فشار دهید. ۶. روی آیکون چشم مدخل تازه‌تأسیس کلیک کرده و توکن را کپی کنید.

نمونه‌ای از پیکربندی:

gotify:
  enabled: true
  priority: 4
  server_url: "http://127.0.0.1:8090"
  title: null
  token: "Aa1yyikLFjEm35A"

سرویس IFTTT

برای پیکربندی رویدادهای IFTTT، باید کلید خود را از اینجا دریافت کنید:

https://ifttt.com/maker_webhooks/settings

نشانی اینترنتی نمایش‌داده‌شده در “Account Info” دارای قالب زیر است:

https://maker.ifttt.com/use/{key}

در این نشانی اینترنتی، {key} کلید API شماست. پیکربندی باید به این شکل باشد (می‌توانید هر نام رویدادی را که مایلید انتخاب کنید):

ifttt:
  enabled: true
  key: aA12abC3D456efgHIjkl7m
  event: event_name_you_want

رویداد شامل سه مقدار در JSON ارسال‌شده خواهد بود:

value1: نوع تغییر (new، changed، unchanged یا error)
value2: نام وظیفه (کلید name در jobs.yaml)
value3: مکان وظیفه (کلید url، command یا navigate در jobs.yaml)

این مقادیر به بخش Action در Recipe شما ارسال خواهند شد.

پروتکل MATRIX

می‌توانید اعلان‌ها را از طریق پروتکل ماتریس https://matrix.org برای خود ارسال کنید.

برای دستیابی به این هدف، ابتدا باید یک حساب Matrix برای ربات در هر سرور خانگی (homeserver) ثبت کنید.

سپس باید با استفاده از دستورالعمل‌های زیر، توکن دسترسی و شناسه اتاق را به دست آورید:

1.: نشانی https://riot.im/app را در یک پنجره مرور خصوصی (Private Browsing) باز کنید.
2.: با استفاده از شناسه کاربری و گذرواژه ربات، به عنوان ربات خود ثبت‌نام کرده/وارد شوید.
3.: در صورت تمایل، نام نمایشی و آواتار را تنظیم کنید.
4.: در صفحه تنظیمات، برگه “Help & About” را انتخاب کنید، به پایین صفحه رفته و روی عبارت Access Token: <click to reveal> کلیک کنید.
5.: متن نمایان‌شده را در پیکربندی خود کپی کنید.
6.: به اتاقی که مایلید اعلان‌ها به آن ارسال شود ملحق شوید.
7.: به بخش Room Settings (آیکون چرخ‌دنده) رفته و مقدار Internal Room ID را از پایین صفحه کپی نمایید.
8.: پنجره مرور خصوصی را ببندید، اما از حساب خارج (Log out) نشوید، زیرا این کار توکن دسترسی را باطل می‌کند.

نمونه‌ای از پیکربندی:

matrix:
  homeserver: https://matrix.org
  access_token: "YOUR_TOKEN_HERE"
  room_id: "!roomroomroom:matrix.org"
  enabled: true

اگر قصد دارید اعلان‌های تغییر را در یک اتاق عمومی Matrix منتشر کنید، احتمالاً تمایل خواهید داشت از پیکربندی زیر برای گزارش‌دهنده markdown استفاده نمایید، زیرا پیام‌ها به‌سرعت شلوغ و پر سر و صدا می‌شوند:

markdown:
  details: false
  footer: false
  minimal: true
  enabled: true

ایمیل از طریق SENDMAIL

می‌توانید با استفاده از دستور sendmail ارائه‌شده توسط MTA سیستم، ایمیل بفرستید. باید مقدار method: sendmail را در فایل پیکربندی تنظیم کنید:

report:
  email:
    enabled: true
    from: 'postmaster@example.com'
    to: 'recipient@bar.com'
    method: sendmail

ایمیل از طریق GMAIL SMTP

باید حساب کاربری GMail خود را به گونه‌ای پیکربندی کنید که به برنامه‌های «کم‌امنیت‌تر» (مبتنی بر گذرواژه) اجازه ورود دهد:

1.: به نشانی https://myaccount.google.com بروید.
2.: روی “Sign-in & security” کلیک کنید.
3.: به پایین صفحه به بخش “Allow less secure apps” رفته و آن را فعال کنید.

شما نباید این کار را روی حساب اصلی جیمیل خود انجام دهید، بلکه روی حساب جداگانه‌ای که فقط برای ارسال نامه‌های urlwatch ایجاد می‌کنید این کار را بکنید. مجاز کردن برنامه‌های با امنیت کمتر و ذخیره گذرواژه برای حساب اصلی شما یک رویه امنیتی خوب نیست.

اکنون، ویرایشگر پیکربندی را باز کنید:

urlwatch --edit-config

این‌ها کلیدهایی هستند که باید پیکربندی کنید:

report:
  email:
    enabled: true
    from: your.username@gmail.com
    to: your.destination.email@example.com
    method: smtp
    smtp:
      host: smtp.gmail.com
      auth: true
      port: 587
      starttls: true

بهتر است گذرواژه در جاکلیدی (keychain) شما ذخیره شود و نه در فایل پیکربندی. برای ذخیره گذرواژه، دستور زیر را اجرا کنید:

urlwatch --smtp-login

این دستور گذرواژه شما را جویا شده، ورود به سیستم را اعتبارسنجی کرده و آن را در جاکلیدی شما ذخیره می‌کند. اجراهای بعدی از این گذرواژه برای ورود استفاده خواهند کرد.

ایمیل از طریق سرویس AMAZON SES

مشابه پیکربندی GMail در بالا است، اما برای مثال از email-smtp.us-west-2.amazonaws.com به عنوان میزبان SMTP، و تنظیمات نام کاربری و پورت مطابق با صفحه ورود SES استفاده کنید.

ورود به SMTP بدون جاکلیدی (SMTP LOGIN WITHOUT KEYRING)

اگر به هر دلیلی نمی‌توانید از یک جا‌کلیدی برای ذخیره گذرواژه خود استفاده کنید (به عنوان مثال، هنگام اجرای آن از طریق یک تسک cron)، می‌توانید گزینه insecure_password را در پیکربندی SMTP تنظیم نمایید:

report:
  email:
    smtp:
      auth: true
      insecure_password: secret123

کلید insecure_password نسبت به داده‌های ذخیره‌شده در جاکلیدی اولویت خواهد داشت. توجه داشته باشید همان‌طور که از نام آن مشخص است، ذخیره گذرواژه به‌صورت متن آشکار در فایل پیکربندی ناامن بوده و روش نادرستی است، اما برای یک حساب ایمیل که صرفاً برای ارسال ایمیل‌ها اختصاص یافته، ممکن است یک راهکار باشد. هرگز و تحت هیچ شرایطی از این گزینه برای حساب اصلی ایمیل خود استفاده نکنید! واقعاً! یک حساب یک‌بارمصرف جیمیل (یا سرویس دیگر) بسازید یا از sendmail محلی به همراه یک میل‌سرور پیکربندی‌شده استفاده کنید.

توجه داشته باشید که این کار باعث می‌شود استخراج گذرواژه شما توسط نرم‌افزارهای در حال اجرا روی سیستم، توسط سایر کاربران واردشده به سیستم و یا ثبت تصادفی در فایل‌های گزارش وقایع بسیار آسان شود.

پروتکل XMPP

می‌توانید اعلان‌ها را از طریق پروتکل XMPP دریافت کنید.

برای انجام این کار، باید یک حساب XMPP جدید ثبت کنید که فقط برای urlwatch استفاده شود.

نمونه‌ای از پیکربندی:

xmpp:
  enabled: true
  sender: "BOT_ACCOUNT_NAME"
  recipient: "YOUR_ACCOUNT_NAME"

گذرواژه در فایل پیکربندی ذخیره نمی‌شود، بلکه در جاکلیدی شما نگهداری می‌شود. جهت ذخیره گذرواژه، دستور urlwatch --xmpp-login را اجرا کرده و گذرواژه خود را وارد کنید.

اگر به هر دلیلی نمی‌توانید از یک جاکلیدی برای ذخیره گذرواژه خود استفاده نمایید، می‌توانید گزینه insecure_password را در پیکربندی XMPP قرار دهید. برای اطلاعات بیشتر در خصوص پیامدهای امنیتی، بخش «ورود به SMTP بدون جاکلیدی» را ببینید.

سرویس PROWL

می‌توانید از طریق سرویس اعلان لحظه‌ای (push notification) Prowl اعلان‌ها را دریافت کنید تا روی دستگاه‌های با سیستم‌عامل iOS نمایش داده شوند.

برای دستیابی به این هدف، باید یک حساب کاربری جدید در Prowl ثبت کرده و برنامه Prowl را روی دستگاه iOS خود نصب کرده باشید.

جهت ساخت یک کلید API برای urlwatch:

1.: به وب‌سایت Prowl در نشانی https://prowlapp.com وارد شوید.
2.: به برگه “API Keys” بروید.
3.: به بخش “Generate a new API key” پیمایش کنید.
4.: یک یادداشت برای کلید بگذارید تا به شما یادآوری کند از آن برای urlwatch استفاده کرده‌اید.
5.: دکمه “Generate Key” را فشار دهید.
6.: کلید حاصل را کپی نمایید.

نمونه‌ای از پیکربندی:

prowl:
  enabled: true
  api_key: '<your api key here>'
  priority: 2
  application: 'urlwatch example'
  subject: '{count} changes: {jobs}'

فیلد “subject” مشابه با فیلد موضوع در ایمیل است و به عنوان نام رویداد Prowl استفاده خواهد شد. مقدار application به رویداد افزوده شده و در برنامه Prowl به عنوان منبع رویداد نشان داده می‌شود.

شل (SHELL)

این یک گزارش‌دهنده ساده است که اعلان گزارش متنی را به یک دستور به انتخاب شما هدایت (pipe) می‌کند. این دستور با استفاده از تابع پایتون subprocess.Popen() با آرگومان shell=False (برای جلوگیری از بسط ناخواسته شل) اجرا می‌شود. البته می‌توانید اسکریپت شل اختصاصی خود را بسازید و آن را از طریق command فراخوانی کنید.

کلید ignore_stdout (پیش‌فرض: true) می‌تواند برای نادیده گرفتن هرگونه خروجی برنامه در خروجی استاندارد استفاده شود. کلید ignore_stderr (پیش‌فرض: false) می‌تواند برای نادیده گرفتن هرگونه خروجی برنامه در خطای استاندارد استفاده شود.

اگر stdout/stderr نادیده گرفته نشوند، urlwatch هر خروجی احتمالی را در لاگ‌های --verbose خود ثبت می‌کند.

گزارشی که به ورودی استاندارد (stdin) فرآیند فرستاده می‌شود بر اساس خروجی گزارش‌دهنده text است؛ پیکربندی گزارش‌دهنده متنی داده‌های ارسالی به گزارش‌دهنده shell را تنظیم می‌کند.

برای مثال، برای افزودن ساده گزارش‌ها به انتهای یک فایل، آن را به این صورت پیکربندی کنید:

shell:
  enabled: true
  command: ['tee', '-a', '/path/to/log.txt']
  ignore_stdout: true

فایل‌ها (FILES)

$XDG_CONFIG_HOME/urlwatch/urlwatch.yaml

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

urlwatch(1), urlwatch-config(5), urlwatch-intro(7), urlwatch-cookbook(7)

حق نشر (COPYRIGHT)

2024 Thomas Perl