شروع سریع جاسازی تعاملی

اگر تازه با جاسازی متابیس شروع می‌کنید، استفاده از تجزیه و تحلیل تعبیه‌شده JS را در نظر بگیرید - یک گزینه بهبود یافته و قابل سفارشی‌سازی بیشتر برای جاسازی عناصر تعاملی متابیس. جاسازی تعاملی همچنان به طور کامل پشتیبانی می‌شود.

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

{% include shared/in-page-promo-embedding-workshop.html %}

پیش‌نیازها

• یک برنامه دارید که می‌توانید متابیس را در آن جاسازی کنید.
• یک اشتراک Pro یا Enterprise از متابیس دارید. اگر مطمئن نیستید از کجا شروع کنید، برای Pro On-Prem یک آزمایش رایگان ثبت‌نام کنید. اگر Docker Desktop نصب شده است، می‌توانید فقط "metabase-enterprise" را جستجو کنید تا تصویر Docker را پیدا کرده و اجرا کنید. به‌جای آن، می‌توانید این دستورالعمل‌ها را دنبال کنید.

کد ارائه شده در این راهنما را می‌توانید در مخزن نمونه ما پیدا کنید.

راه‌اندازی SSO و جاسازی تعاملی در متابیس

آماده کردن یک داشبورد برای جاسازی

ابتدا به یک داشبورد برای جاسازی نیاز دارید. اگر هنوز یکی ندارید، می‌توانید از داشبورد نمونه‌ای که متابیس در نمونه‌های جدید شامل می‌شود استفاده کنید یا می‌توانید با استفاده از x-rays یکی ایجاد کنید.

به آن داشبورد بروید و URL آن را یادداشت کنید، مثلاً /dashboard/1-e-commerce-insights. باید این URL نسبی را در برنامه خود قرار دهید، زیرا از داشبورد به‌عنوان اولین صفحه‌ای که افراد وارد شده هنگام بازدید از بخش تجزیه و تحلیل در برنامه شما می‌بینند استفاده خواهید کرد. کافی است فقط ID را شامل کنید و بقیه URL را حذف کنید، مثلاً /dashboard/1.

همچنین می‌توانید از Entity ID داشبورد استفاده کنید. در داشبورد، روی دکمه info کلیک کنید. در تب Overview، به دنبال Entity ID داشبورد بگردید. آن Entity ID را کپی کنید. از آن Entity ID در URL src iframe استفاده خواهید کرد: (مثلاً، src=/dashboard/entity/[Entity ID]).

فعال کردن جاسازی تعاملی

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

در زیر مبدأهای مجاز، URL وب‌سایت یا برنامه وب که می‌خواهید متابیس را در آن جاسازی کنید را اضافه کنید. اگر برنامه خود را به صورت محلی اجرا می‌کنید، می‌توانید localhost را اضافه کنید و شماره پورت را مشخص کنید، مثلاً http://localhost:8080.

پیکربندی SameSite

اگر متابیس را در یک دامنه متفاوت جاسازی می‌کنید، ممکن است نیاز داشته باشید مقدار SameSite کوکی جلسه را روی none تنظیم کنید

راه‌اندازی SSO با JWT در متابیس شما

فعال کردن احراز هویت با JWT

در حالی که هنوز در بخش جاسازی تعاملی هستید، روی احراز هویت در زیر تنظیمات مرتبط کلیک کنید.

روی کارتی که می‌گوید JWT، دکمه Setup را کلیک کنید (ممکن است نیاز داشته باشید به پایین اسکرول کنید تا کارت JWT را ببینید).

تنظیم JWT Identity provider URI

در برنامه خود، یک route برای SSO در /sso/metabase ایجاد خواهید کرد. در فیلد JWT IDENTITY PROVIDER URI، URL route SSO خود را وارد کنید. به عنوان مثال، برنامه نمونه ما روی پورت 8080 اجرا می‌شود، بنابراین در آن صورت این JWT IDENTITY PROVIDER URI می‌تواند http://localhost:8080/sso/metabase باشد.

تولید یک کلید امضای JWT

روی دکمه Generate key کلیک کنید تا یک کلید امضا تولید شود. این کلید را مخفی نگه دارید. از آن در سرور خود استفاده خواهید کرد. اگر کلید دیگری تولید کنید، کلید موجود را بازنویسی می‌کنید، بنابراین باید کلید را در برنامه خود نیز به‌روزرسانی کنید.

این کلید را کپی کنید، زیرا در بخش بعدی به آن نیاز خواهید داشت.

ذخیره و فعال کردن احراز هویت JWT

بعداً همگام‌سازی گروه را راه‌اندازی خواهیم کرد، اما در حال حاضر، مطمئن شوید که دکمه Save and enable را کلیک کنید تا احراز هویت JWT فعال شود.

راه‌اندازی SSO با JWT در سرور برنامه شما

افزودن کلید امضا و URL سایت متابیس به برنامه

در اینجا باید برخی مقادیر را برای کار SSO خود وارد کنید.

می‌خواهید دو ثابت در برنامه خود اعلان کنید:

• METABASE_JWT_SHARED_SECRET، کلید امضای JWT که از متابیس خود دریافت کرده‌اید را اینجا جایگذاری کنید.
• METABASE_SITE_URL، که به مسیر ریشه متابیس شما اشاره می‌کند.

const METABASE_JWT_SHARED_SECRET = "YOURSIGNINGKEY";
const METABASE_SITE_URL = "https://your-domain.metabaseapp.com";

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

افزودن یک کتابخانه JWT به سرور برنامه

یک کتابخانه JWT به برنامه خود اضافه کنید. به عنوان مثال، اگر از یک backend Node با JavaScript استفاده می‌کنید، استفاده از jsonwebtoken را توصیه می‌کنیم.

در ترمینال خود:

npm install jsonwebtoken --save

و در برنامه خود، کتابخانه را require کنید:

{% include_file "{{ dirname }}/snippets/interactive-embedding-quick-start-guide/sso-with-jwt.ts" snippet="jsonwebtoken-import" %}

محدود کردن دسترسی به routeهای خاص

احتمالاً برنامه شما قبلاً روشی برای اطمینان از اینکه برخی routeها فقط پس از ورود قابل دسترسی هستند دارد. مثال‌های ما از یک تابع helper ساده به نام restrict استفاده می‌کنند که این routeها را محافظت می‌کند:

{% include_file "{{ dirname }}/snippets/interactive-embedding-quick-start-guide/sso-with-jwt.ts" snippet="restrict-helper" %}

افزودن یک تابع برای امضای کاربران

نیاز داریم یک تابع برای امضای JWTهای کاربر بنویسیم، با استفاده از کتابخانه JWT.

{% include_file "{{ dirname }}/snippets/interactive-embedding-quick-start-guide/sso-with-jwt.ts" snippet="sign-user-token-helper" %}

افزودن یک route sso/metabase

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

{% include_file "{{ dirname }}/snippets/interactive-embedding-quick-start-guide/sso-with-jwt.ts" snippet="sso-route" %}

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

نقطه بررسی: ورود به متابیس خود با استفاده از SSO

مطمئن شوید که از متابیس خود خارج شده‌اید. از صفحه ورود متابیس، روی "Sign in with SSO" کلیک کنید. باید به برنامه شما هدایت شوید.

وارد برنامه خود شوید. برنامه شما باید شما را به صفحه خوش‌آمدگویی متابیس هدایت کند. اگر فرد هنوز حساب متابیس نداشته باشد، متابیس باید یک حساب برای آن‌ها ایجاد کند.

جاسازی متابیس در برنامه شما

حالا برای جاسازی متابیس خود در برنامه. می‌خواهید یک route برای سرو تجزیه و تحلیل جاسازی شده خود راه‌اندازی کنید. بیایید آن را /analytics بنامیم. توجه داشته باشید که از تابع helper restrict (تعریف شده در بالا) استفاده می‌کنیم زیرا این صفحه فقط باید پس از ورود افراد به برنامه شما قابل مشاهده باشد.

در این route، نیاز داریم یک iframe رندر کنیم که متابیس شما را بارگذاری می‌کند. ویژگی src iframe باید به مسیر نسبی endpoint SSO برنامه شما اشاره کند. پس از ورود فرد به برنامه شما (و بنابراین به متابیس شما)، پارامتر query string return_to را اضافه می‌کنیم تا iframe داشبورد درخواستی را نمایش دهد.

METABASE_DASHBOARD_PATH باید به مسیر نسبی داشبوردی که در ابتدای این راهنما ایجاد کردید اشاره کند (/dashboard/[ID]، یا اگر از Entity ID داشبورد استفاده کردید: /dashboard/entity/[Entity ID]).

{% include_file "{{ dirname }}/snippets/interactive-embedding-quick-start-guide/sso-with-jwt.ts" snippet="analytics-route" %}

METABASE_DASHBOARD_PATH فقط اولین چیزی است که افراد هنگام ورود می‌بینند، اما می‌توانید آن مسیر را به هر URL متابیس تنظیم کنید. و از آنجایی که برنامه کامل متابیس را جاسازی می‌کنید، افراد می‌توانند از داده حفاری کنند و سؤال‌ها، داشبوردها و مجموعه‌های دیگر را مشاهده کنند.

نقطه بررسی: مشاهده یک داشبورد متابیس در برنامه شما

افرادی که از برنامه شما استفاده می‌کنند اکنون باید بتوانند به /analytics دسترسی داشته باشند و داشبورد متابیس جاسازی شده شما را مشاهده کنند.

نحوه تست: وارد برنامه خود شوید و به route /analytics بروید. باید داشبورد متابیس را ببینید.

اگر از مرورگر Safari استفاده می‌کنید و متابیس و برنامه خود را از دامنه‌های مختلف سرو می‌دهید، ممکن است نیاز داشته باشید به تنظیمات Safari بروید و جلوگیری از ردیابی cross-site را خاموش کنید.

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

حالا که SSO و جاسازی تعاملی را راه‌اندازی کرده‌اید، زمان راه‌اندازی گروه‌ها است تا بتوانید مجوزها را به موجودیت‌های متابیس جاسازی شده خود (سؤال‌ها، داشبوردها، مجموعه‌ها و غیره) اعمال کنید.

افزودن یک کلید groups به توکن

تابع signUserToken استفاده شده برای ایجاد JWTها را به یاد بیاورید. یک کلید groups به توکن امضا شده اضافه کنید که به یک آرایه نگاشت می‌شود. متابیس به مقادیر در آن آرایه نگاه می‌کند تا ببیند آیا هر یک از مقادیر به یک گروه در متابیس نگاشت می‌شوند (کمی بعد از نگاشت گروه‌ها عبور می‌کنیم).

{% include_file "{{ dirname }}/snippets/interactive-embedding-quick-start-guide/sso-with-jwt.ts" snippet="user-groups-sign-user-token-helper" %}

ایجاد یک گروه در متابیس

در متابیس، روی آیکون چرخ‌دنده کلیک کنید و به تنظیمات مدیر > افراد > گروه‌ها بروید. دکمه Create a group را کلیک کنید. یک گروه اضافه کنید که با یک گروه در برنامه شما مطابقت دارد. اگر از برنامه نمونه استفاده می‌کنید، یک گروه به نام Customer Acme اضافه کنید.

همگام‌سازی گروه‌ها بین متابیس و برنامه شما

این رشته در کلید groups را به یک گروه متابیس نگاشت خواهید کرد، تا زمانی که فرد از طریق SSO وارد می‌شود، متابیس به طور خودکار آن‌ها را به گروه متابیس مناسب اختصاص دهد.

در بخش admin متابیس، به احراز هویت > JWT بروید و Edit را کلیک کنید.

در بخش Group schema، همگام‌سازی عضویت گروه را روشن کنید. اگر نام‌های گروه‌ها در آرایه groups دقیقاً با نام‌های گروه متابیس مطابقت داشته باشند (مثلاً هر دو "Customer Acme" هستند)، سپس گروه‌ها به طور خودکار نگاشت می‌شوند.

اگر نام‌های گروه JWT و نام‌های گروه متابیس مطابقت نداشته باشند، برای هر گروهی که می‌خواهید همگام‌سازی کنید، یک نگاشت گروه اضافه کنید. وقتی New mapping را کلیک می‌کنید، "Customer-Acme"، رشته‌ای که در آرایه groups در payload JWT خود شامل کرده‌اید را وارد کنید. سپس می‌توانید آن نام گروه را با گروه متابیس "Customer Acme" که قبلاً ایجاد کردیم مرتبط کنید.

مطمئن شوید که Save changes را کلیک کنید.

نقطه بررسی: تأیید اینکه متابیس افراد را هنگام ورود به گروه‌ها اختصاص می‌دهد

ابتدا از متابیس خارج شوید و با استفاده از SSO وارد شوید.

سپس خارج شوید و به عنوان یک مدیر به متابیس خود وارد شوید و به بخش تنظیمات مدیر > افراد بروید و تأیید کنید که متابیس فرد را به گروه مناسب اضافه کرده است.

توجه: فقط مدیران متابیس و مدیران گروه از گروه‌ها آگاه هستند. کاربران پایه مفهومی از گروه‌ها ندارند و راهی برای دانستن اینکه در کدام گروه‌ها هستند ندارند.

تنظیم مجوزها

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

بازنشانی مجوزها برای گروه All Users

متابیس با دو گروه اولیه عرضه می‌شود: "Admins" و "All Users". به‌طور پیش‌فرض، متابیس به گروه "All Users" دسترسی به منابع داده متصل شده می‌دهد. و از آنجایی که متابیس امتیازات گروه‌های مجازترین خود را به افراد اعطا می‌کند، می‌خواهید آنچه گروه "All Users" می‌تواند ببیند را قبل از اضافه کردن آن‌ها به گروه‌هایی با دسترسی محدود یا بدون دسترسی به منابع داده و مجموعه‌ها محدود کنید.

برای بازنشانی مجوزها برای گروه All users، روی آیکون چرخ‌دنده کلیک کنید و به تنظیمات مدیر > مجوزها بروید. در زیر تب Data، به Groups بروید و All Users را انتخاب کنید. برای Sample Database در ستون View data، "Blocked" را انتخاب کنید. Save changes را کلیک کنید و یک modal ظاهر می‌شود که خلاصه آنچه تغییر می‌دهید را نشان می‌دهد. Yes را کلیک کنید.

اجازه دادن به دسترسی مشاهده به مجموعه داشبوردهای تولید شده خودکار

هنوز در تب Permissions، روی زیرتب Collections کلیک کنید، سپس روی مجموعه Automatically generated dashboards، و مجوزهای Collection access را برای گروه All Users روی View تنظیم کنید.

Save changes را کلیک کنید، سپس Yes.

افزودن یک ویژگی کاربر به توکن

می‌توانید ویژگی‌های کاربر را در JSON web token شامل کنید. متابیس هر کلیدی را از payload JWT برمی‌دارد و آن‌ها را به عنوان ویژگی‌های کاربر ذخیره می‌کند. در میان موارد استفاده دیگر، می‌توانید از این ویژگی‌های کاربر برای تنظیم مجوزهای سطح ردیف روی جداول استفاده کنید، تا افراد فقط نتایج مرتبط با حساب‌های خود را ببینند.

اگر از برنامه نمونه ما استفاده می‌کنید، تابع signUserToken استفاده شده برای ایجاد JWT را با افزودن یک کلید account_id با مقدار 28 ویرایش کنید.

{% include_file "{{ dirname }}/snippets/interactive-embedding-quick-start-guide/sso-with-jwt.ts" snippet="user-attribute-sign-user-token-helper" %}

آن user ID با ستون Account ID در جدول Invoices پایگاه داده نمونه مطابقت خواهد داشت. از این ویژگی کاربر account_id برای امنیت ردیف و ستون در جدول Invoices استفاده خواهیم کرد، تا افراد فقط ردیف‌هایی در آن جدول را ببینند که شامل account ID آن‌ها است.

توجه داشته باشید که برای ماندگار کردن ویژگی کاربر در متابیس، باید وارد شوید. به عنوان یک non-admin وارد برنامه خود شوید و صفحه با متابیس جاسازی شده خود را بازدید کنید.

تنظیم مجوزهای سطح ردیف

در متابیس، به تنظیمات مدیر > مجوزها بروید. در زیر تب Data در سمت چپ، روی یک گروه کلیک کنید. برای "Sample Database"، ستون Data access آن را به Granular تغییر دهید.

متابیس فهرستی از جداول در پایگاه داده را نمایش می‌دهد. بعد، View data access را برای جدول "Invoices" به Row and column security تغییر دهید.

بعد، متابیس شما را با یک modal برای مرتبط کردن یک ستون در آن جدول با یک ویژگی کاربر راهنمایی می‌کند.

گزینه Filter by a column in a table را بررسی شده بگذارید و ستون "Account ID" در جدول Invoices را با ویژگی کاربر account_id مرتبط کنید. (توجه داشته باشید که متابیس فقط ویژگی‌های کاربر را نمایش می‌دهد اگر کاربر قبلاً از طریق SSO وارد شده باشد.)

Save را کلیک کنید تا انتخاب خود را تأیید کنید. سپس دکمه Save changes را در بالا سمت راست کلیک کنید.

متابیس می‌پرسد که آیا مطمئن هستید که می‌خواهید این کار را انجام دهید. شما مطمئن هستید.

نقطه بررسی: مشاهده داشبورد امن

مطمئن شوید که از جلسه قبلی خود خارج شده‌اید.

وارد برنامه خود شوید، به /analytics بروید. داشبورد اکنون اطلاعات متفاوتی را ارائه می‌دهد، زیرا فقط یک زیرمجموعه از داده برای این فرد قابل مشاهده است. روی Browse Data در پایین nav سمت چپ کلیک کنید. جدول امن Invoices خود را مشاهده کنید و باید فقط ردیف‌هایی در آن جدول را ببینید که با حساب فرد مرتبط هستند.

مخفی کردن عناصر متابیس

می‌توانید تصمیم بگیرید نمایش یا مخفی کردن عناصر مختلف متابیس، مانند اینکه آیا نوار nav، جستجو یا دکمه +New را نمایش دهید و غیره.

به عنوان مثال، برای مخفی کردن لوگو و نوار ناوبری بالای متابیس جاسازی شده خود، پارامترهای query string ?logo=false&top_nav=false را به URL return_to که در redirect SSO شامل می‌کنید اضافه می‌کنید.

در handler مسیر /sso/metabase خود، پارامترهای query را اضافه کنید:

{% include_file "{{ dirname }}/snippets/interactive-embedding-quick-start-guide/sso-with-jwt.ts" snippet="hide-metabase-elements" %}

نقطه بررسی: تأیید عناصر UI مخفی

از برنامه خود خارج شوید و دوباره وارد شوید و به /analytics بروید. متابیس جاسازی شده شما نباید شامل لوگو یا ناوبری بالایی باشد.

مراحل بعدی

می‌توانید نحوه ظاهر متابیس را در برنامه خود سفارشی کنید: فونت‌ها، رنگ‌ها و لوگوها.