برای دریافت فهرست فیلدهایی که هنگام ایجاد یا به‌روزرسانی test run و test plan برای فیلتر پویا در دسترس هستند، از متد API زیر استفاده کنید.
get_dynamic_filter_fields
فهرست فیلدهای قابل استفاده برای فیلتر پویا را برای یک project مشخص برمی‌گرداند.
GET index.php?/api/v2/get_dynamic_filter_fields/{project_id}پارامترها
| نام | نوع | الزامی | توضیحات |
|---|---|---|---|
| project_id | integer | true | ID پروژه‌ای که فیلدهای فیلتر پویای آن باید برگردانده شوند. |
محتوای پاسخ
پاسخ شامل آرایه‌ای از تعریف‌های فیلد است که می‌توان از آن‌ها برای ساخت dynamic_filters payload برای endpointهای API پشتیبانی‌شده‌ی test run و test plan استفاده کرد.
فیلدهای برگردانده‌شده با فیلدهای فیلتر پویایی که در UI TestRail برای project انتخاب‌شده در دسترس هستند مطابقت دارند. این موارد شامل فیلدهای سیستمی پشتیبانی‌شده و فیلدهای custom case فعال است که در آن project قابل فیلتر کردن هستند.
نوع‌های فیلدی که قابل فیلتر کردن نیستند، مانند Text، Steps و Scenarios، برگردانده نمی‌شوند. نمونه‌ای از پاسخ معمول را در ادامه ببینید:
[
{
"type_id": 6,
"system_name": "status_id",
"label": "Status",
"options": "1, Untested\n2, Retest\n3, Passed\n4, Failed"
},
{
"type_id": 6,
"system_name": "priority_id",
"label": "Priority",
"options": "1, Low\n2, Medium\n3, High"
},
{
"type_id": 1,
"system_name": "title",
"label": "Title",
"sub_filters": "1, Is\n2, Is Not\n5, Contains\n6, Does not contain"
},
{
"type_id": 8,
"system_name": "updated_on",
"label": "Updated On",
"sub_filters": "1, Is\n2, Is Not\n3, Is Before\n4, Is After"
},
{
"type_id": 12,
"system_name": "custom_multiselect",
"label": "Custom Multiselect",
"options": "1, Option 1\n2, Option 2"
}
]فیلدهای پاسخ
| نام | نوع | توضیحات |
|---|---|---|
| type_id | integer | ID نوع فیلد. clientها می‌توانند از این مقدار برای تعیین نحوه نمایش یا ساخت فیلترهای مربوط به فیلد استفاده کنند. |
| system_name | string | نام سیستمی فیلد. این مقدار هنگام ساخت dynamic_filters. |
| label | string | برچسب نمایشی فیلد. |
| options | string | گزینه‌های موجود برای فیلدهایی که مقدارهای قابل انتخاب دارند؛ مانند dropdown، multiselect، user، milestone، priority، status، type یا templates. |
| sub_filters | string | operatorهای پشتیبانی‌شده برای فیلدهایی که از فیلتر مبتنی بر شرط پشتیبانی می‌کنند؛ مانند فیلدهای string، URL، integer یا date. |
IDهای نوع فیلد
| Type ID | نام |
|---|---|
| 1 | String |
| 2 | Integer |
| 3 | Text |
| 4 | URL |
| 5 | Checkbox |
| 6 | Dropdown |
| 7 | User |
| 8 | Date |
| 9 | Milestone |
| 10 | Steps |
| 12 | Multi-select |
فیلدهای پشتیبانی‌شده
پاسخ می‌تواند شامل فیلدهای سیستمی پشتیبانی‌شده‌ای مثل موارد زیر باشد:
| فیلد | توضیح |
|---|---|
| Assigned To | test caseها را بر اساس کاربر اختصاص‌داده‌شده فیلتر کنید. |
| Automation Type | test caseها را بر اساس نوع automation فیلتر کنید. |
| Created By | test caseها را بر اساس ایجادکننده فیلتر کنید. |
| Created On | test caseها را بر اساس تاریخ ایجاد فیلتر کنید. |
| Estimate | test caseها را بر اساس estimate فیلتر کنید. |
| Forecast | test caseها را بر اساس forecast فیلتر کنید. |
| Labels | test caseها را بر اساس labelها فیلتر کنید. |
| Milestone | test caseها را بر اساس milestone فیلتر کنید. |
| اولویت | test caseها را بر اساس اولویت فیلتر کنید. |
| References | test caseها را بر اساس references فیلتر کنید. |
| Templateها | test caseها را بر اساس template فیلتر کنید. |
| عنوان | test caseها را بر اساس عنوان فیلتر کنید. |
| نوع | test caseها را بر اساس نوع case فیلتر کنید. |
| به‌روزرسانی‌شده توسط | test caseها را بر اساس آخرین کاربری که آن‌ها را به‌روزرسانی کرده است فیلتر کنید. |
| به‌روزرسانی‌شده در | test caseها را بر اساس آخرین تاریخ به‌روزرسانی فیلتر کنید. |
response همچنین می‌تواند شامل custom case fieldهای فعالی باشد که برای project انتخاب‌شده در دسترس هستند و dynamic filtering از آن‌ها پشتیبانی می‌کند.
استفاده از نام فیلدها در فیلترهای پویا
وقتی از فیلدی که این endpoint برمی‌گرداند در یک dynamic_filters payload استفاده می‌کنید، قبل از system_name از cases: استفاده کنید.
برای مثال، اگر این endpoint مقدار زیر را برگرداند:
{
"type_id": 6,
"system_name": "priority_id",
"label": "Priority",
"options": "1, Low\n2, Medium\n3, High"
}در dynamic filter، از فیلد به شکل زیر استفاده کنید:
{
"mode": "1",
"filters": {
"cases:priority_id": {
"values": [2]
}
}
}کدهای response
| Status Code | توضیحات |
|---|---|
| 200 | موفقیت‌آمیز است. فیلدهای dynamic filter موجود، به‌عنوان بخشی از response برگردانده می‌شوند. |
| 400 | project نامعتبر یا ناشناخته است. |
| 403 | به project دسترسی ندارید. |
| 429 | فقط در TestRail Cloud: تعداد درخواست‌ها بیش از حد مجاز است. |
نکته‌ها
این endpoint فقط فیلدهایی را برمی‌گرداند که رفتار dynamic filter در TestRail برای project انتخاب‌شده از آن‌ها پشتیبانی می‌کند. باید قبل از ساخت dynamic_filters payloadها از آن استفاده شود؛ به‌ویژه هنگام ساخت API clientها، CLIها یا integrationهایی که باید گزینه‌های dynamic filter را خارج از TestRail UI نمایش دهند.
استفاده از فیلترهای پویا با runها و planها
این get_dynamic_filter_fields از این endpoint برای شناسایی فیلدهایی استفاده می‌شود که می‌توان آن‌ها را در یک dynamic_filters payload به کار برد. هنگام ایجاد یا به‌روزرسانی test runها و test planها، فیلترهای پویا پشتیبانی می‌شوند و به کلاینت‌های API اجازه می‌دهند انتخاب‌هایی بسازند که مانند Selection Filter در رابط کاربری TestRail عمل کنند.