ذخیره داده ها

نوشتن داده با 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"
    }
  }
}

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

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

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

• شما فقط می توانید یک مقدار ETag برای هر درخواست if-match ارائه دهید، نه چند عدد.
• در حالی که استاندارد پیشنهاد می کند که ETag ها با همه درخواست ها بازگردانده شوند، پایگاه داده Realtime فقط ETag هایی را با درخواست هایی از جمله هدر X-Firebase-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 Realtime Database Security Rules را می‌دهد و توسط همه انواع درخواست پشتیبانی می‌شود. آرگومان می تواند مخفی برنامه 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 کدهای خطا را تحت این شرایط برمی گرداند:

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

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