بازیابی داده ها با پایگاه داده بیدرنگ Firebase برای C++

این سند اصول بازیابی داده ها و نحوه سفارش و فیلتر کردن داده های Firebase را پوشش می دهد.

قبل از شروع

اطمینان حاصل کنید که برنامه خود را راه اندازی کرده اید و می توانید به پایگاه داده همانطور که در راهنمای Get Started توضیح داده شده است دسترسی داشته باشید.

بازیابی داده ها

داده‌های Firebase با یک تماس یک‌باره به GetValue() یا پیوست کردن به ValueListener در مرجع FirebaseDatabase بازیابی می‌شوند. شنونده ارزش یک بار برای وضعیت اولیه داده ها و بار دیگر هر زمان که داده ها تغییر کند فراخوانی می شود.

یک مرجع پایگاه داده دریافت کنید

برای نوشتن داده در پایگاه داده، به یک نمونه از DatabaseReference نیاز دارید:

    // Get the root reference location of the database.
    firebase::database::DatabaseReference dbref = database->GetReference();

داده ها را یک بار بخوانید

می‌توانید از متد GetValue() برای خواندن یک عکس فوری از محتویات در یک مسیر معین استفاده کنید. نتیجه کار حاوی یک عکس فوری است که شامل همه داده‌ها در آن مکان، از جمله داده‌های فرزند است. اگر داده ای وجود نداشته باشد، عکس فوری بازگشتی null است.

  firebase::Future&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("Leaders").GetValue();

در نقطه‌ای که درخواست انجام شده است، باید منتظر بمانیم تا آینده تکمیل شود تا بتوانیم مقدار را بخوانیم. از آنجایی که بازی‌ها معمولاً در یک حلقه اجرا می‌شوند و نسبت به سایر برنامه‌ها کمتر پاسخگوی تماس هستند، معمولاً برای تکمیل نظرسنجی انجام می‌دهید.

  // In the game loop that polls for the result...

  if (result.status() != firebase::kFutureStatusPending) {
    if (result.status() != firebase::kFutureStatusComplete) {
      LogMessage("ERROR: GetValue() returned an invalid result.");
      // Handle the error...
    } else if (result.error() != firebase::database::kErrorNone) {
      LogMessage("ERROR: GetValue() returned error %d: %s", result.error(),
                 result.error_message());
      // Handle the error...
    } else {
      firebase::database::DataSnapshot snapshot = result.result();
      // Do something with the snapshot...
    }
  }

این بررسی برخی از بررسی خطاهای اساسی را نشان می دهد، برای اطلاعات بیشتر در مورد بررسی خطا، و راه هایی برای تعیین زمان آماده شدن نتیجه، به firebase:: مرجع آینده مراجعه کنید.

به رویدادها گوش دهید

می‌توانید شنونده‌هایی را برای اشتراک در تغییرات داده‌ها اضافه کنید:

کلاس پایه ValueListener

پاسخ به تماس	استفاده معمولی
OnValueChanged	برای تغییرات در کل محتوای یک مسیر بخوانید و گوش دهید.

کلاس پایه OnChildListener

OnChildAdded	لیستی از آیتم ها را بازیابی کنید یا برای اضافات به لیستی از موارد گوش دهید. استفاده از OnChildChanged و OnChildRemoved برای نظارت بر تغییرات فهرست‌ها پیشنهاد می‌شود.
OnChildChanged	به تغییرات در موارد موجود در یک لیست گوش دهید. با OnChildAdded و OnChildRemoved برای نظارت بر تغییرات لیست ها استفاده کنید.
OnChildRemoved	به مواردی که از لیست حذف می شوند گوش دهید. با OnChildAdded و OnChildChanged برای نظارت بر تغییرات لیست ها استفاده کنید.
OnChildMoved	به تغییرات در ترتیب اقلام در یک لیست مرتب گوش دهید. پاسخ‌های تماس OnChildMoved همیشه از تماس‌های OnChildChanged پیروی می‌کنند زیرا ترتیب آن تغییر می‌کند (بر اساس روش سفارشی فعلی شما).

کلاس ValueListener

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

مهم: رویداد OnValueChanged هر بار که داده ها در مرجع پایگاه داده مشخص شده تغییر می کنند، از جمله تغییرات مربوط به فرزندان، فراخوانی می شود. برای محدود کردن اندازه عکس‌های فوری خود، فقط در بالاترین سطح مورد نیاز برای تماشای تغییرات پیوست کنید. به عنوان مثال، پیوست کردن شنونده به ریشه پایگاه داده توصیه نمی شود.

مثال زیر یک بازی را نشان می‌دهد که امتیازات یک تابلوی امتیازات را از پایگاه داده بازیابی می‌کند:

  class LeadersValueListener : public firebase::database::ValueListener {
   public:
    void OnValueChanged(
        const firebase::database::DataSnapshot& snapshot) override {
      // Do something with the data in snapshot...
    }
    void OnCancelled(const firebase::database::Error& error_code,
                     const char* error_message) override {
      LogMessage("ERROR: LeadersValueListener canceled: %d: %s", error_code,
                 error_message);
    }
  };

  // Elsewhere in the code...

  LeadersValueListener* listener = new LeadersValueListener();
  firebase::Future&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("Leaders").AddValueListener(listener);

نتیجه Future&ltDataSnapshot&gt حاوی داده ها در مکان مشخص شده در پایگاه داده در زمان رویداد است. فراخوانی value() روی یک عکس فوری، یک Variant را برمی گرداند که نشان دهنده داده ها است.

در این مثال، متد OnCancelled نیز لغو می شود تا ببیند آیا خواندن لغو شده است یا خیر. برای مثال، اگر کلاینت مجوز خواندن از محل پایگاه داده Firebase را نداشته باشد، می‌توان یک خواندن را لغو کرد. database::Error نشان می دهد که چرا شکست رخ داده است.

کلاس ChildListener

رویدادهای فرزند در پاسخ به عملیات خاصی که برای فرزندان یک گره از عملیاتی مانند فرزند جدید اضافه شده از طریق متد PushChild() یا فرزندی که از طریق متد UpdateChildren() به روز می شود، فعال می شوند. هر یک از اینها با هم می توانند برای گوش دادن به تغییرات یک گره خاص در پایگاه داده مفید باشند. به عنوان مثال، یک بازی ممکن است از این روش ها برای نظارت بر فعالیت در نظرات جلسه بازی استفاده کند، همانطور که در زیر نشان داده شده است:

  class SessionCommentsChildListener : public firebase::database::ChildListener {
   public:
    void OnChildAdded(const firebase::database::DataSnapshot& snapshot,
                      const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnChildChanged(const firebase::database::DataSnapshot& snapshot,
                        const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnChildRemoved(
        const firebase::database::DataSnapshot& snapshot) override {
      // Do something with the data in snapshot ...
    }
    void OnChildMoved(const firebase::database::DataSnapshot& snapshot,
                      const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnCancelled(const firebase::database::Error& error_code,
                     const char* error_message) override {
      LogMessage("ERROR: SessionCommentsChildListener canceled: %d: %s",
                 error_code, error_message);
    }
  };

  // elsewhere ....

  SessionCommentsChildListener* listener = new SessionCommentsChildListener();
  firebase::Future&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("GameSessionComments").AddChildListener(listener);

پاسخ تماس OnChildAdded معمولاً برای بازیابی لیستی از موارد در پایگاه داده Firebase استفاده می شود. فراخوانی OnChildAdded یک بار برای هر فرزند موجود و سپس دوباره هر بار که فرزند جدیدی به مسیر مشخص شده اضافه می شود، فراخوانی می شود. یک عکس فوری حاوی داده‌های کودک جدید به شنونده ارسال می‌شود.

پاسخ تماس OnChildChanged هر زمان که یک گره فرزند اصلاح شود فراخوانی می شود. این شامل هرگونه تغییر در نوادگان گره فرزند می شود. معمولاً همراه با تماس‌های OnChildAdded و OnChildRemoved برای پاسخ دادن به تغییرات فهرست موارد استفاده می‌شود. عکس فوری ارسال شده به شنونده حاوی داده های به روز شده برای کودک است.

پاسخ تماس OnChildRemoved زمانی فعال می شود که یک فرزند فوری حذف شود. معمولاً همراه با تماس‌های OnChildAdded و OnChildChanged استفاده می‌شود. عکس فوری ارسال شده به پاسخ تماس حاوی داده های فرزند حذف شده است.

زمانی که تماس OnChildChanged توسط به‌روزرسانی‌ای که باعث ترتیب مجدد فرزند می‌شود، برقرار می‌شود، پاسخ تماس OnChildMoved فعال می‌شود. با داده هایی که با OrderByChild یا OrderByValue سفارش داده شده اند استفاده می شود.

مرتب سازی و فیلتر کردن داده ها

می توانید از کلاس Realtime Database Query برای بازیابی داده های مرتب شده بر اساس کلید، ارزش یا مقدار فرزند استفاده کنید. همچنین می توانید نتیجه مرتب شده را به تعداد مشخصی از نتایج یا طیفی از کلیدها یا مقادیر فیلتر کنید.

توجه: فیلتر کردن و مرتب‌سازی می‌تواند گران باشد، به خصوص زمانی که روی مشتری انجام شود. اگر برنامه شما از عبارت‌های جستجو استفاده می‌کند، قانون .indexOn را برای فهرست کردن آن کلیدها در سرور و بهبود عملکرد درخواست همانطور که در نمایه‌سازی داده‌های شما توضیح داده شده است، تعریف کنید.

مرتب سازی داده ها

برای بازیابی داده‌های مرتب شده، با مشخص کردن یکی از روش‌های ترتیب‌بندی شده شروع کنید تا نحوه ترتیب‌بندی نتایج را مشخص کنید:

روش	استفاده
OrderByChild()	نتایج را بر اساس مقدار کلید فرزند مشخص شده مرتب کنید.
OrderByKey()	نتایج را با کلیدهای فرزند مرتب کنید.
OrderByValue()	نتایج را بر اساس مقادیر فرزند مرتب کنید.

هر بار فقط می توانید از یک روش سفارشی استفاده کنید. چندین بار فراخوانی یک متد سفارشی در یک کوئری یک خطا ایجاد می کند.

مثال زیر نشان می‌دهد که چگونه می‌توانید در جدول امتیازات مرتب شده بر اساس امتیاز مشترک شوید.

  firebase::database::Query query =
    dbRef.GetReference("Leaders").OrderByChild("score");

  // To get the resulting DataSnapshot either use query.GetValue() and poll the
  // future, or use query.AddValueListener() and register to handle the
  // OnValueChanged callback.

این یک firebase::Query را تعریف می‌کند که وقتی با ValueListener ترکیب می‌شود، مشتری را با تابلوی امتیازات در پایگاه داده، مرتب‌سازی شده بر اساس امتیاز هر ورودی، همگام‌سازی می‌کند. می‌توانید در مورد ساختاردهی کارآمد داده‌های خود در Structure Your Database اطلاعات بیشتری کسب کنید.

فراخوانی متد OrderByChild() کلید فرزند را برای مرتب کردن نتایج مشخص می کند. در این مورد، نتایج بر اساس مقدار "score" در هر فرزند مرتب می شوند. برای اطلاعات بیشتر در مورد نحوه ترتیب‌دهی انواع دیگر داده‌ها، به نحوه ترتیب داده‌های جستجو مراجعه کنید.

فیلتر کردن داده ها

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

روش	استفاده
LimitToFirst()	حداکثر تعداد آیتم هایی را برای بازگشت از ابتدای فهرست ترتیب یافته نتایج تنظیم می کند.
LimitToLast()	حداکثر تعداد مواردی را برای بازگشت از انتهای لیست نتایج مرتب شده تنظیم می کند.
StartAt()	بسته به روش سفارشی انتخاب شده، اقلام بزرگتر یا مساوی با کلید یا مقدار مشخص شده را برگردانید.
EndAt()	بسته به روش سفارشی انتخاب شده، موارد کمتر یا مساوی با کلید یا مقدار مشخص شده را برگردانید.
EqualTo()	بسته به روش سفارشی انتخاب شده، موارد را برابر با کلید یا مقدار مشخص شده برگردانید.

برخلاف روش‌های مرتب‌سازی، می‌توانید چندین تابع محدود یا محدوده را ترکیب کنید. به عنوان مثال، می توانید متدهای StartAt() و EndAt() را ترکیب کنید تا نتایج را به محدوده مشخصی از مقادیر محدود کنید.

حتی زمانی که فقط یک مورد منطبق برای پرس و جو وجود دارد، عکس فوری همچنان یک لیست است. فقط شامل یک مورد واحد است.

تعداد نتایج را محدود کنید

شما می توانید از متدهای LimitToFirst() و LimitToLast() برای تنظیم حداکثر تعداد فرزندان جهت همگام سازی برای یک فراخوان معین استفاده کنید. به عنوان مثال، اگر از LimitToFirst() برای تعیین حد 100 استفاده کنید، در ابتدا فقط تا 100 تماس OnChildAdded دریافت می کنید. اگر کمتر از 100 مورد در پایگاه داده Firebase خود ذخیره کرده اید، برای هر مورد یک پاسخ تماس OnChildAdded فعال می شود.

با تغییر موارد، پاسخ‌های تماس OnChildAdded را برای مواردی که وارد پرس‌وجو می‌شوند و پاسخ‌های OnChildRemoved را برای مواردی که از آن حذف می‌شوند دریافت می‌کنید، به طوری که تعداد کل در 100 باقی می‌ماند.

برای مثال، کد زیر امتیاز برتر را از تابلوی امتیازات برمی‌گرداند:

  firebase::database::Query query =
    dbRef.GetReference("Leaders").OrderByChild("score").LimitToLast(1);

  // To get the resulting DataSnapshot either use query.GetValue() and poll the
  // future, or use query.AddValueListener() and register to handle the
  // OnValueChanged callback.

بر اساس کلید یا مقدار فیلتر کنید

می توانید از StartAt() ، EndAt() و EqualTo() برای انتخاب نقطه شروع، پایان و معادل سازی دلخواه برای پرس و جوها استفاده کنید. این می‌تواند برای صفحه‌بندی داده‌ها یا یافتن مواردی با کودکان که دارای ارزش خاصی هستند مفید باشد.

نحوه سفارش داده های پرس و جو

این بخش توضیح می‌دهد که چگونه داده‌ها بر اساس هر یک از روش‌های مرتب‌سازی در کلاس Query مرتب می‌شوند.

OrderByChild

هنگام استفاده از OrderByChild() ، داده هایی که حاوی کلید فرزند مشخص شده هستند به صورت زیر مرتب می شوند:

1. کودکان با مقدار null برای کلید فرزند مشخص شده اول هستند.
2. کودکان با مقدار false برای کلید فرزند مشخص شده در مرحله بعدی قرار می گیرند. اگر چند فرزند مقدار false داشته باشند، از نظر واژگانی بر اساس کلید مرتب می شوند.
3. کودکان با مقدار true برای کلید فرزند مشخص شده در مرحله بعدی قرار می گیرند. اگر چند فرزند مقدار true داشته باشند، از نظر واژگانی بر اساس کلید مرتب می شوند.
4. کودکان با مقدار عددی در مرحله بعدی قرار می گیرند که به ترتیب صعودی مرتب شده اند. اگر چندین فرزند مقدار عددی یکسانی برای گره فرزند مشخص شده داشته باشند، آنها بر اساس کلید مرتب می شوند.
5. رشته ها بعد از اعداد آمده و از نظر واژگانی به ترتیب صعودی مرتب شده اند. اگر چندین فرزند مقدار یکسانی برای گره فرزند مشخص شده داشته باشند، آنها از نظر واژگانی بر اساس کلید مرتب می شوند.
6. اشیاء در آخر قرار می گیرند و از نظر واژگانی بر اساس کلید به ترتیب صعودی مرتب می شوند.

OrderByKey

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

1. کودکان دارای کلیدی که می تواند به عنوان یک عدد صحیح 32 بیتی تجزیه شود، در درجه اول قرار می گیرند و به ترتیب صعودی مرتب می شوند.
2. کودکان با مقدار رشته به عنوان کلید در مرحله بعدی قرار می گیرند که از نظر واژگانی به ترتیب صعودی مرتب شده اند.

OrderByValue

هنگام استفاده از OrderByValue() ، بچه ها بر اساس مقدارشان مرتب می شوند. معیارهای مرتب سازی مانند OrderByChild() است، با این تفاوت که مقدار گره به جای مقدار کلید فرزند مشخص شده استفاده می شود.

مراحل بعدی

• ذخیره داده ها