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

خواندن داده ها با 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'

چاپ کنید

تعیین 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'

تایم اوت

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

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

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

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

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

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

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

پارامترهای 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 ترکیب کنیم تا هر دو انتهای پرس و جو خود را محدود کنیم. مثال زیر تمام دایناسورهایی را که نام آنها با حرف "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. اشیاء در آخر قرار می گیرند و از نظر لغوی بر اساس کلید به ترتیب صعودی مرتب می شوند.

orderBy="$key"

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

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

orderBy="$value"

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

orderBy="$اولویت"

هنگام استفاده از پارامتر 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

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

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

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