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

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

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

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

یک درخواست موفق با کد وضعیت HTTP 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 برای قرار دادن پاسخ در یک تابع فراخوانی جاوا اسکریپت استفاده کنید. برای اینکه REST API داده‌های برگشتی را در تابع فراخوانی که شما مشخص می‌کنید، قرار دهد callback= را اضافه کنید. برای مثال:

<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 .

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

{
  "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 مرتب خواهد شد. برای جزئیات بیشتر در مورد نحوه مرتب‌سازی داده‌ها، به «نحوه مرتب‌سازی داده‌ها» مراجعه کنید.

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

{
  "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 ، boolean، string و object هنگام استفاده از 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 برای یافتن تمام دایناسورهایی که نامشان قبل از Pterodactyl آمده است، از نظر لغوی استفاده کنیم: 

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 به همراه نام یک کلید فرزند، داده‌هایی که حاوی کلید فرزند مشخص شده هستند به صورت زیر مرتب می‌شوند:

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

سفارش توسط="$key"

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

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

سفارش توسط ="مقدار $"

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

orderBy="$priority"

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

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

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

پخش جریانی از REST API

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

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

  1. هدر Accept کلاینت را روی text/event-stream تنظیم کنید.
  2. به ریدایرکت‌های HTTP، به ویژه کد وضعیت HTTP 307، احترام بگذارید.
  3. اگر محل پایگاه داده Firebase نیاز به مجوز خواندن دارد، پارامتر کوئری auth را وارد کنید.

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

event: event name
data: JSON encoded data payload

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

قرار دادن داده‌های کدگذاری شده با JSON یک شیء با دو کلید خواهند بود: مسیر و داده
مسیر به مکانی نسبت به URL درخواستی اشاره می‌کند.
کلاینت باید تمام داده‌های موجود در آن مکان از حافظه پنهان خود را با داده‌های داده شده در پیام جایگزین کند.
پچ داده‌های کدگذاری شده با JSON یک شیء با دو کلید خواهند بود: مسیر و داده
مسیر به مکانی نسبت به URL درخواستی اشاره می‌کند.
برای هر کلید در داده‌ها، کلاینت باید کلید مربوطه در حافظه پنهان خود را با داده‌های مربوط به آن کلید در پیام جایگزین کند.
زنده نگه داشتن داده‌ی این رویداد تهی است، هیچ اقدامی لازم نیست
لغو داده‌های این رویداد تهی است
این رویداد در صورتی ارسال می‌شود که 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 APIها.