Check out what’s new from Firebase at Google I/O 2022. Learn more

ذخیره داده ها

راه های ذخیره داده ها

قرار دادن نوشتن یا جایگزینی داده ها در یک مسیر تعریف شده ، مانند fireblog/users/user1/<data>
پچ برخی از کلیدها را برای یک مسیر تعریف شده بدون جایگزینی همه داده ها به روز کنید.
پست به لیستی از داده ها در پایگاه داده Firebase خود اضافه کنید. هر بار که درخواست POST ارسال می کنیم، مشتری Firebase یک کلید منحصر به فرد مانند fireblog/users/<unique-id>/<data> تولید می کند.
حذف داده ها را از مرجع پایگاه داده Firebase مشخص شده حذف کنید.

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

عملیات نوشتن اولیه از طریق REST API PUT است. برای نشان دادن ذخیره داده ها، ما یک برنامه وبلاگ نویسی با پست ها و کاربران می سازیم. همه داده‌های برنامه ما در مسیر «fireblog»، در URL پایگاه داده Firebase «https://docs-examples.firebaseio.com/fireblog» ذخیره می‌شود.

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

با استفاده از PUT ، می‌توانیم یک رشته، عدد، بولی، آرایه یا هر شی JSON را در پایگاه داده Firebase بنویسیم. در این مورد ما به آن یک شی ارسال می کنیم:

curl -X PUT -d '{
  "alanisawesome": {
    "name": "Alan Turing",
    "birthday": "June 23, 1912"
  }
}' 'https://docs-examples.firebaseio.com/fireblog/users.json'

هنگامی که یک شی JSON در پایگاه داده ذخیره می شود، ویژگی های شی به طور خودکار به مکان های فرزند به صورت تو در تو نگاشت می شوند. اگر به گره جدید ایجاد شده برویم، مقدار "Alan Turing" را خواهیم دید. همچنین می‌توانیم داده‌ها را مستقیماً در مکان کودک ذخیره کنیم:

curl -X PUT -d '"Alan Turing"' \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome/name.json'
curl -X PUT -d '"June 23, 1912"' \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome/birthday.json'

دو مثال بالا - نوشتن مقدار به طور همزمان به عنوان یک شی و نوشتن آنها به طور جداگانه در مکان های فرزند - منجر به ذخیره داده های مشابه در پایگاه داده Firebase ما می شود:

{
  "users": {
    "alanisawesome": {
      "date_of_birth": "June 23, 1912",
      "full_name": "Alan Turing"
    }
  }
}

یک درخواست موفقیت آمیز با یک کد وضعیت HTTP 200 OK نشان داده می شود و پاسخ حاوی داده هایی است که ما به پایگاه داده نوشتیم. مثال اول فقط یک رویداد را در مشتریانی که داده‌ها را تماشا می‌کنند راه‌اندازی می‌کند، در حالی که مثال دوم دو رویداد را راه‌اندازی می‌کند. توجه به این نکته مهم است که اگر داده‌ها قبلاً در مسیر کاربران وجود داشته باشد، روش اول آن را بازنویسی می‌کند، اما روش دوم فقط مقدار هر گره فرزند جداگانه را تغییر می‌دهد در حالی که سایر فرزندان را بدون تغییر می‌گذارد. PUT معادل set() در JavaScript SDK ما است.

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

با استفاده از یک درخواست PATCH ، می‌توانیم کودکان خاصی را در یک مکان بدون بازنویسی داده‌های موجود به‌روزرسانی کنیم. بیایید نام مستعار تورینگ را با یک درخواست PATCH به داده های کاربر او اضافه کنیم:

curl -X PATCH -d '{
  "nickname": "Alan The Machine"
}' \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome.json'

درخواست بالا بدون حذف name یا birthday فرزندان، nickname را به شیء alanisawesome ما می نویسد. توجه داشته باشید که اگر در اینجا درخواست PUT را صادر کرده بودیم، name و birthday حذف می شد زیرا در درخواست گنجانده نشده بود. داده های موجود در پایگاه داده Firebase ما اکنون به شکل زیر است:

{
  "users": {
    "alanisawesome": {
      "date_of_birth": "June 23, 1912",
      "full_name": "Alan Turing",
      "nickname": "Alan The Machine"
    }
  }
}

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

Firebase همچنین از به روز رسانی های چند مسیری پشتیبانی می کند. این بدان معنی است که PATCH اکنون می تواند مقادیر را در چندین مکان در پایگاه داده Firebase شما به طور همزمان به روز کند، یک ویژگی قدرتمند که به شما کمک می کند داده های خود را غیرعادی کنید . با استفاده از به‌روزرسانی‌های چند مسیری، می‌توانیم نام مستعار را به Alan و Grace به طور همزمان اضافه کنیم:

curl -X PATCH -d '{
  "alanisawesome/nickname": "Alan The Machine",
  "gracehopper/nickname": "Amazing Grace"
}' \
  'https://docs-examples.firebaseio.com/fireblog/users.json'

پس از این به روز رسانی، هر دو آلن و گریس نام مستعار خود را اضافه کردند:

{
  "users": {
    "alanisawesome": {
      "date_of_birth": "June 23, 1912",
      "full_name": "Alan Turing",
      "nickname": "Alan The Machine"
    },
    "gracehop": {
      "date_of_birth": "December 9, 1906",
      "full_name": "Grace Hopper",
      "nickname": "Amazing Grace"
    }
  }
}

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

curl -X PATCH -d '{
  "alanisawesome": {"nickname": "Alan The Machine"},
  "gracehopper": {"nickname": "Amazing Grace"}
}' \
  'https://docs-examples.firebaseio.com/fireblog/users.json'

این منجر به رفتارهای متفاوتی می شود، یعنی بازنویسی کل گره /fireblog/users :

{
  "users": {
    "alanisawesome": {
      "nickname": "Alan The Machine"
    },
    "gracehop": {
      "nickname": "Amazing Grace"
    }
  }
}

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

می‌توانید از درخواست‌های شرطی، معادل REST برای تراکنش‌ها، برای به‌روزرسانی داده‌ها با توجه به وضعیت موجود استفاده کنید. برای مثال، اگر می‌خواهید یک شمارنده رأی مثبت را افزایش دهید، و می‌خواهید مطمئن شوید که شمارش به طور دقیق چندین رأی مثبت را نشان می‌دهد، از یک درخواست شرطی برای نوشتن مقدار جدید در شمارنده استفاده کنید. به جای دو نوشتن که شمارنده را به یک عدد تغییر می دهند، یکی از درخواست های نوشتن با شکست مواجه می شود و سپس می توانید درخواست را با مقدار جدید دوباره امتحان کنید.
  1. برای انجام یک درخواست شرطی در یک مکان، شناسه منحصربه‌فرد برای داده‌های فعلی در آن مکان یا ETag را دریافت کنید. اگر داده ها در آن مکان تغییر کنند، ETag نیز تغییر می کند. شما می توانید با هر روشی غیر از PATCH یک ETag درخواست کنید. مثال زیر از یک درخواست GET استفاده می کند.
    curl -i 'https://test.example.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'
    
    به طور خاص فراخوانی ETag در هدر، ETag مکان مشخص شده در پاسخ HTTP را برمی‌گرداند.
    HTTP/1.1 200 OK
    Content-Length: 6
    Content-Type: application/json; charset=utf-8
    Access-Control-Allow-Origin: *
    ETag: [ETAG_VALUE]
    Cache-Control: no-cache
    
    10 // Current value of the data at the specified location
    
  2. ETag برگشتی را در درخواست PUT یا DELETE بعدی خود بگنجانید تا داده هایی را به روز کنید که به طور خاص با مقدار ETag مطابقت دارند. به دنبال مثال ما، برای به روز رسانی شمارنده به 11، یا 1 بزرگتر از مقدار اولیه واکشی شده 10، و عدم موفقیت در درخواست اگر مقدار دیگر مطابقت ندارد، از کد زیر استفاده کنید:
    curl -iX PUT -d '11' 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'if-match:[ETAG_VALUE]'
    
    اگر مقدار داده ها در مقدار مشخص شده باشد. مکان هنوز 10 است، ETag در درخواست PUT مطابقت دارد، و درخواست موفق می شود و 11 را در پایگاه داده می نویسد.
    HTTP/1.1 200 OK
    Content-Length: 6
    Content-Type: application/json; charset=utf-8
    Access-Control-Allow-Origin: *
    Cache-Control: no-cache
    
    11 // New value of the data at the specified location, written by the conditional request
    
    اگر مکان دیگر با ETag مطابقت نداشته باشد، که ممکن است در صورتی رخ دهد که کاربر دیگری مقدار جدیدی را در پایگاه داده بنویسد، درخواست بدون نوشتن در مکان با شکست مواجه می شود. پاسخ بازگشتی شامل مقدار جدید و ETag است.
    HTTP/1.1 412 Precondition Failed
    Content-Length: 6
    Content-Type: application/json; charset=utf-8
    Access-Control-Allow-Origin: *
    ETag: [ETAG_VALUE]
    Cache-Control: no-cache
    
    12 // New value of the data at the specified location
    
  3. اگر تصمیم دارید درخواست را دوباره امتحان کنید، از اطلاعات جدید استفاده کنید. پایگاه داده بیدرنگ به طور خودکار درخواست های شرطی را که شکست خورده اند دوباره امتحان نمی کند. با این حال، می‌توانید از مقدار جدید و ETag برای ایجاد یک درخواست شرطی جدید با اطلاعاتی که توسط پاسخ شکست بازگردانده شده است استفاده کنید.

درخواست‌های شرطی مبتنی بر REST استاندارد if-match HTTP را پیاده‌سازی می‌کنند. با این حال، آنها با استاندارد در موارد زیر متفاوت هستند:

  • شما فقط می توانید یک مقدار ETag برای هر درخواست if-match ارائه دهید، نه چند عدد.
  • در حالی که استاندارد پیشنهاد می‌کند که ETag‌ها با همه درخواست‌ها برگردانده شوند، پایگاه داده Realtime فقط ETag‌هایی را با درخواست‌هایی از جمله هدر X-Firebase-ETag ETag برمی‌گرداند. این هزینه های صورتحساب درخواست های استاندارد را کاهش می دهد.

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

ذخیره لیست داده ها

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

curl -X POST -d '{
  "author": "alanisawesome",
  "title": "The Turing Machine"
}' 'https://docs-examples.firebaseio.com/fireblog/posts.json'

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

{
  "posts": {
    "-JSOpn9ZC54A4P4RoqVa": {
      "author": "alanisawesome",
      "title": "The Turing Machine"
    }
  }
}

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

{"name":"-JSOpn9ZC54A4P4RoqVa"}

حذف داده ها

برای حذف داده‌ها از پایگاه داده، می‌توانیم یک درخواست DELETE با URL مسیری که می‌خواهیم داده‌ها را از آن حذف کنیم، ارسال کنیم. موارد زیر Alan را از مسیر users ما حذف می کند:

curl -X DELETE \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome.json'

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

پارامترهای URI

REST API پارامترهای URI زیر را هنگام نوشتن داده در پایگاه داده می پذیرد:

اعتبار

auth درخواست تأیید اجازه دسترسی به داده‌های محافظت شده توسط قوانین پایگاه داده بیدرنگ Firebase را می‌دهد و توسط همه انواع درخواست پشتیبانی می‌شود. این آرگومان می تواند مخفی برنامه Firebase ما باشد یا یک نشانه احراز هویت، که در بخش مجوز کاربر پوشش خواهیم داد. در مثال زیر، ما یک درخواست POST با یک پارامتر auth ارسال می‌کنیم، که در آن CREDENTIAL یا راز برنامه Firebase ما است یا یک نشانه احراز هویت:

curl -X POST -d '{"Authenticated POST request"}' \
  'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'

چاپ

پارامتر print به ما امکان می دهد قالب پاسخ خود را از پایگاه داده مشخص کنیم. افزودن print=pretty به درخواست ما، داده ها را در قالبی قابل خواندن برای انسان باز می گرداند. print=pretty توسط درخواست‌های GET ، PUT ، POST ، PATCH و DELETE پشتیبانی می‌شود.

برای سرکوب خروجی از سرور هنگام نوشتن داده ها، می توانیم print=silent را به درخواست خود اضافه کنیم. در صورت موفقیت آمیز بودن درخواست، پاسخ به دست آمده خالی خواهد بود و با کد وضعیت HTTP 204 No Content نشان داده می شود. print=silent توسط درخواست‌های GET ، PUT ، POST و PATCH پشتیبانی می‌شود.

نوشتن مقادیر سرور

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

curl -X PUT -d '{".sv": "timestamp"}' \
  'https://docs-examples.firebaseio.com/alanisawesome/createdAt.json'

"timestamp" تنها مقدار سرور پشتیبانی شده است و زمان از زمان یونیکس بر حسب میلی ثانیه است.

بهبود عملکرد نوشتاری

اگر مقادیر زیادی داده در پایگاه داده می نویسیم، می توانیم از پارامتر print=silent برای بهبود عملکرد نوشتن و کاهش استفاده از پهنای باند استفاده کنیم. در رفتار عادی نوشتن، سرور با داده‌های JSON که نوشته شده بود پاسخ می‌دهد. هنگامی که print=silent مشخص می شود، سرور بلافاصله پس از دریافت داده ها، اتصال را می بندد و استفاده از پهنای باند را کاهش می دهد.

در مواردی که درخواست‌های زیادی به پایگاه داده می‌کنیم، می‌توانیم با ارسال یک درخواست Keep-Alive در هدر HTTP، از اتصال HTTPS دوباره استفاده کنیم.

شرایط خطا

REST API کدهای خطا را تحت این شرایط برمی گرداند:

کدهای وضعیت HTTP
400 درخواست بد

یکی از شرایط خطای زیر:

  • تجزیه و تحلیل داده های PUT یا POST امکان پذیر نیست.
  • داده PUT یا POST وجود ندارد.
  • درخواست PUT می کند داده POST را که خیلی بزرگ هستند قرار دهد یا ارسال کند.
  • فراخوانی REST API شامل نام‌های فرزند نامعتبر به عنوان بخشی از مسیر است.
  • مسیر تماس REST API خیلی طولانی است.
  • درخواست حاوی یک مقدار سرور ناشناخته است.
  • نمایه پرس و جو در قوانین پایگاه داده بیدرنگ Firebase شما تعریف نشده است.
  • درخواست از یکی از پارامترهای پرس و جو که مشخص شده است پشتیبانی نمی کند.
  • این درخواست پارامترهای پرس و جو را با یک درخواست GET کم عمق ترکیب می کند.
401 غیر مجاز

یکی از شرایط خطای زیر:

404 یافت نشد پایگاه داده Firebase مشخص شده یافت نشد.
500 خطای داخلی سرور سرور یک خطا برگرداند. برای جزئیات بیشتر به پیام خطا مراجعه کنید.
سرویس 503 در دسترس نیست پایگاه داده بیدرنگ Firebase مشخص شده به طور موقت در دسترس نیست، به این معنی که درخواست انجام نشده است.

ایمن سازی داده ها

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

اکنون که ذخیره داده‌ها را پوشش داده‌ایم، می‌توانیم یاد بگیریم که چگونه داده‌های خود را از پایگاه داده Firebase از طریق REST API در بخش بعدی بازیابی کنیم.