درحال بازیابی داده‌ها

خواندن داده‌ها با GET

می‌توانیم با صدور درخواست GET به نقطه پایانی نشانی وب پایگاه داده Firebase، داده‌ها را از آن بخوانیم. بیایید مثال وبلاگ را از بخش قبلی ادامه دهیم و همه داده‌های پست وبلاگ را بخوانیم: 

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'

درخواست موفق با رمز وضعیت اچ‌تی‌تی‌پی 200 OK نشان داده می‌شود و پاسخ حاوی داده‌هایی است که بازیابی می‌کنیم.

افزودن پارامترهای URI

‫REST API هنگام خواندن داده‌ها از پایگاه داده Firebase ما، چندین پارامتر پُرسمان را می‌پذیرد. در زیر، رایج‌ترین پارامترهای مورداستفاده فهرست شده است. برای مشاهده فهرست کامل، به مرجع REST API مراجعه کنید.

اصالت‌سنجی

پارامتر درخواست auth امکان دسترسی به داده‌های محافظت‌شده توسط Firebase Realtime Database Security Rules را فراهم می‌کند و همه انواع درخواست از آن پشتیبانی می‌کنند. این آرگومان می‌تواند کلید خصوصی برنامه Firebase شما یا یک اصالت‌سنجی باشد، همان‌طور که در کاربران در پروژه‌های Firebase شرح داده شده است. در مثال زیر، درخواست GET را با پارامتر auth ارسال می‌کنیم، که در آن CREDENTIAL یا رمز برنامه Firebase شما است یا یک توکن اصالت‌سنجی: 

curl 'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'

چاپ

مشخص کردن print=pretty داده‌ها را در قالب قابل‌خواندن برای انسان برمی‌گرداند. 

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'

مشخص کردن print=silent درصورت موفقیت، 204 No Content را برمی‌گرداند. 

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=silent'

تماس برگشتی

برای برقراری تماس‌های REST از مرورگر وب در دامنه‌ها، می‌توانید از JSONP برای قرار دادن پاسخ در تابع بازخوانی جاوا اسکریپت استفاده کنید. callback= را اضافه کنید تا REST API داده‌های برگردانده‌شده را در تابع بازخوانی که مشخص می‌کنید قرار دهد. برای مثال: 

<script>
  function gotData(data) {
    console.log(data);
  }
</script>
<script src="https://docs-examples.firebaseio.com/fireblog/posts.json?callback=gotData">

کم‌عمق

این ویژگی پیشرفته‌ای است که برای کمک به شما در کار با مجموعه‌های داده بزرگ بدون نیاز به بارگیری همه چیز طراحی شده است. برای استفاده از آن، shallow=true را به‌عنوان پارامتر اضافه کنید. این کار عمق داده‌های برگردانده‌شده را محدود می‌کند. اگر داده‌های موجود در مکان از نوع JSON اولیه (رشته، عدد، یا بولی) باشد، مقدار آن به‌سادگی برگردانده می‌شود. اگر عکس آنی داده در مکان، شیء JSON باشد، مقادیر هر کلید به true کوتاه می‌شود. برای مثال، بااستفاده از داده‌های زیر: 

{
  "message": {
    "user": {
      "name": "Chris"
    },
    "body": "Hello!"
  }
}

// A request to /message.json?shallow=true
// would return the following:
{
  "user": true,
  "body": true
}

// A request to /message/body.json?shallow=true
// would simply return:
"Hello!"

با این درخواست curl آن را امتحان کنید: 

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?shallow=true&print=pretty'

درنگ

از این مورد برای محدود کردن مدت زمان خواندن در سمت سرور استفاده کنید. اگر درخواست خواندن در زمان اختصاص‌داده‌شده تکمیل نشود، با خطای HTTP 400 خاتمه می‌یابد. این به‌ویژه زمانی مفید است که انتظار انتقال داده کمی دارید و نمی‌خواهید برای واکشی زیردرخت بالقوه بزرگ خیلی منتظر بمانید. زمان خواندن واقعی ممکن است براساس اندازه داده و ذخیره‌سازی در حافظه نهان متفاوت باشد.

timeouts را بااستفاده از قالب زیر مشخص کنید: 3ms، 3s، یا 3min، با عدد و واحد. اگر مشخص نشده باشد، حداکثر timeout از 15min اعمال خواهد شد. اگر timeout مثبت نباشد یا از حداکثر فراتر رود، درخواست با خطای HTTP 400 رد خواهد شد. در مثال زیر، درخواست GET شامل timeout ۱۰ ثانیه‌ای است. 

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?timeout=10s'

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

می‌توانیم پُرسمان‌هایی را برای فیلتر کردن داده‌ها براساس عوامل مختلف بسازیم. برای شروع، بااستفاده از پارامتر orderBy مشخص می‌کنید که می‌خواهید داده‌هایتان چگونه فیلتر شود. سپس، orderBy را با هرکدام از پنج پارامتر دیگر ترکیب می‌کنید: limitToFirst،‏ limitToLast،‏ startAt،‏ endAt، و equalTo.

ازآنجایی‌که همه ما در Firebase فکر می‌کنیم دایناسورها خیلی جالب هستند، از قطعه‌ای از پایگاه داده نمونه حقایق دایناسورها استفاده می‌کنیم تا نشان دهیم چگونه می‌توانید داده‌ها را فیلتر کنید: 

{
  "lambeosaurus": {
    "height": 2.1,
    "length": 12.5,
    "weight": 5000
  },
  "stegosaurus": {
    "height": 4,
    "length": 9,
    "weight": 2500
  }
}

می‌توانیم داده‌ها را به یکی از سه روش فیلتر کنیم: براساس کلید فرزند، براساس کلید، یا براساس مقدار. پُرسمان با یکی از این پارامترها شروع می‌شود و سپس باید با یک یا چند پارامتر زیر ترکیب شود: startAt،‏ endAt،‏ limitToFirst،‏ limitToLast، یا equalTo.

فیلتر کردن براساس کلید فرزند مشخص‌شده

می‌توانیم گره‌ها را براساس کلید فرزند مشترک با ارسال آن کلید به پارامتر orderBy فیلتر کنیم. برای مثال، برای بازیابی همه دایناسورهایی که ارتفاعشان بیشتر از ۳ است، می‌توانیم این کار را انجام دهیم: 

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'

هر گره‌ای که کلید فرعی موردنظر برای فیلتر کردن را نداشته باشد با مقدار null مرتب خواهد شد. برای جزئیات بیشتر درباره نحوه مرتب‌سازی داده‌ها، به نحوه مرتب‌سازی داده‌ها مراجعه کنید.

Firebase همچنین از پُرسمان‌های مرتب‌شده براساس فرزندان عمیقاً تودرتو پشتیبانی می‌کند، نه فقط فرزندان یک سطح پایین‌تر. این کار زمانی مفید است که داده‌های تودرتوی عمیقی مانند این داشته باشید: 

{
  "lambeosaurus": {
    "dimensions": {
      "height" : 2.1,
      "length" : 12.5,
      "weight": 5000
    }
  },
  "stegosaurus": {
    "dimensions": {
      "height" : 4,
      "length" : 9,
      "weight" : 2500
    }
  }
}

برای پُرسمان کردن ارتفاع، اکنون به‌جای یک کلید از مسیر کامل به شیء استفاده می‌کنیم: 

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="dimensions/height"&startAt=3&print=pretty'

پرس‌وجوها فقط می‌توانند براساس یک کلید در هر بار فیلتر شوند. استفاده از پارامتر orderBy چندین بار در یک درخواست باعث ایجاد خطا می‌شود.

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

همچنین می‌توانیم گره‌ها را بااستفاده از پارامتر orderBy="$key" براساس کلیدهایشان فیلتر کنیم. مثال زیر همه دایناسورهایی را که نامشان با حرف a تا m شروع می‌شود بازیابی می‌کند: 

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="a"&endAt="m"&print=pretty'

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

بااستفاده از پارامتر orderBy="$value" می‌توانیم گره‌ها را براساس مقدار کلیدهای فرزندشان فیلتر کنیم. فرض کنید دایناسورها مسابقه ورزشی دایناسوری دارند و ما امتیازهای آن‌ها را در قالب زیر پیگیری می‌کنیم: 

{
  "scores": {
    "bruhathkayosaurus": 55,
    "lambeosaurus": 21,
    "linhenykus": 80,
    "pterodactyl": 93,
    "stegosaurus": 5,
    "triceratops": 22
  }
}

برای بازیابی همه دایناسورهای با امتیاز بالاتر از ۵۰، می‌توانیم درخواست زیر را ارائه دهیم: 

curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&startAt=50&print=pretty'

برای توضیحی درباره نحوه مرتب‌سازی مقادیر null، بولی، رشته، و شیء هنگام استفاده از orderBy="$value"، به نحوه مرتب‌سازی داده‌ها مراجعه کنید.

فیلتر کردن پیچیده

می‌توانیم چندین پارامتر را ترکیب کنیم تا پُرسمان‌های پیچیده‌تری بسازیم.

محدود کردن پُرسمان‌ها

از پارامترهای limitToFirst و limitToLast برای تنظیم حداکثر تعداد فرزندانی که داده‌هایشان دریافت می‌شود استفاده می‌شود. اگر حد را ۱۰۰ تنظیم کنیم، فقط تا ۱۰۰ فرزند منطبق دریافت خواهیم کرد. اگر کمتر از ۱۰۰ پیام در پایگاه داده‌مان ذخیره شده باشد، همه فرزندان را دریافت خواهیم کرد. اما اگر بیش‌از ۱۰۰ پیام داشته باشیم، فقط داده‌های ۱۰۰ پیام را دریافت خواهیم کرد. اگر از limitToFirst استفاده کنیم، این پیام‌ها ۱۰۰ پیام اول مرتب‌شده خواهند بود و اگر از limitToLast استفاده کنیم، ۱۰۰ پیام آخر مرتب‌شده خواهند بود.

بااستفاده از پایگاه داده حقایق دایناسورها و orderBy، می‌توانیم دو دایناسور سنگین را پیدا کنیم: 

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="weight"&limitToLast=2&print=pretty'

به‌طور مشابه، می‌توانیم دو دایناسور کوتاه‌تر را بااستفاده از limitToFirst پیدا کنیم: 

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&limitToFirst=2&print=pretty'

همچنین می‌توانیم با orderBy="$value" پُرسمان‌های محدود انجام دهیم. اگر بخواهیم جدول رده‌بندی‌ای با سه رقیب برتر در ورزش دایناسورها ایجاد کنیم، می‌توانیم این کار را انجام دهیم: 

curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&limitToLast=3&print=pretty'

پرسمان‌های محدوده

استفاده از startAt، endAt، و equalTo به ما امکان می‌دهد نقاط شروع و پایان دلخواهی را برای پُرسمان‌هایمان انتخاب کنیم. برای مثال، اگر بخواهیم همه دایناسورهایی را که حداقل سه متر قد دارند پیدا کنیم، می‌توانیم orderBy و startAt را ترکیب کنیم: 

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'

می‌توانیم از endAt برای پیدا کردن همه دایناسورهایی که نامشان ازنظر واژه‌نامه‌ای قبل‌از «پتروداکتیل» می‌آید استفاده کنیم: 

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&endAt="pterodactyl"&print=pretty'

می‌توانیم startAt و endAt را ترکیب کنیم تا هر دو انتهای پُرسمان را محدود کنیم. مثال زیر همه دایناسورهایی را که نامشان با حرف «b» شروع می‌شود پیدا می‌کند: 

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="b"&endAt="b\uf8ff"&print=pretty'

پرسمان‌های گستره همچنین زمانی مفید هستند که نیاز به صفحه‌بندی داده‌های خود دارید.

درحال سرهم کردن

می‌توانیم همه این تکنیک‌ها را برای ایجاد پرسمان‌های پیچیده ترکیب کنیم. برای مثال، شاید بخواهید نام همه دایناسورهایی را که قدشان کوتاه‌تر یا مساوی با نوع موردعلاقه‌تان، استگوسور، است پیدا کنید: 

MY_FAV_DINO_HEIGHT=`curl "https://dinosaur-facts.firebaseio.com/dinosaurs/stegosaurus/height.json"`
curl "https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy=\"height\"&endAt=${MY_FAV_DINO_HEIGHT}&print=pretty"

نحوه مرتب‌سازی داده‌ها

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

orderBy

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

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

orderBy="$key"

هنگام استفاده از پارامتر orderBy="$key" برای مرتب‌سازی داده‌ها، داده‌ها به‌ترتیب صعودی براساس کلید به‌صورت زیر برگردانده می‌شوند. به‌خاطر داشته باشید که کلیدها فقط می‌توانند رشته باشند.

  1. فرزندان با کلیدی که می‌تواند به‌عنوان عدد صحیح ۳۲ بیتی تجزیه شود، ابتدا می‌آیند و به‌صورت صعودی مرتب می‌شوند.
  2. فرزندان با مقدار رشته‌ای به‌عنوان کلیدشان در ردیف بعدی قرار می‌گیرند و به‌ترتیب صعودی واژه‌نامه‌ای مرتب می‌شوند.

orderBy="$value"

هنگام استفاده از پارامتر orderBy="$value" برای مرتب‌سازی داده‌ها، فرزندان براساس مقدارشان مرتب خواهند شد. معیار ترتیب‌بندی همانند داده‌های مرتب‌شده براساس کلید فرزند است، با این تفاوت که به‌جای مقدار کلید فرزند مشخص‌شده، از مقدار گره استفاده می‌شود.

orderBy="$priority"

هنگام استفاده از پارامتر orderBy="$priority" برای مرتب‌سازی داده‌هایتان، ترتیب فرزندان براساس اولویت و کلید آن‌ها به‌صورت زیر تعیین می‌شود. به‌خاطر داشته باشید که مقادیر اولویت فقط می‌توانند عدد یا رشته باشند.

  1. کودکان بدون اولویت (پیش‌فرض) در ابتدا قرار می‌گیرند.
  2. کودکانی که اولویت آن‌ها با عدد مشخص شده است در رده بعدی قرار می‌گیرند. این فیلدها به‌صورت عددی براساس اولویت، از کوچک به بزرگ مرتب شده‌اند.
  3. فرزندانی که اولویت آن‌ها رشته است در آخر قرار می‌گیرند. آن‌ها به‌صورت واژه‌نگاری براساس اولویت مرتب شده‌اند.
  4. هرگاه دو فرزند اولویت یکسانی داشته باشند (ازجمله بدون اولویت)، براساس کلید مرتب می‌شوند. کلیدهای عددی اول می‌آیند (به‌ترتیب عددی مرتب شده‌اند)، و سپس کلیدهای باقی‌مانده (به‌ترتیب واژه‌نامه‌ای مرتب شده‌اند).

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

جاری‌سازی از REST API

پایانه‌های Firebase REST از پروتکل EventSource / Server-Sent Events پشتیبانی می‌کنند، که باعث می‌شود جریان دادن تغییرات به یک مکان واحد در پایگاه داده Firebase ما آسان شود.

برای شروع جاری‌سازی، باید کارهای زیر را انجام دهیم:

  1. سرصفحه Accept مشتری را روی text/event-stream تنظیم کنید
  2. رعایت «هدایت‌های HTTP»، به‌ویژه رمز وضعیت HTTP 307
  3. اگر مکان پایگاه داده Firebase به اجازه خواندن نیاز دارد، پارامتر پُرسمان auth را اضافه کنید

درمقابل، سرور رویدادهای نام‌گذاری‌شده را به‌عنوان وضعیت داده‌ها در نشانی وب درخواست‌شده ارسال می‌کند تغییرات. ساختار این پیام‌ها با پروتکل EventSource مطابقت دارد: 

event: event name
data: JSON encoded data payload

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

قرار دادن داده‌های JSON-encoded شیئی با دو کلید خواهد بود: path و data
path به مکانی مرتبط با نشانی وب درخواست اشاره می‌کند
کارخواه باید همه داده‌های آن مکان را در حافظه نهان خود با داده‌های ارائه‌شده در پیام جایگزین کند
وصله داده‌های کدبندی‌شده JSON شیئی با دو کلید خواهد بود: مسیر و داده
مسیر به مکانی مرتبط با نشانی وب درخواست اشاره می‌کند
برای هر کلید در داده‌ها، کارخواه باید کلید مربوطه را در حافظه نهان خود با داده‌های آن کلید در پیام جایگزین کند
زنده نگه داشتن داده‌های این رویداد تهی است، اقدامی لازم نیست
لغو کردن داده‌های این رویداد تهی است
اگر Firebase Realtime Database Security Rules باعث شود خواندن در مکان درخواستی دیگر مجاز نباشد، این رویداد ارسال خواهد شد
auth_revoked داده‌های این رویداد رشته‌ای است که نشان می‌دهد اعتبارنامه منقضی شده است
این رویداد زمانی ارسال می‌شود که پارامتر auth ارائه‌شده دیگر معتبر نباشد

در زیر نمونه‌ای از مجموعه‌ای از رویدادها که سرور ممکن است ارسال کند آورده شده است: 

// Set your entire cache to {"a": 1, "b": 2}
event: put
data: {"path": "/", "data": {"a": 1, "b": 2}}


// Put the new data in your cache under the key 'c', so that the complete cache now looks like:
// {"a": 1, "b": 2, "c": {"foo": true, "bar": false}}
event: put
data: {"path": "/c", "data": {"foo": true, "bar": false}}


// For each key in the data, update (or add) the corresponding key in your cache at path /c,
// for a final cache of: {"a": 1, "b": 2, "c": {"foo": 3, "bar": false, "baz": 4}}
event: patch
data: {"path": "/c", "data": {"foo": 3, "baz": 4}}

اگر از Go استفاده می‌کنید، Firego را بررسی کنید، یک پوشاننده شخص ثالث در اطراف Firebase REST و Streaming APIs.