کلیدهای دسترسی و سطح دسترسی
برای هر یکپارچه‌سازی (دروازه، اسکریپت، سامانهٔ دیگر) کلید پروژه با کمترین سطح لازم بسازید، آن را به پروژه وصل یا از آن جدا کنید، در صورت افشا غیرفعال کنید و بدانید سرور برای هر سطح دقیقاً چه اجازه‌ای می‌دهد.
کنسول مدیریت سرور: «System Design» ← «Projects» ← بخش «API Key Management»؛ در برنامهٔ وب: «تنظیمات» ← «تنظیمات پروژه» ← زبانهٔ «اتصال سرور»
هر درخواست به سرور همزاد دیجیتال با یک «کلید پروژه» همراه است. سطح همین کلید است که در سرور تعیین می‌کند درخواست فقط بخواند، بنویسد یا به تجهیز فرمان بدهد. کاربران وب پس از ورود خودکار کلید پروژه را دریافت می‌کنند؛ اما هر دستگاه یا سامانهٔ بیرونی باید کلید جداگانهٔ خودش را داشته باشد. مدیریت کلیدها در کنسول مدیریت سرور انجام می‌شود و برچسب‌های آن انگلیسی است.
صفحه را بشناسید
| بخش | آنچه می‌بینید |
|---|---|
| کارت‌ها | Total Keys، Active Keys، Expired Keys؛ دکمه‌های Generate New Key و Refresh |
| جدول All API Keys | ستون‌های ID، Key Name، Key Value (پوشیده)، Status، Assigned To، Created و Actions با دکمه‌های Assign و Deactivate |
| بخش Keys by Project | فهرست Select Project: و جدول کلیدهای پروژه با ستون Access Level و Last Used و دکمهٔ Remove |
| برنامهٔ وب، زبانهٔ اتصال سرور | کد پروژه *، کلید API * (پوشیده)، آدرس سرور API *، آدرس WebSocket * و تست اتصال |
سطح‌ها و آنچه سرور اجازه می‌دهد
| سطح در کنسول | خواندن | نوشتن (ثبت و ویرایش) | فرمان به تجهیز | API دستگاه‌ها (دروازه) | کارهای مدیریتی |
|---|---|---|---|---|---|
Master (Full Access) | بله | بله | بله | بله | بله |
System (Read/Write/Manage) | بله | بله | بله | بله | خیر |
User Level 1 (Read/Write) | بله | بله | بله | خیر | خیر |
User Level 2 (Read Only) | بله | بله | خیر | خیر | خیر |
User Level 3 (Limited Read) | بله | خیر | خیر | خیر | خیر |
User Level 3 بدهید.کلید پروژه با حساب کاربری فرق دارد
حساب کاربری برای انسان است و با نام کاربری و رمز کار می‌کند؛ کلید پروژه برای ماشین است و در هر درخواست همراه می‌رود. کاربر واردشده هم پشت صحنه با کلید پروژه کار می‌کند، اما آن کلید را نمی‌بیند و نمی‌تواند سطحش را عوض کند. پس اگر می‌خواهید یک دروازه، اسکریپت یا نمایشگر دیواری به سامانه وصل شود، برای آن حساب کاربری نسازید؛ کلید جدا با کمترین سطح لازم بسازید. برعکس، برای یک همکار تازه کلید نسازید؛ او باید حساب کاربری و نقش داشته باشد (درس C1).
گام‌به‌گام
- کلید تازه بسازید. در کنسول سرور به «System Design» ← «Projects» بروید و تا بخش API Key Management پایین بیایید. Generate New Key را بزنید. Key Name * را گویا بنویسید (مثلاً «دروازهٔ ساختمان ب — خواندن»)؛ Description اختیاری است. برای کلیدهای موقت حتماً Expiration Date (Optional) بگذارید؛ خالی یعنی بدون انقضا.
- پروژه و سطح را تعیین کنید. در بخش Assign to Project (Optional) پروژه را انتخاب کنید تا Access Level * ظاهر شود؛ کمترین سطحی را برگزینید که کار با آن انجام می‌شود (پیش‌فرض User Level 1 است). سپس Generate Key.
- کلید را امن نگه دارید. در کادر Key Generated Successfully! با Copy مقدار را کپی و فوراً در مدیر رمز سازمان ذخیره کنید. در هر مستند، کلید را فقط به‌صورت «XXXX…» بنویسید.
- کلید موجود را به پروژهٔ دیگر وصل کنید. در جدول All API Keys روی Assign بزنید، Project * و Access Level * را انتخاب و Assign to Project را بزنید. اگر همان کلید قبلاً به همان پروژه وصل باشد، سرور خطا می‌دهد.
- کلید را از یک پروژه جدا کنید. در Keys by Project پروژه را انتخاب کنید و در ردیف کلید Remove را بزنید. کلید برای پروژه‌های دیگر همچنان کار می‌کند.
- کلید افشاشده را از کار بیندازید. در All API Keys روی Deactivate بزنید و پیام تأیید را بپذیرید؛ کلید برای همهٔ پروژه‌ها از کار می‌افتد. بلافاصله کلید جانشین بسازید و در دستگاه یا سامانهٔ یکپارچه جایگزین کنید.
- اتصال مرورگر را آزمایش کنید. در برنامهٔ وب «تنظیمات» ← «تنظیمات پروژه» ← «اتصال سرور» را باز کنید و تست اتصال را بزنید. اگر فیلدی خالی باشد پیام «لطفاً همه فیلدهای الزامی را پر کنید» و در شکست «تست اتصال ناموفق بود» می‌آید.
اتصال سرور · کلید API پوشیده است؛ دکمهٔ تست اتصال و نتیجهٔ API و WebSocket
روال چرخش کلید
کلیدها را مثل رمز عبور مدیریت کنید: یک فهرست از کلیدهای فعال، صاحب هر کلید (کدام دستگاه یا سامانه)، سطح و تاریخ انقضا نگه دارید. برای چرخش بدون قطعی، اول کلید تازه بسازید و به همان پروژه با همان سطح وصل کنید، سپس آن را در مصرف‌کننده جایگزین کنید، با ستون Last Used مطمئن شوید کلید تازه کار می‌کند و تنها بعد از آن کلید قدیمی را Deactivate کنید. اگر کلیدی افشا شده، ترتیب برعکس است: اول Deactivate، بعد جایگزینی.
نکته‌ها و اشتباه‌های رایج
- برای هر مصرف‌کننده کلید جدا بسازید تا در صورت افشا فقط همان را غیرفعال کنید.
- کلید Master پروژه را به دستگاه یا سامانهٔ بیرونی ندهید؛ همان کلیدی است که کاربران وب با آن کار می‌کنند. اگر آن را غیرفعال کنید و کلید فعال دیگری برای پروژه نماند، ورود کاربران با پیام «کلید API فعال یافت نشد» رد می‌شود.
- Deactivate روی همهٔ پروژه‌ها اثر دارد؛ برای قطع از یک پروژه Remove بزنید.
- کلید منقضی بی‌درنگ از کار می‌افتد؛ پیش از تاریخ انقضا کلید جانشین بسازید و در تقویم نگهداری ثبت کنید.
- مقدار کامل کلید از جدول هم کپی‌شدنی است؛ دسترسی به کنسول سرور را فقط به مدیران مورد اعتماد بدهید.
- کلید را هرگز در ایمیل، پیام‌رسان، تیکت، تصویر صفحه یا مخزن کد نگذارید.
خلاصه
- سطح کلید پروژه، اجبار واقعی دسترسی در سرور است.
- فقط‌خواندنی واقعی = User Level 3؛ دروازهٔ داده = System.
- Remove یک پروژه را قطع می‌کند؛ Deactivate کلید را همه‌جا از کار می‌اندازد.
- کلید را یک بار کپی و در مدیر رمز نگه دارید؛ برای کلیدهای موقت انقضا بگذارید.
تمرین عملی روی دموی زنده
کنسول سرور روی دموی عمومی در اختیار عموم نیست؛ تمرین را در برنامهٔ وب دمو (bms.argsrv.com، پروژهٔ «هولدینگ ارگ») و روی کاغذ انجام دهید. هیچ مقداری را تغییر یا ذخیره نکنید.
- «تنظیمات» ← «تنظیمات پروژه» ← «اتصال سرور» را باز کنید؛ ببینید کلید API * پوشیده است. آن را آشکار یا برای کسی ارسال نکنید. تست اتصال را بزنید و نتیجهٔ API و WebSocket را یادداشت کنید.
- برای سه سناریو سطح مناسب را بنویسید و دلیل بیاورید: (الف) نمایشگر دیواری فقط‌نمایشی، (ب) دروازهٔ میدانی که مقدار نقطه‌ها را می‌فرستد، (ج) اسکریپت گزارش‌گیری که دارایی ثبت می‌کند.
- پاسخ خود را با جدول سطح‌ها مقایسه کنید (پاسخ پیشنهادی: User Level 3، System، User Level 1).
آزمون درس
برای گذراندن درس دست‌کم به ۳ پرسش از ۴ پرسش پاسخ درست بدهید.
- ۱. کدام سطح می‌تواند به تجهیز فرمان بدهد ولی API دستگاه‌ها را صدا نمی‌زند؟
- ۲. برای کلیدی که واقعاً هیچ تغییری نتواند ثبت کند، کدام سطح درست است؟
- ۳. تفاوت Remove و Deactivate چیست؟
- ۴. هنگام ساخت پروژهٔ تازه کدام کلید خودکار ساخته می‌شود؟