پارامترها برای جاسازیهای ایستا
همچنین شناخته شده به عنوان: پارامترها برای جاسازیهای امضا شده، یا جاسازیهای مستقل.
پارامترها قطعات اطلاعاتی هستند که بین متابیس و وبسایت شما از طریق URL جاسازی ارسال میشوند. میتوانید از پارامترها برای مشخص کردن نحوه ظاهر و رفتار موارد متابیس درون iframe در وبسایت خود استفاده کنید.
{% include shared/in-page-promo-embedding-workshop.html %}
انواع پارامترها
پارامترها میتوانند امضا شده یا امضا نشده باشند.
پارامترهای امضا شده
پارامترهای امضا شده، مانند نامها و مقادیر فیلتر، باید به کد سرور شما اضافه شوند.
پارامترهای امضا نشده
پارامترهای امضا نشده، مانند تنظیمات ظاهر، باید مستقیماً به ویژگی src iframe شما اضافه شوند.
- مقادیر پیشفرض برای پارامترهای قابل ویرایش
- تنظیمات قابلیت مشاهده برای پارامترهای قابل ویرایش
- تنظیمات ظاهر
افزودن یک ویجت فیلتر به یک جاسازی ایستا
میتوانید از پارامترهای قابل ویرایش برای افزودن ویجتهای فیلتر به داشبوردهای جاسازی شده یا سؤالهای SQL استفاده کنید.
۱. به داشبورد یا سؤال SQL خود بروید. مطمئن شوید که یک فیلتر داشبورد یا متغیر SQL راهاندازی کردهاید. ۲. روی آیکون sharing > Embed this item in an application کلیک کنید. ۳. در زیر Parameters، نامهای فیلترهای داشبورد یا متغیرهای SQL خود را پیدا خواهید کرد. ۴. Editable را برای هر پارامتری که باید یک ویجت فیلتر در جاسازی شما دریافت کند انتخاب کنید. ۵. Publish را کلیک کنید تا تغییرات خود را ذخیره کنید. ۶. کد را در سرور خود اضافه یا بهروزرسانی کنید تا با کد تولید شده توسط متابیس مطابقت داشته باشد.
پارامترهای قابل ویرایش مسئول انتقال مقادیر فیلتر از ویجت فیلتر جاسازی شده (نمایش داده شده در iframe) به فیلترهای داشبورد یا سؤال SQL اصلی شما (در متابیس شما) هستند.
نمیتوانید پارامترها را غیرفعال کنید وقتی سؤال یا داشبورد اصلی نیاز به یک مقدار دارد
اگر فیلتر روی یک داشبورد یا سؤال روی همیشه نیاز به یک مقدار تنظیم شده باشد، نمیتوانید پارامتر را هنگام جاسازی غیرفعال کنید.
پر کردن یک ویجت فیلتر جاسازی شده با یک مقدار پیشفرض
اگر میخواهید یک مقدار پیشفرض برای ویجت فیلتر قابل ویرایش خود تنظیم کنید، میتوانید آن مقدار پیشفرض را به نام پارامتر مربوطه در ویژگی src iframe خود ارسال کنید:
your_embedding_url?parameter_name=value
به عنوان مثال، اگر داشبورد جاسازی شده شما یک فیلتر متصل به یک پارامتر قابل ویرایش به نام "Breakfast" دارد، و میخواهید مقدار پیشفرض را روی "Hash browns" تنظیم کنید:
your_embedding_url?breakfast=Hash_browns
برای مشخص کردن مقادیر پیشفرض برای چندین فیلتر، آنها را با ampersand (&) جدا کنید:
your_embedding_url?breakfast=Hash_browns&lunch=Sandwich
میتوانید چندین مقدار پیشفرض را برای یک فیلتر واحد با جدا کردن مقادیر با ampersand (&) تنظیم کنید:
your_embedding_url?breakfast=Hash_browns&breakfast=Pancakes
مخفی کردن ویجتهای فیلتر از یک جاسازی ایستا
اگر چندین پارامتر قابل ویرایش دارید (که منجر به چندین ویجت فیلتر میشود)، میتوانید موارد خاص را از جاسازی ایستای خود با افزودن #hide_parameters به انتهای URL در ویژگی src iframe خود مخفی کنید:
your_embedding_url#hide_parameters=parameter_name
به عنوان مثال، برای مخفی کردن یک فیلتر به نام "Breakfast" از داشبورد جاسازی شده خود:
your_embedding_url#hide_parameters=breakfast
میتوانید چندین ویجت فیلتر را با جدا کردن نامهای پارامتر با کاما مخفی کنید:
your_embedding_url#hide_parameters=breakfast,lunch
همچنین میتوانید همزمان یک مقدار پیشفرض به یک پارامتر اختصاص دهید و ویجت فیلتر آن را مخفی کنید:
your_embedding_url?breakfast=Hash_browns#hide_parameters=breakfast
نحو پارامتر امضا نشده
هر زمان که یک پارامتر را به URL جاسازی در ویژگی src iframe خود اضافه میکنید، توجه داشته باشید که:
- نامهای پارامتر با حروف کوچک هستند.
- مقادیر پارامتر به حروف حساس هستند (مقادیر باید با داده شما مطابقت داشته باشند).
- فاصلهها باید با underscore جایگزین شوند.
محدود کردن داده در یک جاسازی ایستا با پارامترهای قفل شده
اگر میخواهید داده نمایش داده شده در یک داشبورد یا سؤال SQL جاسازی شده را محدود کنید، میتوانید یک پارامتر قفل شده راهاندازی کنید. یک پارامتر قفل شده داده را در یک داشبورد یا سؤال SQL قبل از نمایش نتایج به افراد در یک جاسازی ایستا فیلتر میکند.
۱. به داشبورد یا سؤال SQL خود بروید. مطمئن شوید که یک فیلتر داشبورد یا متغیر SQL راهاندازی کردهاید. ۲. روی آیکون sharing > Embed this item in an application کلیک کنید. ۳. در زیر Parameters، نامهای فیلترهای داشبورد یا متغیرهای SQL خود را پیدا خواهید کرد. ۴. Locked را برای هر پارامتری که میخواهید داده خود را با آن محدود کنید انتخاب کنید. ۵. اختیاری: یک مقدار در زیر Preview locked parameters انتخاب کنید تا ببینید داده محدود شده چگونه به نظر میرسد. ۶. Publish را کلیک کنید تا تغییرات خود را ذخیره کنید. ۷. کد را در سرور خود اضافه یا بهروزرسانی کنید تا با کد تولید شده توسط متابیس مطابقت داشته باشد.
میتوانید از پارامترهای قفل شده برای نمایش داده فیلتر شده بر اساس ویژگیهای گرفته شده توسط سرور وب خود، مانند نام کاربری یا tenant ID استفاده کنید. برای مثالهای بیشتر، مخزن برنامههای مرجع را ببینید.
پارامترهای قفل شده مقادیر فیلتر انتخاب شده را به داشبورد یا سؤال SQL اصلی شما اعمال میکنند، اما آنها به عنوان ویجتهای فیلتر در جاسازی شما نمایش داده نمیشوند. پارامترهای قفل شده همچنین ممکن است مقادیری که در ویجتهای فیلتر قابل ویرایش شما نمایش داده میشوند را محدود کنند.
اگر فقط میخواهید یک مقدار برای پارامتر الزامی کنید، میتوانید فیلتر را به عنوان قابل ویرایش تنظیم کنید و سؤال یا داشبورد زیربنایی را برای همیشه نیاز به یک مقدار پیکربندی کنید.
بهروزرسانی یک پارامتر قفل شده
چیزهایی که باید در نظر داشته باشید اگر نیاز به ایجاد تغییرات در پارامترهای قفل شده خود دارید.
شامل کردن همه پارامترهای قفل شده در کد سرور
پس از انتشار یک نمودار یا داشبورد با یک پارامتر قفل شده، باید نام پارامتر قفل شده را در کد سرور خود شامل کنید. اگر نام پارامتر را حذف کنید، لاگها به آرامی به شما یادآوری میکنند: You must specify a value for :parameter in the JWT.
برای خاموش کردن یک پارامتر قفل شده، یک آرایه خالی را به عنوان مقدار آن در JWT ارسال کنید
اگر نمیخواهید فیلتر قفل شده اعمال شود، میتوانید یک آرایه خالی، []، را به عنوان مقدار برای پارامتر در JWT ارسال کنید.
مطمئن شوید نام فیلتر با نام پارامتر قفل شده مطابقت دارد
اگر نام یک فیلتر query builder استفاده شده به عنوان یک پارامتر قفل شده را تغییر میدهید، مطمئن شوید که نام و مقدار(های) پارامتر را در کد سرور خود نیز بهروزرسانی کنید. اگر پارامتر قفل شده شما به یک متغیر SQL متصل است، نیازی به تغییر نام و مقدار(های) پارامتر ندارید.
چندین پارامتر قفل شده یا چندین مقدار
مقادیر برای پارامتر قفل شده در کد سرور شما باید دقیقاً با مقادیر فیلتر شما مطابقت داشته باشند. بهترین راه برای تنظیم چندین پارامتر قفل شده، یا ارسال چندین مقدار به یک پارامتر قفل شده، انتخاب یک مقدار فیلتر در زیر Preview locked parameters و پیشنمایش کد سرور تولید شده توسط متابیس است.
استفاده از چندین پارامتر قفل شده با هم با AND فیلتر میکند، نه OR. اگر فقط میخواهید یک زیرمجموعه از پارامترهای قفل شده را اعمال کنید، باید به متابیس بگویید که پارامترهای قفل شده دیگر را نادیده بگیرد.
پارامترهای قفل شده مقادیر موجود برای پارامترهای قابل ویرایش دیگر را محدود میکنند
از آنجایی که پارامترهای قفل شده داده را قبل از نمایش نتایج در جاسازی فیلتر میکنند، پارامترهای قفل شده مقادیر موجود برای ویجتهای فیلتر قابل ویرایش دیگر را محدود میکنند.
به عنوان مثال، بگویید که یک داشبورد با دو فیلتر، State و City را جاسازی میکنید. اگر پارامتر State را با مقدار "Vermont" قفل کنید، متابیس فقط ویجت فیلتر City را در داشبورد نمایش میدهد، و منوی dropdown برای آن ویجت فیلتر City به شهرهای Vermont محدود میشود. در حالی که دو فیلتر را به صراحت لینک نمیکنید، دو فیلتر به طور ضمنی مانند فیلترهای لینک شده رفتار میکنند.
پارامترهای قفل شده در داشبوردها با سؤالهای SQL
اگر پارامتر قفل شده شما به یک فیلتر داشبورد که به نوبه خود به یک سؤال SQL لینک شده است متصل است، فقط میتوانید یک مقدار تکی برای پارامتر قفل شده خود انتخاب کنید.
به عنوان مثال، بگویید که یک فیلتر داشبورد به نام "Breakfast" با مقادیر "Hash browns"، "Muffin"، و "Waffles" دارید. اگر فیلتر "Breakfast" به هر سؤال SQL در داشبورد لینک شده باشد، فقط میتوانید یکی از گزینهها را برای یک پارامتر قفل شده متصل به فیلتر "Breakfast" انتخاب کنید.
استفاده از پارامترهای قفل شده برای قدرت دادن به ویجتهای سفارشی در برنامه شما
از آنجایی که متابیس پارامترهای قفل شده را به عنوان ویجتهای فیلتر نمایش نمیدهد، میتوانید از پارامترهای قفل شده برای قدرت دادن به ویجتهای فیلتر سفارشی که در برنامه خود میسازید استفاده کنید. ممکن است بخواهید ویجت فیلتر خود را بسازید تا:
- ویجتها را با ظاهر و احساس برنامه خود سازگارتر کنید.
- منطق سفارشی را شامل کنید. به عنوان مثال، برای اینکه یک ویجت فیلتر مقادیر اخیر را به خاطر بسپارد.
- یک داشبورد را به روشهای مختلف در بخشهای مختلف برنامه خود استفاده مجدد کنید. به عنوان مثال، ممکن است یک داشبورد با چندین پارامتر قفل شده داشته باشید، و از یک پارامتر در یک مورد، و از پارامتر دیگر در مورد دیگر استفاده کنید. مانند یک داشبورد فروش که در یک بخش از برنامه شما با "region" قفل شده است، در بخش دیگر با "team".
سفارشی کردن ظاهر یک جاسازی ایستا
میتوانید ظاهر یک مورد جاسازی شده را با افزودن پارامترهای hash (مثلاً، #theme=night) به انتهای URL در ویژگی src iframe خود تغییر دهید.
به عنوان مثال، URL جاسازی زیر یک مورد جاسازی شده را در حالت تاریک، بدون حاشیه، و با عنوان اصلی آن نمایش میدهد:
your_embedding_url#theme=night&bordered=false&titled=true
میتوانید تنظیمات ظاهر را از تنظیمات ظاهر جاسازی سؤال یا داشبورد خود پیشنمایش کنید.
| Parameter name | Possible values |
|---|---|
background | true (default), false. Dashboards only. |
bordered | true (default), false. |
locale* | E.g., ko. See list of locales |
titled | true (default), false. |
theme | null (default), night. theme=transparent should work, but is deprecated (see Transparent backgrounds) |
refresh (dashboard only) | integer (seconds, e.g., refresh=60). |
font* | font name |
downloads** | true (default), false, results, pdf |
* Available on Pro and Enterprise plans
** Disabling downloads is available on Pro and Enterprise plans.
برای تنظیمات ظاهر سراسری، مانند رنگها و فونتهای استفاده شده در کل نمونه متابیس شما، سفارشیسازی ظاهر متابیس را ببینید.
تنظیم زبان برای یک جاسازی ایستا
برای تغییر زبان UI برای یک جاسازی ایستا، میتوانید زبان محلی آن را تنظیم کنید. به عنوان مثال، برای تنظیم زبان یک لینک عمومی روی کرهای، #locale=ko را اضافه کنید:
https://metabase.example.com/public/dashboard/7b6e347b-6928-4aff-a56f-6cfa5b718c6b?category=&city=&state=#locale=ko
اگر چندین پارامتر دارید، آنها را با ampersand (&) جدا کنید:
category=Gadget&state=Vermont#theme=night&locale=ko
پارامتر locale زبان عناصر UI متابیس را تغییر میدهد، مانند برچسب دکمه "Export to PDF". برای تغییر زبان محتوا در یک جاسازی ایستا (مانند نامهای سؤالها و داشبوردها)، باید یک فرهنگ لغت ترجمه آپلود کنید.
پسزمینههای شفاف برای جاسازیها
شفاف کردن یک جاسازی بستگی به نوع جاسازی دارد:
- داشبوردها:
background=falseرا تنظیم کنید. پارامترbackgroundمیتواند با پارامترthemeترکیب شود (مثلاً،background=false&theme=night). - سؤالها:
theme=transparentرا تنظیم کنید (منسوخ شده، اما همچنان پشتیبانی میشود).
غیرفعال کردن دانلود برای یک سؤال یا داشبورد جاسازی شده
بهطور پیشفرض، متابیس یک دکمه Download روی سؤالهای جاسازی شده، و یک گزینه Export to PDF روی داشبوردهای جاسازی شده شامل میکند.
میتوانید این گزینهها را با پارامتر downloads در URL جاسازی در ویژگی src iframe پیکربندی کنید، سفارشی کردن ظاهر جاسازیهای ایستا را ببینید.
downloads مقادیر زیر را میپذیرد:
true(پیشفرض): شامل هر دو گزینه Download و Export to PDF.false: مخفی کردن هر دو گزینه Download و Export to PDF.results: نمایش گزینه Download.pdf: نمایش گزینه Export to PDF (فقط داشبوردها).
میتوانید گزینههای صریح را ترکیب کنید: downloads=results,pdf همان downloads=true است.
پارامتر downloads پارامتر منسوخ شده hide_download_button را جایگزین میکند.
حداکثر اندازه درخواست
حداکثر طول یک URL جاسازی ایستا (شامل همه پارامترها) توسط متغیر محیطی MB_JETTY_REQUEST_HEADER_SIZE شما تعیین میشود. پیشفرض 8192 بایت است.
اگر URL جاسازی ایستای شما از حداکثر اندازه header تجاوز کند، یک پیام لاگ مانند URI too long خواهید دید. میتوانید متغیر محیطی را برای پذیرش headerهای بزرگتر بهروزرسانی کنید. اگر از یک سرور proxy استفاده میکنید، ممکن است نیاز داشته باشید یک ویژگی مربوطه را در سرور نیز تنظیم کنید.