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

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

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

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 شما باشد یا یک نشانه احراز هویت، همانطور که در Users in Firebase Projects توضیح داده شده است. در مثال زیر، یک درخواست GET با یک پارامتر auth ارسال می‌کنیم، که در آن CREDENTIAL یا راز برنامه Firebase شما است یا یک نشانه احراز هویت:

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

اگر پرچم debug نشانه تنظیم شده باشد، اطلاعات اشکال زدایی را می توان در سربرگ X-Firebase-Auth-Debug پاسخ یافت.

چاپ کنید

تعیین 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 داده های برگشتی را در تابع 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'

shallow نمی توان با هیچ یک از پارامترهای پرس و جو "داده های فیلتر" استفاده کرد.

تایم اوت

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

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

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

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

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

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

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

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

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

فیلتر کردن توسط کلید فرزند مشخص شده

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

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 چندین بار در یک درخواست یک خطا ایجاد می کند.

افزودن نمایه سازی به Firebase Realtime Database Security Rules : اگر orderBy در برنامه خود استفاده می کنید، باید کلیدهایی را که از طریق قانون .indexOn نمایه می کنید را در Firebase Realtime Database Security Rules تعریف کنید. برای اطلاعات بیشتر مستندات مربوط به قانون .indexOn را بخوانید.

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

همچنین می‌توانیم گره‌ها را با کلیدهایشان با استفاده از پارامتر 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
  }
}

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

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

برای توضیح نحوه مرتب‌سازی مقادیر null ، boolean، string و object در هنگام استفاده از orderBy="$value" نحوه مرتب‌سازی داده‌ها را ببینید.

افزودن نمایه سازی به Firebase Realtime Database Security Rules : اگر orderBy="$value" در برنامه خود استفاده می کنید، باید .value در فهرست مناسب به قوانین خود اضافه کنید. برای اطلاعات بیشتر مستندات مربوط به قانون .indexOn را بخوانید.

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

ما می توانیم چندین پارامتر را برای ساخت پرس و جوهای پیچیده تر ترکیب کنیم.

محدودیت کوئری ها

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

با استفاده از پایگاه داده حقایق دایناسورها و 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 شامل هستند، به این معنی که "pterodactyl" با درخواست بالا مطابقت دارد.

ما می توانیم startAt و endAt ترکیب کنیم تا هر دو انتهای پرس و جو خود را محدود کنیم. مثال زیر تمام دایناسورهایی را که نام آنها با حرف "b" شروع می شود را پیدا می کند:

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

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

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

همه را کنار هم گذاشتن

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

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"

چگونه داده ها مرتب می شوند

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

REST API نتایج مرتب نشده را برمی گرداند : مفسرهای JSON هیچ ترتیبی را در مجموعه نتایج اعمال نمی کنند. در حالی که orderBy می‌تواند در ترکیب با startAt ، endAt ، limitToFirst یا limitToLast برای برگرداندن زیرمجموعه‌ای از داده‌ها استفاده شود، نتایج برگردانده شده مرتب‌سازی نمی‌شوند. بنابراین، اگر سفارش مهم است، ممکن است لازم باشد نتایج به صورت دستی مرتب شوند.

سفارش توسط

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

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

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

orderBy="$key"

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

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

orderBy="$value"

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

orderBy="$اولویت"

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

اولویت های عددی به صورت اعداد ممیز شناور با دقت دوگانه IEEE 754 ذخیره و مرتب می شوند. کلیدها همیشه به عنوان رشته ذخیره می شوند و تنها زمانی به عنوان عددی در نظر گرفته می شوند که بتوان آنها را به عنوان یک عدد صحیح 32 بیتی تجزیه کرد.

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_revokuar	داده های این رویداد رشته ای است که نشان می دهد اعتبار یک اعتبار منقضی شده است این رویداد زمانی ارسال می شود که پارامتر تأیید اعتبار ارائه شده دیگر معتبر نباشد

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

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