قابلیت‌های مدیر - REST

هدف از این مستند درک قابلیت‌هاییست که با اطلاعات مدیر (Master Token) به آنها دسترسی دارید. حفظ اطلاعات و دسترسی مدیر بر عهده شماست و نباید توکن مدیر را به هیچ وجه به کلاینت خود انتقال دهید. زیرا این دسترسی امکانات نامحدود در تغییر و حتی حذف اطلاعات شما دارد و به هیچ وجه نباید توسط کاربران قابل مشاهده باشد. کاربرد اصلی این دسترسی وقتی است که شما قصد اتصال به بکتوری از طریق سرور دلخواه خود را دارید. سرویس رایانش نیز یک نمونه از این سرور دلخواه است. سرویس رایانش به طور پیشفرض همه درخواست‌ها را با دسترسی مدیر می‌دهد. بنابر این هر درخواستی که به سرویس لیدربورد و یا پایگاه داده و یا هر سرویس دیگری در بکتوری از طریق سرویس رایانش بدهید، هرگز با پیام 403 که به معنای عدم دسترسی است، مواجه نخواهید شد. زیرا شما دسترسی مدیر (بالاترین سطح دسترسی ممکن به داده‌های خود) را دارید.

نکته: در صورتی که با مفهوم REST و سرویس‌های سمت سرور و یا با دستور curl آشنایی ندارید، به آشنایی با REST مراجعه کنید.

پیش‌نیازها

  1. در صورتی که با سرویس کاربران آشنایی ندارید، به معرفی سرویس کاربران مراجعه کنید.
  2. اگر با فرآیند امنیتی ورود کاربران در بکتوری آشنایی ندارید، به فرآیند امنیتی ورود کاربران مراجعه کنید.

گرفتن اطلاعات کاربر با استفاده از Id

با استفاده از این واسط می‌توانید اطلاعات یک کاربر را با استفاده از ID ‌آن کاربر به دست آورید. برای این منظور باید درخواست را با توکن دسترسی مدیر یا کاربری ارسال کنید که اطلاعات وی را می‌خواهید (با ورود و گرفتن توکن دسترسی).

در header این درخواست نیاز به X-Backtory-Authentication-Id وجود دارد که با مراجعه به پنل بکتوری، در قسمت کلیدها قابل مشاهده می‌باشد.

curl -X GET \
    --header "X-Backtory-Authentication-Id: <ID>" \
    --header "Authorization: Bearer <USER-ACCESS-TOKEN or MASTER-ACCESS-TOKEN>" \
    'https://api.backtory.com/auth/users/{USER-ID}

دقت داشته باشید که یک کاربر می‌تواند با داشتن توکن دسترسی خودش، از طریق واسط زیر اطلاعاتش را بازیابی کند:

curl -X GET \
    --header "X-Backtory-Authentication-Id: <ID>" \
    --header "Authorization: Bearer <USER-ACCESS-TOKEN>" \
    'https://api.backtory.com/auth/users/me

انواع پاسخ‌هایی که از این سرویس ممکن است دریافت کنید به صورت جدول زیر است:

Tables Description
200-OK Successful
401-Unauthorized Incorrect access token
404-Not Found Your Authentication-Id is wrong.
500-Internal Server Error Data access was unsuccessful
503-Service Unavailable Your service is disabled

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

{
  "instanceId": "AUTHENTICATION-ID",
  "userId": "USER-ID",
  "username": "USERNAME",
  "firstName": "FIRSTNAME",
  "lastName": "LASTNAME",
  "email": "aaa@bbb.ccc",
  "phoneNumber": "12345678",
  "guest": false,
  "active": true
}

گرفتن اطلاعات کاربر با استفاده از نام کاربری

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

در header این درخواست نیاز به X-Backtory-Authentication-Id وجود دارد که با مراجعه به پنل بکتوری، در قسمت کلیدها قابل مشاهده است.

curl -X GET \
    --header "X-Backtory-Authentication-Id: <ID>" \
    --header "Authorization: Bearer <USER-ACCESS-TOKEN or MASTER-ACCESS-TOKEN>" \
    'https://api.backtory.com/auth/users/by-username/{USER-NAME}'

انواع پاسخ‌هایی که از این دو سرویس ممکن است دریافت کنید به صورت جدول زیر است:

Tables Description
200-OK Successful
401-Unauthorized Incorrect access token
404-Not Found Your Authentication-Id is wrong
500-Internal Server Error Data access was unsuccessful
503-Service Unavailable Your service is disabled

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

{
  "instanceId": "AUTHENTICATION-ID",
  "userId": "USER-ID",
  "username": "USERNAME",
  "firstName": "FIRSTNAME",
  "lastName": "LASTNAME",
  "email": "aaa@bbb.ccc",
  "phoneNumber": "12345678",
  "guest": false,
  "active": true
}

به روز رسانی کاربر

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

در header این درخواست نیاز به X-Backtory-Authentication-Id وجود دارد که با مراجعه به پنل بکتوری، در قسمت کلیدها قابل مشاهده است.

curl -X PUT \
    --header "X-Backtory-Authentication-Id: <ID>" \
    --header "Authorization: Bearer <MASTER-ACCESS-TOKEN>" \
    --header "Content-Type: application/json" \
    -d '{
        "username": "NEW-USERNAME",
        "firstName": "NEW-FIRSTNAME",
        "lastName": "NEW-LASTNAME"
    }' https://api.backtory.com/auth/users/{USER-ID}

انواع پاسخ‌هایی که از این سرویس ممکن است دریافت کنید به صورت جدول زیر است:

Tables Description
200-OK Successful
400-Bad Request Invalid email address. Or firstname, lastname, or username length is more than 40 characters.
401-Unauthorized Incorrect access token
404-Not Found Your Authentication-Id is wrong
500-Internal Server Error Data access was unsuccessful
503-Service Unavailable Your service is disabled

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

{
  "instanceId": "AUTHENTICATION-ID",
  "userId": "USER-ID",
  "username": "NEW-USERNAME",
  "firstName": "NEW-FIRSTNAME",
  "lastName": "NEW-LASTNAME",
  "email": "aaa@bbb.ccc",
  "phoneNumber": "12345678",
  "guest": false,
  "active": true
}

جستجو

با استفاده از این سرویس می‌توانید به جستجو در کاربران خود بپردازید. در این سرویس، واژه یا زیرواژه‌ای به عنوان کلمه جستجو گرفته می‌شود و با استفاده از آن در نام، نام خانوادگی، نام کاربری، و ایمیل کاربران جستجو می‌شود. در پاسخ این جستجو، لیست کاربرانی که کلمه جستجو در یکی از چهار ویژگی فوق آن‌ها وجود دارد، برگردانده می‌شود. در این سرویس امکان دریافت اطلاعات به شکل صفحه‌بندی (paging) شده نیز وجود دارد که در درخواست مثال آمده است. لازم به ذکر است برای استفاده از این سرویس نیاز به توکن دسترسی مدیر دارید که با استفاده از واسط ورود مدیر قابل انجام است. بطور مثال در صورت جستجوی کلمه “ez”، اگر در یکی از ویژگی‌های کاربر بطور مثال “reza” باشد، آن کاربر به عنوان نتیجه جستجو برگردانده می‌شود.

در header این درخواست نیاز به X-Backtory-Authentication-Id وجود دارد که با مراجعه به پنل بکتوری، در قسمت کلیدها قابل مشاهده می‌باشد.

curl -X GET \
    --header "X-Backtory-Authentication-Id: <ID>" \
    --header "Authorization: Bearer <MASTER-ACCESS-TOKEN>" \
    'https://api.backtory.com/auth/users/search?word={WORD}&page=0&pageSize=1'

انواع پاسخ‌هایی که از این سرویس ممکن است دریافت کنید به صورت جدول زیر است:

Tables Description
200-OK Successful
417-Expectation failed Authentication Id is wrong.
500-Internal Server Error Data access was unsuccessful
503-Service Unavailable Your service is disabled

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

{
 "userCount": 1,
 "users": [
   {
     "instanceId": "AUTHENTICATION-ID",
     "userId": "USER-ID",
     "username": "USERNAME",
     "firstName": "FIRSTNAME",
     "lastName": "LASTNAME",
     "email": "aaa@bbb.ccc",
     "phoneNumber": "12345678",
     "guest": false,
     "active": true
   }
 ]
}

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

با استفاده از این سرویس، لیست کاربران یک پروژه (به همراه اطلاعات آن‌ها) قابل دسترسی خواهد بود. امکان صفحه‌بندی (Paging) نیز در این سرویس فراهم شده است که در درخواست مثال، نشان داده شده است. لازم به ذکر است برای استفاده از این واسط نیاز به توکن دسترسی مدیر دارید که با استفاده از واسط ورود مدیر قابل انجام است.

در header این درخواست نیاز به X-Backtory-Authentication-Id وجود دارد که با مراجعه به پنل بکتوری، در قسمت کلیدها قابل مشاهده می‌باشد.

curl -X GET \
    --header "X-Backtory-Authentication-Id: <ID>" \
    --header "Authorization: Bearer <MASTER-ACCESS-TOKEN>" \
    'https://api.backtory.com/auth/users?page=1&pageSize=1'

انواع پاسخ‌هایی که از این سرویس ممکن است دریافت کنید به صورت جدول زیر است:

Tables Description
200-OK Successful
417-Expectation failed Authentication id is wrong.
500-Internal Server Error Data access was unsuccessful
503-Service Unavailable Your service is disabled

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

{
  "userCount": 26,
  "users": [
    {
      "instanceId": "AUTHENTICATION-ID",
      "userId": "USER-ID",
      "username": "USERNAME",
      "firstName": "FIRSTNAME",
      "lastName": "LASTNAME",
      "email": "aaa@bbb.ccc",
      "phoneNumber": "12345678",
      "guest": false,
      "active": true
    },...
  ]
}

گرفتن اطلاعات لیستی از کاربران با دادن لیستی از IDهای آن‌ها

این سرویس لیستی از IDهای کاربران را به عنوان ورودی می‌گیرد و لیستی شامل اطلاعات آن کاربران را بر‌می‌گرداند. لازم به ذکر است برای استفاده از این سرویس نیاز به توکن دسترسی مدیر دارید که با استفاده از واسط ورود مدیر قابل انجام است.

در header این درخواست نیاز به X-Backtory-Authentication-Id وجود دارد که با مراجعه به پنل بکتوری، در قسمت کلیدها قابل مشاهده می‌باشد.

curl -X POST \
    --header "X-Backtory-Authentication-Id: <ID>" \
    --header "Authorization: Bearer <MASTER-ACCESS-TOKEN>" \
    --header "Content-Type: application/json" \
    -d '{
        "userIds": [
            "USER-ID-1",
            "USER-ID-2"
        ]
    }' https://api.backtory.com/auth/users/by-user-ids

انواع پاسخ‌هایی که از این سرویس ممکن است دریافت کنید به صورت جدول زیر است:

Tables Description
200-OK Successful
417-Expectation failed Authentication id is wrong.
500-Internal Server Error Data access was unsuccessful
503-Service Unavailable Your service is disabled

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

{
  "userCount": 26,
  "users": [
    {
      "instanceId": "AUTHENTICATION-ID",
      "userId": "USER-ID",
      "username": "USERNAME",
      "firstName": "FIRSTNAME",
      "lastName": "LASTNAME",
      "email": "aaa@bbb.ccc",
      "phoneNumber": "12345678",
      "guest": false,
      "active": true
    },...
  ]
}