کار با اشیاء

پیش‌نیازها

در صورتی که با سرویس پایگاه‌داده آشنایی ندارید، به معرفی سرویس پایگاه‌داده مراجعه کنید.
در صورتی که هنوز در پنل توسعه‌دهنده خود تنظیمات لازم برای سرویس پایگاه‌داده خود را انجام نداده‌اید، به تنظیمات پنل مراجعه کنید.
در صورتی که هنوز SDK یونیتی را راه‌اندازی نکرده‌اید، به راه‌اندازی SDK بکتوری در یونیتی مراجعه کنید.

نکته‌ی مهم: دقت کنید که برای کار با سرویس دیتابیس باید در بکتوری لاگین کنید. در صورتی که با نحوه‌ی لاگین کردن به کمک sdk بکتوری آشنایی ندارید، این‌جا را مشاهده کنید.

کار با اشیاء

ذخیره‌ی یک شیء

فرض کنید که در حال نوشتن برنامه‌ی مدیریت یادداشت‌های روزانه هستید و می‌خواهید یادداشت‌ها کاربر در برنامه را در سرور ذخیره کنید. ابتدا مطابق این‌جا در پنل یک جدول برای یادداشت‌ها بسازید (مثلا به نام Note). هر سطر این جدول متناظر یادداشت یکی از کاربران برنامه شما خواهد بود. یک یادداشت جدید می‌تواند به صورت زیر باشد:

title: "Checkout Backtory MBaaS",
content: "Wow! Take a look at backtory.com",
pinned: true

این یادداشت را با استفاده از کلاس BacktoryObject به صورت زیر بسازید:

BacktoryObject note = new BacktoryObject("Note");
note["title"] = "Checkout Backtory MBaaS";
note["content"] = "Wow! Take a look at backtory.com";
note["pinned"] = true;

دقت کنید که رشته‌ای که به Constructor کلاس BacktoryObject پاس می‌دهید، باید دقیقا نام جدولی باشد که در پنل تعریف کرده‌اید. پیشنهاد ما این است که نام جداول را مطابق LikeThis و نام ستون‌های جداول را مطابق likeThis بگذارید.

بعد از آن‌که شیء یادداشت را به وجود آوردید، ‌ قصد دارید که آن را در سمت سرور ذخیره کنید. برای این کار می‌توانید از کد زیر استفاده کنید:

note.SaveInBackground(response => {
    if (response.Successful) {
        // successful save. good place for Debug.Log function.
    } else {
        // see response.Message to know the cause of error
    }
});

بازیابی یک شیء

هر داده‌ای که در دیتابیس ذخیره شود، یک شناسه منحصر به فرد خواهد گرفت. چنانچه شما این شناسه را داشته باشید، می‌توانید به راحتی آن شیء را از سرور بازیابی (retrieve) کنید. فرض کنید که یادداشتی که در مرحله قبل ذخیره کردیم، شناسه 58f48d0c5169da0001adf3db را گرفته باشد. در این صورت، برای گرفتن این شیء مطابق زیر عمل می‌کنیم: (برای بازیابی یک یا مجموعه‌ای از اشیاء، وقتی از شناسه‌ی آنها اطلاع ندارید، به بخش جستارها مراجعه کنید.)

BacktoryQuery noteQuery = new BacktoryQuery("Note");
noteQuery.GetInBackground("58f48d0c5169da0001adf3db", response => {
    if (response.Successful) {
        BacktoryObject note = response.Body; 
        // get note data by calling get functions on received BacktoryObject
        // for example, Debug.Log(note.Get<string>(“title”))
    } else {
        // see response.Message to know the cause of error
     }
});

اکنون که به شیء note مطابق بالا دست یافته‌ایم، می‌خواهیم مقادیر ستون‌های مختلف را به ازای این BacktoryObject ببینیم. این کار مطابق زیر به کمک دستور <Get<T قابل انجام است:

string title = note.Get<string>("title");
string content = note.Get<string>("content");
bool pinned = note.Get<bool>("pinned");

به‌روزرسانی یک شیء

بسیار محتمل است که کاربر بخواهد یادداشتش را تغییر دهد. با فرض داشتن BacktoryObject متناظر آن (مثلا بازیابی با شناسه مانند قسمت قبل) کافیست برای دستیابی به این هدف، مقادیر ستون‌هایی را که می‌خواهیم، تغییر دهیم و مجددا از تابع SaveInBackground استفاده کنیم. به صورت زیر:

BacktoryQuery noteQuery = new BacktoryQuery("Note");
noteQuery.GetInBackground("<MY-NOTE-ID>", response => {
    if (response.Successful) {
        // object will be updated on server
        BacktoryObject note = response.Body;
        note["title"] = "USE BACKTORY RIGHT NOW!";
        note["pinned"] = false;
        note["editCount"] = note["editCount"] + 1
        note.SaveInBackground(saveResponse => {…});
    }
    else
        Debug.Log("failed; " + response.Message);
});

شمارنده‌ها

در مثال بالا یک نیاز متداول دیده می‌شود؛ اضافه کردن مقدار یک فیلد BacktoryObject. این عمل باید مستقل از مقدار فعلی این فیلد باشد. به طور مثال فرض کنید دو همدست (collaborator) به طور همزمان این یادداشت را میخوانند، فرض کنید تعداد دفعات تغییر این یادداشت در آن لحظه 5 باشد، بعد از اینکه هر دو همدست تغییراتی در فایل اعمال کردند، اگر بخواهیم مانند روش بالا عمل کنیم، عدد 6 برای یادداشت در دیتابیس ذخیره خواهد شد، اما می‌دانیم که در حقیقت عدد 7 باید ثبت می‌شد.

جهت ذخیره کردن فیلدهایی از جنس شمارندها، بکتوری توابع Atomicای برای زیاد کردن و کم کردن شمارنده‌ها فراهم می‌کند. مثال بالا را می‌توان به صورت زیر بازنویسی کرد:

note.Increment("editCount");

مقدار اضافه یا کم شدن را نیز می‌توان با استفاده از تابع (Increment(key, amount تعیین کرد.

حذف یک شیء

برای حذف یک شیء در سرور، با فرض داشتن BacktoryObject متناظر آن به شیوه‌ی زیر عمل می‌کنیم:

note.DeleteInBackground(response => {
    if (response.Successful) {
         // note is deleted on server
    }  else { 
        // see response.Message to know the cause of error 
    }
});

کار با آرایه‌ها

می‌توان در BacktoryObject یک آرایه را به عنوان مقدار یک فیلد گذاشت. مثلا فرض کنید که امکان اضافه کردن هم‌دست (collaborator) به یک یادداشت وجود دارد. به صورت زیر:

note["collaborators"] = new List<string>{"Alireza Farahani", "Javad Abedi",
                        "Mohammad Mesbah"};
note.SaveInBackground(response => {…});

اکنون می‌خواهیم یک هم‌دست به این لیست اضافه کنیم و مطمئن باشیم که عضو تکراری اضافه نشود. در این صورت مشابه زیر عمل می‌کنیم:

note.AddUniqueToList("collaborators", "Mohammad Taheri");
note.SaveInBackground(response => {…});

چنان‌چه عضو تکراری (مثلا “Javad Abedi”) پاس داده بودیم، محتویات collaborators تغییری نمی‌کرد.

اکنون می‌خواهیم یک یا چند هم‌دست را حذف کنیم:

note.RemoveAllFromList("collaborators", new List<string>{"Mohammad Mesbah", "Mohammad Taheri"});
note.SaveInBackground(response => {…});

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

IList<string> collaborators = note.Get<IList<string>>("collaborators");

به طور خلاصه:

توابع AddToList و AddRangeToList اشیاء داده‌شده را به انتهای لیست می‌چسبانند.
توابع AddUniqueToList و AddRangeUniqueToList تنها اعضایی را اضافه می‌کنند که در حال حاضر در لیست وجود ندارند. مکان اضافه شدن مشخص نیست.
تابع RemoveAllFromList تمامی اعضای مشابه لیست ورودی را از لیست اصلی حذف می‌کند.

امنیت اشیاء

برای هر شیء (یا همان سطر در دیتابیس)، می‌توان تعیین کرد که چه کاربرانی حق خواندن این شیء و چه کاربرانی حق تغییردادن این شیء را دارند. جهت تعیین این سطوح دسترسی، بکتوری از مفهوم (access control list (ACL بهره می‌برد. یک حالت ساده و متداول، محدود کردن دسترسی به یک شیء برای کاربر فعلی SDK است. برای ساختن یک یادداشت خصوصی در SDK می‌توان نوشت:

BacktoryObject privateNote = new BacktoryObject("Note");
privateNote["content"] = "personal contents :wink";
privateNote.ACL = new BacktoryACL(BacktoryUser.CurrentUser);
privateUser.SaveInBackground(response => {…});

داده‌گونه‌ها

در حال حاضر به یک BacktoryObject می‌توان داده‌هایی از جنس زیر اضافه کرد:

رشته: string
عدد: int, double
بولین: bool
لیست: IList
نگاشت: IDictionary (کلیدها باید از جنس string باشند.)

دقت کنید که امکان تودرتو کردن (nested) لیست و نگاشت وجود دارد.

پاک کردن تغییرات

تابع (Revert(String key از یک BacktoryObject تمامی تغییرات اعمال شده روی “فیلد متناظر با key” را پاک کرده و آنرا به آخرین وضعیت پایدار بر‌می‌گرداند؛ یعنی، اگر شیء قبلا در سرور ذخیره شده بوده، به ورژن سرور برمی‌گرداند و در غیر این صورت فیلد را حذف می‌کند. تابع ()Revert نیز همان عمل تابع (Revert(String key را برای تمامی فیلدهای BacktoryObject انجام می‌دهد.

دارایی (property)های خاص

هر BacktoryObjectای که در سرور ذخیره شود، یا از سرور بازیابی شود، یک سری دارایی ثابت خواهد داشت که شما قادر به تغییر آنها نیستید، ولی می‌توانید آن‌ها را ببینید:

دارایی ObjectId شناسه‌ی سطر ذخیره‌شده در سرور را برمی‌گرداند.
دارایی CreatedAt زمان ساخته شدن شیء در سرور را برمی‌گرداند.
دارایی UpdatedAt زمان آخرین به‌روزرسانی شیء در سرور را برمی‌گرداند.

گام بعدی

جستارها

کار با اشیاء - Unity

پیش‌نیازها