Firebase Database REST API

استفاده از API

می توانید از هر URL پایگاه داده بیدرنگ Firebase به عنوان نقطه پایانی REST استفاده کنید. تنها کاری که باید انجام دهید این است که .json به انتهای URL اضافه کنید و یک درخواست از مشتری HTTPS مورد علاقه خود ارسال کنید.

HTTPS مورد نیاز است. Firebase فقط به ترافیک رمزگذاری شده پاسخ می دهد تا داده های شما ایمن باقی بماند.

می توانید منطقه ای را انتخاب کنید که در آن یک نمونه پایگاه داده بیدرنگ ایجاد شود. انتخاب منطقه بر URL پایگاه داده تأثیر می گذارد. نمونه‌هایی در این صفحه برای منطقه us-central1 ، با طرح URL <dbname>.firebaseio.com هستند. برای مناطقی که در حال حاضر پشتیبانی می‌شوند و طرح‌های URL، به مبحث راهنماهای انتخاب مکان در پروژه‌های Firebase مراجعه کنید.

GET - خواندن داده ها

داده های پایگاه داده بیدرنگ شما را می توان با ارسال یک درخواست HTTP GET به نقطه پایانی خواند. مثال زیر نشان می دهد که چگونه می توانید نام کاربری را که قبلاً در پایگاه داده Realtime ذخیره کرده بودید بازیابی کنید.

curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

در مثال‌های این صفحه، شناسه پروژه Firebase خود را جایگزین [PROJECT_ID] می‌کنید.

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

{ "first": "Jack", "last": "Sparrow" }

PUT - نوشتن داده ها

می توانید داده ها را با درخواست PUT بنویسید.

curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

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

{ "first": "Jack", "last": "Sparrow" }

POST - فشار دادن داده ها

برای انجام معادل متد push() جاوا اسکریپت (به لیست داده ها مراجعه کنید)، می توانید یک درخواست POST صادر کنید.

curl -X POST -d '{"user_id" : "jack", "text" : "Ahoy!"}' \
  'https://[PROJECT_ID].firebaseio.com/message_list.json'

یک درخواست موفقیت آمیز با یک کد وضعیت HTTP 200 OK نشان داده می شود. پاسخ حاوی نام فرزند داده های جدید مشخص شده در درخواست POST است.

{ "name": "-INOQPH-aV_psbk3ZXEX" }

PATCH - به روز رسانی داده ها

می‌توانید کودکان خاصی را در یک مکان بدون بازنویسی داده‌های موجود با استفاده از درخواست PATCH به‌روزرسانی کنید. فرزندان نام‌گذاری شده در داده‌هایی که با PATCH نوشته می‌شوند رونویسی می‌شوند، اما فرزندان حذف‌شده حذف نمی‌شوند. این معادل تابع update() جاوا اسکریپت است.

curl -X PATCH -d '{"last":"Jones"}' \
 'https://[PROJECT_ID].firebaseio.com/users/jack/name/.json'

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

{ "last": "Jones" }

DELETE - حذف داده ها

با درخواست DELETE می توانید داده ها را حذف کنید:

curl -X DELETE \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

یک درخواست DELETE موفق با یک کد وضعیت HTTP 200 OK با یک پاسخ حاوی JSON null نشان داده می شود.

نادیده گرفتن روش

اگر از مرورگری که از روش‌های قبلی پشتیبانی نمی‌کند، تماس‌های REST برقرار می‌کنید، می‌توانید با ایجاد یک درخواست POST و تنظیم روش خود با استفاده از هدر درخواست X-HTTP-Method-Override ، روش درخواست را لغو کنید.

curl -X POST -H "X-HTTP-Method-Override: DELETE" \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

همچنین می توانید از پارامتر query x-http-method-override استفاده کنید.

curl -X POST \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json?x-http-method-override=DELETE'

درخواست های مشروط

درخواست‌های مشروط، معادل REST عملیات تراکنش‌های SDK، داده‌ها را براساس شرایط خاصی به‌روزرسانی می‌کنند. یک نمای کلی از گردش کار را ببینید و درباره درخواست‌های مشروط برای REST در Saving Data اطلاعات بیشتری کسب کنید.

Firebase ETag

Firebase ETag یک شناسه منحصر به فرد برای داده های فعلی در یک مکان مشخص است. اگر داده ها در آن مکان تغییر کنند، ETag نیز تغییر می کند. ETag Firebase باید در هدر درخواست REST اولیه مشخص شود (معمولا یک GET ، اما می تواند هر چیزی غیر از PATCH باشد).

curl -i 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'

اگر-مطابقت

شرط if-match مقدار ETag را برای داده هایی که می خواهید به روز کنید مشخص می کند. اگر از شرط استفاده می کنید، پایگاه داده بیدرنگ تنها درخواست هایی را تکمیل می کند که ETag مشخص شده در درخواست نوشتن با ETag داده های موجود در پایگاه داده مطابقت داشته باشد. ETag را در مکانی با درخواست Firebase ETag واکشی کنید. اگر می‌خواهید هر مکانی را که خالی است بازنویسی کنید، از null_etag استفاده کنید.

curl -iX PUT -d '11' 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'if-match: [ETAG_VALUE]'

پاسخ های مورد انتظار

جدول زیر یک نمای کلی از پاسخ های مورد انتظار برای هر نوع درخواست را بر اساس مطابقت ETag ارائه می دهد.

نوع درخواست		"X-Firebase-ETag: true"	ETag مطابقت دارد if_match: <matching etag>	ETag مطابقت ندارد if_match: <no matching etag>
گرفتن	وضعیت/محتوای پاسخ	200: "<data_at_path>"	400: "... پشتیبانی نمی شود.."	400: "... پشتیبانی نمی شود.."
	هدرهای اضافه شده	ETag: <ETag_of_data>	N/A	N/A
قرار دادن	وضعیت/محتوای پاسخ	200: "<put_data>"	200: "<put_data>"	412: "...عدم تطابق ETag.."
	هدرهای اضافه شده	ETag: <ETag_of_put_data>	N/A	ETag: <database_ETag>
پست	وضعیت/محتوای پاسخ	200: "<post_data>"	400: "... پشتیبانی نمی شود.."	400: "... پشتیبانی نمی شود.."
	هدرهای اضافه شده	ETag: <ETag_of_post_data>	N/A	N/A
پچ	وضعیت/محتوای پاسخ	400: "... پشتیبانی نمی شود.."	400: "... پشتیبانی نمی شود.."	400: "... پشتیبانی نمی شود.."
	هدرهای اضافه شده	N/A	N/A	N/A
حذف	وضعیت/محتوای پاسخ	200: صفر	200: "<data_after_put>"	412: "...عدم تطابق ETag.."
	هدرهای اضافه شده	ETag: <ETag_of_null>	N/A	ETag: <database_ETag>

پارامترهای پرس و جو

Firebase Database REST API پارامترها و مقادیر پرس و جوی زیر را می پذیرد:

نشانه دسترسی

توسط همه نوع درخواست پشتیبانی می شود. این درخواست را احراز هویت می کند تا اجازه دسترسی به داده های محافظت شده توسط قوانین امنیتی پایگاه داده بیدرنگ Firebase را بدهد. برای جزئیات به مستندات احراز هویت REST مراجعه کنید.

curl 'https://[PROJECT_ID].firebaseio/users/jack/name.json?access_token=CREDENTIAL'

کم عمق

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

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

curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'

توجه داشته باشید که shallow نمی توان با هیچ پارامتر پرس و جو دیگری مخلوط کرد.

چاپ

داده های بازگردانده شده در پاسخ از سرور را قالب بندی می کند.

استدلال ها	روش های REST	شرح
بسیار	دریافت، قرار دادن، ارسال، وصله، حذف	داده ها را در قالبی قابل خواندن برای انسان مشاهده کنید.
بی صدا	دریافت، قرار دادن، ارسال، وصله	برای سرکوب خروجی از سرور هنگام نوشتن داده استفاده می شود. پاسخ به دست آمده خالی خواهد بود و با کد وضعیت HTTP 204 No Content نشان داده می شود.

curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=pretty'

curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=silent'

پاسخ به تماس

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

<script>
  function gotData(data) {
    console.log(data);
  }
</script>
<script src="https://[PROJECT_ID].firebaseio.com/.json?callback=gotData"></script>

قالب

اگر روی export تنظیم شود، سرور اولویت ها را در پاسخ کدگذاری می کند.

استدلال ها	روش های REST	شرح
صادرات	گرفتن	اطلاعات اولویت را در پاسخ درج کنید.

curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'

دانلود

فقط توسط GET پشتیبانی می شود. اگر می خواهید دانلود فایل داده های خود را از یک مرورگر وب آغاز کنید، download= اضافه کنید. این باعث می شود که سرویس REST هدرهای مناسب را اضافه کند تا مرورگرها بدانند که داده ها را در یک فایل ذخیره کنند.

curl 'https://[PROJECT_ID].firebaseio/.json?download=myfilename.txt'

پشتیبان گیری خصوصی : استفاده از REST API را برای پشتیبان گیری منظم از پایگاه داده بیدرنگ خود توصیه نمی کنیم. در عوض، با Firebase Private Backups راه‌اندازی کنید.

تایم اوت

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

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

writeSizeLimit

توجه: این پارامتر برای عملیات حذف و همچنین نوشتن اعمال می شود.

برای محدود کردن اندازه نوشتن، می‌توانید پارامتر query writeSizeLimit را به صورت tiny (target=1s)، small (target=10s)، medium ​​(target=30s)، large (target=60s) مشخص کنید. پایگاه داده Realtime اندازه هر درخواست نوشتن را تخمین می زند و درخواست هایی را که بیشتر از زمان مورد نظر طول می کشد لغو می کند.

اگر unlimited را مشخص کنید، نوشتن‌های فوق‌العاده بزرگ (با حداکثر 256 مگابایت بارگذاری) مجاز است، که احتمالاً درخواست‌های بعدی را در حالی که پایگاه داده عملیات جاری را پردازش می‌کند مسدود می‌کند. رایت ها پس از رسیدن به سرور قابل لغو نیستند.

curl -X DELETE 'https://docs-examples.firebaseio.com/rest/delete-data.json?writeSizeLimit=medium'

اگر نوشتن خیلی بزرگ باشد، پیغام خطای زیر را خواهید دید:

Error: WRITE_TOO_BIG: Data to write exceeds the maximum size that can be modified with a single request.

علاوه بر این، می‌توانید defaultWriteSizeLimit برای کل نمونه پایگاه داده با استفاده از Firebase CLI تنظیم کنید. این محدودیت برای همه درخواست‌ها از جمله درخواست‌های SDK اعمال می‌شود. پایگاه داده های جدید با defaultWriteSizeLimit روی large ایجاد می شوند. با استفاده از Firebase CLI نمی‌توانید defaultWriteSizeLimit روی tiny تنظیم کنید.

firebase database:settings:set defaultWriteSizeLimit large

حذف بزرگ عمدی: برای حذف یک گره بزرگ، استفاده از Firebase CLI را در نظر بگیرید، که به زیبایی حذف های تکه ای را انجام می دهد. حذف های بزرگ از طریق سرویس گیرنده یا Admin SDK ممکن است پایگاه داده شما را تا زمانی که حذف کامل شود مسدود کند.

firebase database:remove /large/path/to/delete

برای اطلاعات بیشتر به این پست وبلاگ مراجعه کنید.

سفارش توسط

برای اطلاعات بیشتر به بخش راهنمای داده های سفارش داده شده مراجعه کنید.

limitToFirst، limitToLast، startAt، endAt، equalTo

برای اطلاعات بیشتر به بخش راهنمای فیلتر کردن داده ها مراجعه کنید.

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

نقاط پایانی Firebase REST از پروتکل EventSource / Server-Sent Events پشتیبانی می کنند. برای پخش جریانی تغییرات به یک مکان واحد در پایگاه داده بیدرنگ خود، باید چند کار را انجام دهید:

• هدر پذیرش مشتری را روی "text/event-stream" تنظیم کنید
• به تغییر مسیرهای HTTP، به ویژه کد وضعیت HTTP 307 احترام بگذارید
• اگر مکان برای خواندن به مجوز نیاز دارد، باید پارامتر auth را وارد کنید

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

event: event name
data: JSON encoded data payload

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

قرار دادن

داده های رمزگذاری شده با JSON یک شی با دو کلید است: مسیر و داده . کلید مسیر به مکانی نسبت به URL درخواست اشاره می کند. کلاینت باید تمام داده های موجود در آن مکان در حافظه پنهان خود را با داده جایگزین کند.

پچ

داده های رمزگذاری شده با JSON یک شی با دو کلید است: مسیر و داده . کلید مسیر به مکانی نسبت به URL درخواست اشاره می کند. برای هر کلید در داده ، مشتری باید کلید مربوطه را در حافظه پنهان خود با داده های آن کلید در پیام جایگزین کند.

زنده بمان

داده های این رویداد null است. هیچ اقدامی لازم نیست.

لغو

برخی از خطاهای غیرمنتظره می توانند رویداد «لغو» را ارسال کرده و اتصال را خاتمه دهند. علت در داده های ارائه شده برای این رویداد توضیح داده شده است. برخی از دلایل احتمالی به شرح زیر است: 1. قوانین امنیتی پایگاه داده بیدرنگ Firebase دیگر اجازه خواندن در مکان درخواستی را نمی دهد. توصیف "داده" برای این دلیل "مجوز رد شد." 2. یک نوشتن، پخش کننده رویدادی را راه اندازی کرد که درخت JSON بزرگی را ارسال کرد که از حد مجاز ما، یعنی 512 مگابایت فراتر رفت. «داده» برای این دلیل این است که «بار مشخص شده خیلی بزرگ است، لطفاً مکانی با داده کمتر درخواست کنید».

auth_revokuar

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

اولویت های

اطلاعات اولویت برای یک مکان را می توان با یک "فرزند مجازی" به نام .priority ارجاع داد. شما می توانید اولویت ها را با درخواست های GET بخوانید و آنها را با درخواست های PUT بنویسید. به عنوان مثال، درخواست زیر اولویت گره users/tom را بازیابی می کند:

curl 'https://[PROJECT_ID].firebaseio/users/tom/.priority.json'

برای نوشتن اولویت و داده به طور همزمان، می توانید یک فرزند .priority بار JSON اضافه کنید:

curl -X PUT -d '{"name": {"first": "Tom"}, ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio/users/tom.json'

برای نوشتن اولویت و یک مقدار اولیه (به عنوان مثال یک رشته) به طور همزمان، می توانید یک فرزند .priority اضافه کنید و مقدار اولیه را در یک فرزند .value قرار دهید:

curl -X PUT -d '{".value": "Tom", ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio/users/tom/name/first.json'

این "Tom" با اولویت 1.0 می نویسد. اولویت ها را می توان در هر عمقی در بار JSON گنجاند.

ارزش های سرور

شما می توانید مقادیر سرور را در یک مکان با استفاده از یک مکان نگهدار که یک شی با یک کلید .sv است بنویسید. مقدار آن کلید نوع ارزش سروری است که می خواهید تنظیم کنید. به عنوان مثال، درخواست زیر مقدار گره را با مهر زمانی فعلی سرور Firebase تنظیم می کند:

curl -X PUT -d '{".sv": "timestamp"}' \
  'https://[PROJECT_ID].firebaseio/users/tom/startedAtTime.json'

همچنین می توانید با استفاده از مسیر "فرزند مجازی" که در بالا ذکر شد، اولویت ها را با استفاده از مقادیر سرور بنویسید.

مقادیر سرور پشتیبانی شده عبارتند از:

ارزش سرور
مهر زمانی	زمان از دوران یونیکس، در میلی ثانیه.
افزایش	یک مقدار دلتای عدد صحیح یا ممیز شناور به شکل { ".sv": {"increment": <delta_value> }} ارائه کنید، که با آن مقدار فعلی پایگاه داده را به صورت اتمی افزایش دهید. اگر داده ها هنوز وجود نداشته باشند، به روز رسانی داده ها را روی مقدار دلتا تنظیم می کند. اگر یکی از مقادیر دلتا یا داده‌های موجود، اعداد ممیز شناور باشند، هر دو مقدار به عنوان اعداد ممیز شناور تفسیر می‌شوند و در قسمت پشتی به عنوان یک مقدار دوگانه اعمال می‌شوند. حساب دوگانه و نمایش مقادیر دوگانه از معنای IEEE 754 پیروی می کند. اگر سرریز عدد صحیح مثبت/منفی وجود داشته باشد، مجموع آن دو برابر محاسبه می شود.

بازیابی و به روز رسانی قوانین امنیتی پایگاه داده بیدرنگ Firebase

REST API همچنین می تواند برای بازیابی و به روز رسانی قوانین امنیتی پایگاه داده بیدرنگ Firebase برای پروژه Firebase شما استفاده شود. شما به راز پروژه Firebase خود نیاز دارید که می توانید آن را در پانل حساب های خدماتی تنظیمات پروژه Firebase خود بیابید.

curl 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'
curl -X PUT -d '{ "rules": { ".read": true } }' 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'

احراز هویت درخواست ها

به‌طور پیش‌فرض، درخواست‌های REST بدون احراز هویت اجرا می‌شوند و تنها در صورتی موفق می‌شوند که قوانین پایگاه داده بلادرنگ اجازه دسترسی خواندن یا نوشتن عمومی به داده‌ها را بدهد. برای احراز هویت درخواست خود، از پارامترهای query access_token= یا auth= استفاده کنید.

درباره احراز هویت از طریق REST API در Authenticate REST Requests بیشتر بیاموزید.

شرایط خطا

Firebase Database REST API می تواند کدهای خطای زیر را برگرداند.

کدهای وضعیت HTTP
400 درخواست بد	یکی از شرایط خطای زیر: تجزیه و تحلیل داده های PUT یا POST امکان پذیر نیست. داده PUT یا POST وجود ندارد. این درخواست سعی می کند داده هایی را که خیلی بزرگ هستند PUT یا POST . فراخوانی REST API شامل نام‌های فرزند نامعتبر به عنوان بخشی از مسیر است. مسیر تماس REST API خیلی طولانی است. درخواست حاوی یک مقدار سرور ناشناخته است. نمایه پرس و جو در قوانین امنیتی پایگاه داده بیدرنگ Firebase شما تعریف نشده است. درخواست از یکی از پارامترهای پرس و جو که مشخص شده است پشتیبانی نمی کند. این درخواست پارامترهای پرس و جو را با یک درخواست GET کم عمق ترکیب می کند.
401 غیر مجاز	یکی از شرایط خطای زیر: رمز تأیید منقضی شده است. رمز تأیید استفاده شده در درخواست نامعتبر است. احراز هویت با access_token انجام نشد. این درخواست قوانین امنیتی پایگاه داده بیدرنگ Firebase شما را نقض می کند.
404 پیدا نشد	پایگاه داده بیدرنگ مشخص شده یافت نشد.
500 خطای سرور داخلی	سرور یک خطا برگرداند. برای جزئیات بیشتر به پیام خطا مراجعه کنید.
503 خدمات در دسترس نیست	پایگاه داده بیدرنگ Firebase مشخص شده به طور موقت در دسترس نیست، به این معنی که درخواست انجام نشده است.
پیش شرط 412 ناموفق بود	مقدار ETag مشخص شده درخواست در هدر if-match با مقدار سرور مطابقت نداشت.