کلیدها و اسرار

پیش از استفاده Keys, پروژه را به Atoms Cloud. اگر متصل نیست، از Agent بخواهید Atoms Cloud را متصل کند یا این مورد را دنبال کنید Atoms Cloud.

استفاده از یک کلید در Atoms Cloud

پیش از شروع

پیش از افزودن یک کلید، مطمئن شوید که:

• از Atoms در وب دسکتاپ استفاده می‌کنید.
• پروژه به این مورد متصل است Atoms Cloud.
• شما مالک workspace هستید. فقط مالکان workspace می‌توانند کلیدهای جدید اضافه کنند.

اگر Keys یا New Key در دسترس نیست، تأیید کنید که پروژه موردنظر را باز کرده‌اید و به این مورد متصل است Atoms Cloud. اگر New Key همچنان در دسترس نیست، تأیید کنید که مالک workspace هستید. اگر Atoms پیام مربوط به در دسترس بودن طرح یا میزان استفاده را نشان می‌دهد، مسیر در دسترس بودن یا ارتقا روی صفحه را دنبال کنید، سپس دوباره تلاش کنید.

افزودن یک کلید Test

1. پروژه را روی یک دستگاه دسکتاپ باز کنید.
2. در همان نوار ابزار workspace که App Viewer قرار دارد، این مورد را انتخاب کنید Atoms Cloud.
3. انتخاب کنید Keys در نوار کناری Atoms Cloud.
4. باز کنید Test Keys, سپس این مورد را انتخاب کنید In This Project.
5. انتخاب کنید New Key.
6. فیلدهای الزامی را کامل کنید:
   • Name: یک نام مرجع واضح وارد کنید، مانند RESEND_API_KEY. از حروف، اعداد و زیرخط استفاده کنید و با یک حرف یا زیرخط شروع کنید.
   • Value: اعتبارنامه را دقیقاً همان‌طور که توسط ارائه‌دهنده داده شده وارد کنید.
   • Description: توضیح دهید این کلید برای چه کاری است، مانند برای ارسال ایمیل‌های حساب استفاده می‌شود. مقدار اعتبارنامه را وارد نکنید.
7. اگر می‌خواهید از این کلید در پروژه‌های دیگر دوباره استفاده کنید، این مورد را انتخاب کنید Save to Library.
8. انتخاب کنید افزودن. وقتی کلید ذخیره شد، Atoms این مورد را نشان می‌دهد Key added successfully.

افزودن یک کلید Test

فقط مالکان workspace می‌توانند کلیدهای جدید اضافه کنند. اگر نیاز دارید کلیدی اضافه شود، از یک مالک workspace بخواهید.

استفاده از یک کلید ذخیره‌شده در Chat

به‌جای وارد کردن مقدار کلید در پیام، به کلید ذخیره‌شده ارجاع دهید.

1. پروژه را باز کنید Chat در نسخه دسکتاپ Atoms و این را تایپ کنید #.
2. انتخاب کنید Keys.
3. کلید ذخیره‌شده را جستجو کنید، سپس نام آن را انتخاب کنید.
4. به Agent بگویید کلید برای چه کاری است و می‌خواهید یکپارچه‌سازی چه کاری انجام دهد.

منوی # یک ارجاع به کلید ذخیره‌شده اضافه می‌کند بدون اینکه مقدار آن را در پیام شما وارد کند.

ارجاع به یک کلید ذخیره‌شده در Chat

آزمایش یک کلید ذخیره‌شده

1. در App Viewer, یک اقدام ساده انجام دهید که از کلید استفاده کند.
2. تأیید کنید که نتیجه مورد انتظار را تولید می‌کند، مانند ارسال یک ایمیل آزمایشی یا بازگرداندن داده‌های آزمایشی.
3. هر خطا یا گزارش قابل‌مشاهده را بررسی کنید و مطمئن شوید که مقدار کلید را افشا نمی‌کنند.

اگر سرویس به شما کلیدهای آزمایشی و زنده جداگانه می‌دهد، هنگام ساخت برنامه‌تان از کلید آزمایشی استفاده کنید. فقط پس از انتشار برنامه از کلید زنده استفاده کنید. اگر آزمایش شکست خورد، داشبورد ارائه‌دهنده را بررسی کنید تا تأیید شود کلید فعال است و مجوز انجام اقدام درخواستی را دارد. هنگام عیب‌یابی، هرگز مقدار کلید را در Chat جای‌گذاری نکنید.

درک نحوه کار Keys

پیش از افزودن کلیدها، بهتر است بدانید Atoms چه چیزی را ذخیره می‌کند و چگونه از اعتبارنامه‌های خود محافظت کنید.

آنچه Atoms ذخیره می‌کند

Atoms Cloud → Keys اعتبارنامه‌هایی را ذخیره می‌کند که برنامه شما برای اتصال به سرویس‌های خارجی استفاده می‌کند، مانند کلیدهای API و توکن‌های دسترسی.

هر کلید ذخیره‌شده یک نام، توضیح و مقدار خصوصی دارد. نام و توضیح به Agent کمک می‌کنند بفهمد چه زمانی از کلید استفاده کند، در حالی که مقدار خصوصی از دید پنهان می‌ماند Chat.

کلید را از کجا بگیرید

Atoms برای سرویس‌های خارجی اعتبارنامه ایجاد یا ارائه نمی‌کند. باید آن‌ها را از ارائه‌دهنده سرویس مربوطه دریافت کنید. هنگام انتخاب مجوزها، آزمایش کلید و بررسی اینکه آیا منقضی می‌شود یا نه، دستورالعمل‌های ارائه‌دهنده را دنبال کنید.

اعتبارنامه‌های خصوصی را محرمانه نگه دارید

هرگز یک اعتبارنامه خصوصی را در Chat, کد منبع، کدی که در مرورگر اجرا می‌شود، اسکرین‌شات‌ها، گزارش‌ها یا پیام‌های پشتیبانی جای‌گذاری نکنید. آن را در Keys, ذخیره کنید، سپس با نام به ورودی ذخیره‌شده ارجاع دهید.

اگر یک مقدار خصوصی قبلاً افشا شده است، آن را در معرض خطر تلقی کنید و از طریق ارائه‌دهنده آن را لغو یا جایگزین کنید.

اعتبارنامه‌های خصوصی و امن برای مرورگر

Keys مقادیر ذخیره‌شده را با برچسب‌های Public یا Private. ذخیره کردن یک مقدار در Keys به‌طور خودکار آن را برای استفاده در کدی که در معرض مرورگر است ایمن نمی‌کند. اگر برنامه شما از این مقدار در مرورگر استفاده کند، بازدیدکنندگان ممکن است بتوانند آن را بررسی کنند.

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

• فقط زمانی از یک مقدار در کدی که در معرض مرورگر است استفاده کنید که ارائه‌دهنده صراحتاً اعلام کرده باشد افشای آن امن است.
• اعتبارنامه‌های خصوصی را در منطق سمت سرور یا backend نگه دارید، جایی که در معرض بازدیدکنندگان برنامه قرار نمی‌گیرند.

محیط و محل ذخیره‌سازی کلید را انتخاب کنید

هنگام افزودن یک کلید، باید دو تصمیم جداگانه بگیرید:

• اینکه کدام محیط از کلید استفاده خواهد کرد.
• اینکه کلید در همین پروژه باقی بماند یا برای پروژه‌های دیگر هم در دسترس باشد.

یک محیط انتخاب کنید

گزینه	زمان استفاده
Test Keys	هنگام توسعه و آزمایش برنامه‌تان در App Viewer. اگر یک مقدار Production جداگانه اضافه نکنید، برنامه منتشرشده نیز از مقدار Test استفاده خواهد کرد.
Production Keys	توسط برنامه منتشرشده استفاده می‌شود وقتی به یک اعتبارنامه زنده جداگانه نیاز دارد. مقادیر Production در فرایند انتشار اضافه می‌شوند و جدا از مقادیر Test مدیریت می‌شوند.

محل ذخیره کلید را انتخاب کنید

گزینه	زمان استفاده از آن
In This Project	این گزینه را برای کلیدی انتخاب کنید که باید فقط توسط پروژه فعلی استفاده شود.
Key Library	وقتی عمداً می‌خواهید از یک کلید در چندین پروژه دوباره استفاده کنید، این گزینه را انتخاب کنید. هنگام افزودن یا به‌روزرسانی یک کلید Test، Save to Library را انتخاب کنید تا در کتابخانه در دسترس باشد.

محیط و محل ذخیره‌سازی مستقل از یکدیگر هستند. ذخیره کردن یک کلید Test در Key Library آن را قابل استفاده مجدد می‌کند، اما آن را به مقدار Production تبدیل نمی‌کند.

به‌طور پیش‌فرض از In This Project استفاده کنید. فقط زمانی یک کلید را در کتابخانه ذخیره کنید که مطمئن باشید باید بین پروژه‌ها به اشتراک گذاشته شود.

از یک مقدار Production جداگانه استفاده کنید

وقتی پروژه‌ای را منتشر می‌کنید که از یک کلید ذخیره‌شده استفاده می‌کند، ممکن است فرایند انتشار از شما بخواهد این مورد را پیکربندی کنید Production Keys. به‌طور پیش‌فرض، برنامه منتشرشده از مقدار Test استفاده می‌کند. برای استفاده از یک اعتبارنامه متفاوت، Production را انتخاب کنید و یک مقدار جداگانه برای کلید ذخیره کنید.

در این موارد از یک مقدار Production جداگانه استفاده کنید:

• ارائه‌دهنده اعتبارنامه‌های آزمایشی و زنده متفاوتی ارائه می‌کند.
• نمی‌خواهید اعتبارنامه‌ای که در طول توسعه استفاده شده توسط برنامه منتشرشده استفاده شود.

مقادیر Production از طریق فرایند انتشار ایجاد می‌شوند. نمی‌توانید با انتخاب New Key از زبانه Production Keys یکی ایجاد کنید. پس از اینکه یک مقدار Production برای یک برنامه منتشرشده پیکربندی شد، می‌توانید آن را در Atoms Cloud → Keys → Production Keys.

پس از انتشار یا به‌روزرسانی برنامه، مسیر کاربری مرتبط را در وب‌سایت منتشرشده تکرار کنید تا تأیید شود کلید Production درست کار می‌کند. برای فرایند کامل استقرار، این مورد را ببینید Publish and deploy.

به‌روزرسانی یا چرخش یک اعتبارنامه

به‌روزرسانی یک مقدار Test ذخیره‌شده

1. باز کنید Atoms Cloud → Keys → Test Keys.
2. باز کنید In This Project یا Key Library, بسته به اینکه ورودی کجا ذخیره شده است.
3. این مورد از کلید را انتخاب کنید Value یا Description, اطلاعات به‌روزشده را وارد کنید، سپس این مورد را انتخاب کنید Update.
4. منتظر Save success, بمانید، سپس جریان تحت تأثیر را دوباره آزمایش کنید.

چرخش برنامه‌ریزی‌شده کلید

وقتی اعتبارنامه موجود هنوز امن است و می‌خواهید بدون ایجاد وقفه در برنامه‌تان آن را جایگزین کنید، این مراحل را دنبال کنید:

1. از طریق ارائه‌دهنده سرویس یک اعتبارنامه جایگزین ایجاد کنید.
2. مقدار Test را در Atoms جایگزین کنید، سپس قابلیت تحت تأثیر را در App Viewer.
3. اگر برنامه منتشرشده از یک مقدار Production جداگانه استفاده می‌کند، آن را جایگزین کنید و به‌روزرسانی را منتشر کنید.
4. همان قابلیت را در وب‌سایت منتشرشده آزمایش کنید.
5. پس از تأیید اینکه جایگزین به‌درستی کار می‌کند، اعتبارنامه قدیمی را از طریق ارائه‌دهنده لغو کنید.

اگر ممکن است یک اعتبارنامه افشا شده باشد

اعتبارنامه را در معرض خطر تلقی کنید و فوراً اقدام کنید:

1. آن را از طریق ارائه‌دهنده سرویس لغو یا غیرفعال کنید.
2. یک اعتبارنامه جایگزین ایجاد کنید.
3. مقادیر Test و Production مربوطه را در Atoms به‌روزرسانی کنید.
4. قابلیت‌های تحت تأثیر را دوباره هم در App Viewer و هم در برنامه منتشرشده آزمایش کنید.
5. هر نسخه افشاشده را تا حد امکان از کد منبع، Chat, اسکرین‌شات‌ها و گزارش‌ها حذف کنید.

حذف یک کلید یا پاک کردن مقدار آن از Atoms، اعتبارنامه اصلی را لغو نمی‌کند. باید آن را از طریق ارائه‌دهنده سرویس لغو کنید.

حذف یک اعتبارنامه

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

1. قابلیتی را که از کلید استفاده می‌کند حذف کنید، یا ارجاعات آن را با یک کلید ذخیره‌شده دیگر جایگزین کنید.
2. اعتبارنامه اصلی را از طریق ارائه‌دهنده سرویس لغو کنید تا دیگر قابل استفاده نباشد.
3. باز کنید Atoms Cloud → Keys, ورودی غیرفعال را پیدا کنید، Delete, را انتخاب کنید و تأیید کنید.

حذف یک کلید قابل بازگردانی نیست. همچنین ممکن است پیش‌نمایش‌ها یا checkpointهای قدیمی‌تری را که هنوز به آن ارجاع می‌دهند خراب کند. اگر Delete در دسترس نیست، کلید هنوز به‌عنوان فعال علامت‌گذاری شده است. پیش از تلاش دوباره، همه ارجاعات به آن را حذف یا جایگزین کنید.

پرسش‌های متداول

کلید Test من در App Viewer کار می‌کند اما بعد از انتشار نه. چرا؟

اگر کلید Test شما در App Viewer کار می‌کند اما برنامه منتشرشده به‌دلیل نبودن یا خالی بودن یک کلید شکست می‌خورد:

1. بررسی کنید که آیا مقدار Test یا Production مربوطه پیش از آخرین انتشار ذخیره شده یا بعد از آن. اگر بعد از آن ذخیره شده، دوباره منتشر کنید تا تغییر اعمال شود.
2. تأیید کنید که کلید ذخیره‌شده مقدار Test یا Production درست را دارد. برنامه منتشرشده از مقدار Test استفاده می‌کند مگر اینکه یک مقدار Production جداگانه پیکربندی شده باشد.
3. برای یافتن سرنخ، خطاهای سرویس پایین‌دستی را بررسی کنید. «Unauthorized» معمولاً نشان‌دهنده یک کلید خالی یا نادرست برای آن محیط است.

اگر مشکل ادامه داشت، با Support تماس بگیرید و این موارد را شامل کنید:

• لینک پروژه یا URL زنده
• نام کلید تحت تأثیر و اینکه مشکل مربوط به مقدار Test است یا Production
• خطای کامل از سرویس پایین‌دستی
• یک اسکرین‌شات پاک‌سازی‌شده از صفحه پیکربندی
• اینکه پیکربندی کلید پیش از انتشار ذخیره شده یا بعد از آن

مهم: فقط نام کلیدها را ارائه کنید. مقادیر محرمانه، گذرواژه‌ها یا توکن‌ها را ارسال نکنید.