کاربران

برای درخواست جزئیات درباره کاربران، از متدهای زیر API استفاده کنید.

get_user

یک کاربر موجود را برمی‌گرداند.

GET index.php?/api/v2/get_user/{user_id}

پارامترها

نام	نوع	الزامی	توضیحات
user_id	integer	true	ID کاربر

محتوای پاسخ (TestRail Professional)

{
    "id": 1,
    "email": "john.doe@gurock.io",
    "email_notifications": true,
    "is_active": true,
    "is_admin": false,
    "name": "John Doe",
    "role_id": 3,
    "role": "Tester",
    "group_ids": [1, 2, 3],
    "mfa_required": false
}

محتوای پاسخ (TestRail Enterprise)

{
    "id": 1,
    "email": "john.doe@gurock.io",
    "email_notifications": true,
    "is_active": true,
    "is_admin": false,
    "name": "John Doe",
    "role_id": 3,
    "role": "Tester",
    "group_ids": [1, 2, 3],
    "mfa_required": false,
    "sso_enabled": true,
    "assigned_projects": [1, 3]
}

فیلدهای زیر در پاسخ برگردانده می‌شوند:

نام	نوع	توضیحات
assigned_projects	array	آرایه‌ای از project IDها. هر ID نشان‌دهنده projectی است که کاربر به آن اختصاص داده شده است. برای اطلاعات بیشتر، Project Level Administration را ببینید – به TestRail Enterprise ۷.۳ یا نسخه‌های بعدی نیاز دارد
email	string	آدرس ایمیل کاربر، همان‌طور که در TestRail تنظیم شده است
email_notifications	boolean	اگر اعلان‌های ایمیلی برای کاربر فعال باشد، مقدار آن true است – به TestRail ۷.۳ یا نسخه‌های بعدی نیاز دارد
id	integer	ID یکتای کاربر
is_active	boolean	اگر کاربر فعال باشد مقدار آن true است؛ در غیر این صورت false است
is_admin	boolean	اگر کاربر administrator در TestRail باشد، مقدار آن true است –به TestRail ۷.۳ یا نسخه‌های بعدی نیاز دارد
group_ids	array	آرایه‌ای از group IDها. هر ID نشان‌دهنده groupی است که کاربر به آن اختصاص داده شده است – به TestRail ۷.۳ یا نسخه‌های بعدی نیاز دارد
mfa_required	boolean	اگر پروفایل کاربر طوری تنظیم شده باشد که در هر ورود MFA لازم باشد، مقدار آن true است – به TestRail ۷.۳ یا نسخه‌های بعدی نیاز دارد
name	string	نام کامل کاربر
role_id	integer	ID یکتای نقشی که در سطح سراسری به کاربر اختصاص داده شده است – به TestRail ۶.۴ یا نسخه‌های بعدی نیاز دارد
role	string	نام نقشی که در سطح سراسری به کاربر اختصاص داده شده است – به TestRail ۶.۴ یا نسخه‌های بعدی نیاز دارد
sso_enabled	boolean	اگر SSO برای پروفایل کاربر فعال باشد، مقدار آن true است – به TestRail Enterprise ۷.۳ یا نسخه‌های بعدی نیاز دارد

هر کاربر می‌تواند اطلاعات حساب خودش را دریافت کند. دریافت اطلاعات حساب کاربران دیگر به دسترسی administrator نیاز دارد.

کدهای پاسخ

کد status	توضیحات
200	موفقیت‌آمیز (کاربر در پاسخ برگردانده می‌شود)
400	کاربر نامعتبر یا ناشناخته
429	فقط TestRail Cloud– تعداد درخواست‌ها بیش از حد مجاز است (ببینید محدودیت نرخ API)

get_current_user

این endpoint به TestRail ۶.۶ یا نسخه‌های بعدی نیاز دارد.

جزئیات کاربر TestRailی را برمی‌گرداند که درخواست API را ارسال کرده است.

GET index.php?/api/v2/get_current_user/{user_id}

پارامترها

نام	نوع	الزامی	توضیحات
user_id	integer	true	ID کاربر

محتوای پاسخ

{
    "id": 1,
    "email": "john.doe@gurock.io",
    "is_active": true,
    "name": "John Doe",
    "role_id": 3,
    "role": "Tester"
}

فیلدهای زیر در پاسخ برگردانده می‌شوند:

نام	نوع	توضیحات
email	string	آدرس ایمیل کاربر، همان‌طور که در TestRail تنظیم شده است
id	integer	ID یکتای کاربر
is_active	boolean	اگر کاربر فعال باشد مقدار آن true است؛ در غیر این صورت false است
name	string	نام کامل کاربر
role_id	integer	ID یکتای نقشی که در سطح سراسری به کاربر اختصاص داده شده است – به TestRail ۶.۴ یا نسخه‌های بعدی نیاز دارد
role	string	نام نقشی که در سطح سراسری به کاربر اختصاص داده شده است – به TestRail ۶.۴ یا نسخه‌های بعدی نیاز دارد

کدهای پاسخ

کد status	توضیحات
200	موفقیت‌آمیز (کاربر در پاسخ برگردانده می‌شود)
400	کاربر نامعتبر یا ناشناخته
429	فقط TestRail Cloud– تعداد درخواست‌ها بیش از حد مجاز است (ببینید محدودیت نرخ API)

get_user_by_email

یک کاربر موجود را بر اساس آدرس ایمیل او برمی‌گرداند.

GET index.php?/api/v2/get_user_by_email&email={email}

پارامترها

نام	نوع	الزامی	توضیحات
email	string	true	آدرس ایمیلی که می‌خواهید کاربر مربوط به آن را دریافت کنید

این متد از همان قالب پاسخ get_user استفاده می‌کند.

کدهای پاسخ

کد status	توضیحات
200	موفقیت‌آمیز (کاربر در پاسخ برگردانده می‌شود)
400/404	آدرس ایمیل نامعتبر یا ناشناخته
429	فقط TestRail Cloud– تعداد درخواست‌ها بیش از حد مجاز است (ببینید محدودیت نرخ API)

get_users

فهرست کاربران را برمی‌گرداند.

GET index.php?/api/v2/get_users
GET index.php?/api/v2/get_users/{project_id}

از TestRail ۶.۶ به بعد، فقط administratorها می‌توانند get_users را بدون parameter project_id استفاده کنند. کاربران غیر administrator باید parameter project_id را وارد کنند.

پارامترها

نام	نوع	الزامی	توضیحات
project_id	integer	true	ID projectی که می‌خواهید اطلاعات کاربران آن را دریافت کنید. (برای کاربران غیر administrator الزامی است.) – به TestRail ۶.۶ یا نسخه‌های بعدی نیاز دارد

توجه:

کاربران غیر administrator باید parameter project_id را وارد کنند.
اگر project_id وارد نشود، اطلاعات همه کاربران برگردانده می‌شود.
get_users/{project_id} فقط کاربرانی را برمی‌گرداند که به‌صورت صریح به project دسترسی دارند و کاربران دارای دسترسی سراسری را فهرست نمی‌کند.

وقتی از parameter project_id استفاده می‌شود:

مقادیر role و role_id برگردانده‌شده، با دسترسی کاربر در سطح project مطابقت دارد.
کاربران غیرفعال در پاسخ برگردانده نمی‌شوند.
کاربرانی که به project دسترسی ندارند، در پاسخ برگردانده نمی‌شوند.

محتوای پاسخ

[
    {
        "id": 1,
        "name": "John Doe",
    },
    {
        "id": 2,
        "name": "Alexis Gonzalez",
    },
]

پاسخ شامل آرایه‌ای از کاربران است. هر کاربر در این فهرست همان قالب get_user را دارد.

کدهای پاسخ

کد status	توضیحات
200	موفقیت‌آمیز (کاربران در پاسخ برگردانده می‌شوند)
400	project_id نامعتبر
403	مجوز کافی ندارید
429	فقط TestRail Cloud– تعداد درخواست‌ها بیش از حد مجاز است (ببینید محدودیت نرخ API)

add_user

این endpoint به TestRail ۷.۳ یا نسخه‌های بعدی نیاز دارد.

POST index.php?/api/v2/add_user

نمونه درخواست

{
    "name": "John Doe",
    "email": "john.doe@gurock.io"
}

فیلدهای زیر در درخواست پشتیبانی می‌شوند:

نام	نوع	توضیحات
assigned_projects	array	آرایه‌ای از project IDها برای اختصاص دادن به Project Level Administrator. برای اطلاعات بیشتر، Project Level Administration را ببینید.
email	string	آدرس ایمیل کاربر. (الزامی)
email_notifications	boolean	برای غیرفعال کردن اعلان‌های ایمیلی کاربر، مقدار false را وارد کنید. مقدار پیش‌فرض: true.
is_active	boolean	اگر کاربر فعال است، مقدار true را وارد کنید. مقدار پیش‌فرض: false.
is_admin	boolean	برای تبدیل کاربر به TestRail Administrator، مقدار true را وارد کنید. مقدار پیش‌فرض: false.
group_ids	array	آرایه‌ای از group IDها برای اختصاص دادن کاربر به groupها
mfa_required	boolean	برای اجباری کردن MFA برای کاربر، مقدار true را وارد کنید. مقدار پیش‌فرض با تنظیم MFA در instance مطابقت دارد
name	string	نام کاربر. (الزامی)
role_id	integer	ID نقش سراسری که باید به کاربر اختصاص داده شود
sso_enabled	boolean	برای فعال کردن SSO برای کاربر، مقدار true را وارد کنید. مقدار پیش‌فرض با تنظیم SSO در instance مطابقت دارد

محتوای پاسخ

در صورت موفقیت، این متد کاربر جدید را با همان قالب پاسخ get_user برمی‌گرداند.

کدهای پاسخ

کد status	توضیحات
200	موفقیت‌آمیز (کاربر ایجاد شد)
400	مقدار فیلد نامعتبر است؛ مانند آدرس ایمیل
403	مجوز ایجاد کاربر را ندارید

update_user

یک کاربر موجود را به‌روزرسانی می‌کند.

POST index.php?/api/v2/update_user/:user_id

پارامترها

نام	نوع	الزامی	توضیحات
user_id	integer	true	ID کاربر

فیلدهای درخواست

این endpoint از همان فیلدهای add_user پشتیبانی می‌کند.

محتوای پاسخ

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

کدهای پاسخ

کد status	توضیحات
200	موفقیت‌آمیز (کاربر به‌روزرسانی شد)
400	مقدار فیلد نامعتبر است؛ مانند آدرس ایمیل
403	مجوز به‌روزرسانی کاربران را ندارید

get_user

پارامترها

محتوای پاسخ (TestRail Professional)

محتوای پاسخ (TestRail Enterprise)

کدهای پاسخ

get_current_user

پارامترها

محتوای پاسخ

کدهای پاسخ

get_user_by_email

پارامترها

کدهای پاسخ

get_users

پارامترها

توجه:

وقتی از parameter project_id استفاده می‌شود:

محتوای پاسخ

کدهای پاسخ

add_user

نمونه درخواست

محتوای پاسخ

کدهای پاسخ

update_user

پارامترها

فیلدهای درخواست

محتوای پاسخ

کدهای پاسخ

TestRail را همین حالا در محیط دمو ببینید.