برنامه خود را به شبیه ساز Cloud Firestore متصل کنید

قبل از اتصال برنامه خود به شبیه‌ساز Cloud Firestore ، مطمئن شوید که گردش کار کلی Firebase Local Emulator Suite را درک کرده‌اید ، و Local Emulator Suite را نصب و پیکربندی کرده‌اید و دستورات CLI آن را بررسی کرده‌اید.

یک پروژه فایربیس انتخاب کنید

Firebase Local Emulator Suite محصولات مربوط به یک پروژه فایربیس را شبیه‌سازی می‌کند.

برای انتخاب پروژه مورد استفاده، قبل از شروع شبیه‌سازها، در CLI firebase use در دایرکتوری کاری خود اجرا کنید. یا می‌توانید پرچم --project را به هر دستور شبیه‌ساز ارسال کنید.

Local Emulator Suite از شبیه‌سازی پروژه‌های واقعی Firebase و پروژه‌های آزمایشی پشتیبانی می‌کند.

نوع پروژه ویژگی‌ها استفاده با شبیه‌سازها
واقعی

یک پروژه واقعی Firebase، پروژه‌ای است که شما ایجاد و پیکربندی کرده‌اید (به احتمال زیاد از طریق کنسول Firebase ).

پروژه‌های واقعی منابع زنده‌ای دارند، مانند نمونه‌های پایگاه داده، مخازن ذخیره‌سازی، توابع یا هر منبع دیگری که برای آن پروژه Firebase تنظیم کرده‌اید.

هنگام کار با پروژه‌های واقعی Firebase، می‌توانید شبیه‌سازها را برای هر یا همه محصولات پشتیبانی‌شده اجرا کنید.

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

نسخه آزمایشی

یک پروژه آزمایشی فایربیس هیچ پیکربندی واقعی فایربیس و هیچ منبع زنده‌ای ندارد. این پروژه‌ها معمولاً از طریق codelabs یا سایر آموزش‌ها قابل دسترسی هستند.

شناسه‌های پروژه برای پروژه‌های نمایشی دارای پیشوند demo- هستند.

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

توصیه می‌کنیم تا حد امکان از پروژه‌های نمایشی استفاده کنید. مزایا عبارتند از:

  • راه‌اندازی آسان‌تر، زیرا می‌توانید شبیه‌سازها را بدون ایجاد یک پروژه Firebase اجرا کنید
  • ایمنی قوی‌تر، زیرا اگر کد شما به‌طور تصادفی منابع شبیه‌سازی نشده (تولیدی) را فراخوانی کند، هیچ شانسی برای تغییر داده‌ها، استفاده و صدور صورتحساب وجود ندارد.
  • پشتیبانی آفلاین بهتر، زیرا نیازی به دسترسی به اینترنت برای دانلود پیکربندی SDK شما نیست.

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

در هنگام راه‌اندازی، شبیه‌ساز Cloud Firestore یک پایگاه داده پیش‌فرض و یک پایگاه داده نامگذاری شده برای هر پیکربندی firestore در فایل firebase.json شما ایجاد می‌کند.

پایگاه‌های داده نامگذاری‌شده همچنین به‌طور ضمنی در پاسخ به هرگونه فراخوانی SDK یا REST API به شبیه‌ساز که به یک پایگاه داده خاص ارجاع می‌دهد، ایجاد می‌شوند. چنین پایگاه‌های داده‌ای که به‌طور ضمنی ایجاد می‌شوند، با قوانین باز عمل می‌کنند.

برای کار تعاملی با پایگاه‌های داده پیش‌فرض و نامگذاری‌شده در Emulator Suite UI ، در نوار آدرس مرورگر خود، URL را به‌روزرسانی کنید تا پایگاه داده پیش‌فرض یا یک پایگاه داده نامگذاری‌شده را انتخاب کنید.

  • برای مثال، برای مرور داده‌ها در نمونه پیش‌فرض خود، URL را به localhost:4000/firestore/default/data به‌روزرسانی کنید.
  • برای مرور در نمونه‌ای به نام ecommerce ، به localhost:4000/firestore/ecommerce/data به‌روزرسانی کنید.

پلتفرم‌های اندروید، اپل و وب SDKها

پیکربندی درون‌برنامه‌ای یا کلاس‌های آزمایشی خود را برای تعامل با Cloud Firestore به شرح زیر تنظیم کنید. توجه داشته باشید که در نمونه‌های زیر، کد برنامه به پایگاه داده پیش‌فرض پروژه متصل می‌شود. برای مثال‌هایی که شامل پایگاه‌های داده اضافی Cloud Firestore فراتر از پایگاه داده پیش‌فرض هستند، به راهنمای مربوط به چندین پایگاه داده مراجعه کنید.

Kotlin 
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val firestore = Firebase.firestore
firestore.useEmulator("10.0.2.2", 8080)

firestore.firestoreSettings = firestoreSettings {
    isPersistenceEnabled = false
}
EmulatorSuite.kt
Java 
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFirestore firestore = FirebaseFirestore.getInstance();
firestore.useEmulator("10.0.2.2", 8080);

FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setPersistenceEnabled(false)
        .build();
firestore.setFirestoreSettings(settings);
EmulatorSuite.java
سویفت 
let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

Web 

import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";

// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, '127.0.0.1', 8080);
fs_emulator_connect.js

Web

// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
  db.useEmulator("127.0.0.1", 8080);
}
emulator-suite.js

برای آزمایش توابع ابری که توسط رویدادهای Firestore با استفاده از شبیه‌ساز فعال می‌شوند ، هیچ تنظیمات اضافی لازم نیست. وقتی شبیه‌سازهای Firestore و Cloud Functions هر دو در حال اجرا هستند، به طور خودکار با هم کار می‌کنند.

Admin SDK

Firebase Admin SDK به طور خودکار هنگام تنظیم متغیر محیطی FIRESTORE_EMULATOR_HOST به شبیه ساز Cloud Firestore متصل می شوند:

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

اگر کد شما درون شبیه‌ساز Cloud Functions اجرا می‌شود، شناسه پروژه و سایر پیکربندی‌های شما هنگام فراخوانی initializeApp به طور خودکار تنظیم می‌شوند.

اگر می‌خواهید کد Admin SDK شما به یک شبیه‌ساز مشترک که در محیط دیگری اجرا می‌شود متصل شود، باید همان شناسه پروژه‌ای را که با استفاده از Firebase CLI تنظیم کرده‌اید، مشخص کنید. می‌توانید یک شناسه پروژه را مستقیماً به initializeApp ارسال کنید یا متغیر محیطی GCLOUD_PROJECT را تنظیم کنید.

SDK مدیریت Node.js 
admin.initializeApp({ projectId: "your-project-id" });
متغیر محیطی 
export GCLOUD_PROJECT="your-project-id"

رابط برنامه‌نویسی کاربردی REST در کلود فایراستور

شبیه‌ساز Cloud Firestore یک نقطه پایانی REST برای تعامل با پایگاه داده شما فراهم می‌کند. همه فراخوانی‌های REST API باید به نقطه پایانی http://localhost:8080/v1 انجام شوند.

مسیر کامل برای فراخوانی REST از این الگو پیروی می‌کند:

http://localhost:8080/v1/projects/{project_id}/databases/{database_id}/documents/{document_path}

برای مثال، برای فهرست کردن تمام اسناد موجود در مجموعه users برای پروژه my-project-id ، می‌توانید از curl استفاده کنید: 

curl -X GET "http://localhost:8080/v1/projects/my-project-id/databases/(default)/documents/users"

پایگاه داده خود را بین آزمایش‌ها پاک کنید

Firestore هیچ روشی برای پاکسازی پایگاه داده در پلتفرم SDK ارائه نمی‌دهد، اما شبیه‌ساز Firestore یک نقطه پایانی REST را به طور خاص برای این منظور در اختیار شما قرار می‌دهد که می‌تواند از مرحله راه‌اندازی/قطع فریم‌ورک تست، از یک کلاس تست یا از پوسته (مثلاً با curl ) قبل از شروع تست فراخوانی شود. می‌توانید از این رویکرد به عنوان جایگزینی برای خاموش کردن ساده فرآیند شبیه‌ساز استفاده کنید.

به روشی مناسب، یک عملیات HTTP DELETE انجام دهید و شناسه پروژه Firebase خود، مثلاً firestore-emulator-example ، را به نقطه پایانی زیر ارائه دهید: 

"http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

طبیعتاً، کد شما باید منتظر تأیید REST باشد تا مشخص شود که عملیات flush تمام شده یا با شکست مواجه شده است.

شما می‌توانید این عملیات را از طریق shell انجام دهید: 

// Shell alternative…
$ curl -v -X DELETE "http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

با پیاده‌سازی چنین مرحله‌ای، می‌توانید تست‌های خود را ترتیب‌بندی کرده و توابع خود را با اطمینان از اینکه داده‌های قدیمی بین اجراها پاک می‌شوند و از یک پیکربندی تست پایه جدید استفاده می‌کنید، فعال کنید.

واردات و صادرات داده‌ها

پایگاه داده و Cloud Storage for Firebase به شما امکان می‌دهند داده‌ها را از یک نمونه شبیه‌ساز در حال اجرا صادر کنید. یک مجموعه داده پایه برای استفاده در تست‌های واحد یا گردش‌های کاری ادغام مداوم خود تعریف کنید، سپس آن را برای اشتراک‌گذاری بین اعضای تیم صادر کنید. 

firebase emulators:export ./dir

در تست‌ها، در هنگام راه‌اندازی شبیه‌ساز، داده‌های پایه را وارد کنید. 

firebase emulators:start --import=./dir

شما می‌توانید به شبیه‌ساز دستور دهید که داده‌ها را پس از خاموش شدن، با مشخص کردن یک مسیر صادرات یا به سادگی با استفاده از مسیری که به پرچم --import منتقل می‌شود، صادر کند. 

firebase emulators:start --import=./dir --export-on-exit

این گزینه‌های ایمپورت و اکسپورت داده‌ها با دستور firebase emulators:exec نیز کار می‌کنند. برای اطلاعات بیشتر، به مرجع دستور emulator مراجعه کنید.

تجسم فعالیت قوانین امنیتی

همانطور که روی حلقه‌های نمونه اولیه و تست کار می‌کنید، می‌توانید از ابزارهای تجسم و گزارش‌های ارائه شده توسط Local Emulator Suite استفاده کنید.

از مانیتور درخواست‌ها استفاده کنید

شبیه‌ساز Cloud Firestore به شما امکان می‌دهد درخواست‌های کلاینت را در Emulator Suite UI تجسم کنید، از جمله ردیابی ارزیابی برای Firebase Security Rules .

برای مشاهده جزئیات ارزیابی هر درخواست، تب Firestore > Requests را باز کنید.

مانیتور درخواست‌های شبیه‌ساز Firestore که ارزیابی‌های قوانین امنیتی را نشان می‌دهد

گزارش‌های ارزیابی قوانین را تجسم کنید

همزمان با اضافه کردن قوانین امنیتی به نمونه اولیه خود، می‌توانید آنها را با ابزارهای اشکال‌زدایی Local Emulator Suite اشکال‌زدایی کنید.

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

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

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage.html

این دستور، قوانین شما را به عبارات و زیرعبارات تقسیم می‌کند که می‌توانید با نگه داشتن ماوس روی آنها، اطلاعات بیشتری از جمله تعداد ارزیابی‌ها و مقادیر برگشتی را مشاهده کنید. برای نسخه خام JSON این داده‌ها، آدرس اینترنتی زیر را در کوئری خود وارد کنید: 

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage

در اینجا، نسخه HTML گزارش، ارزیابی‌هایی را که خطاهای تعریف نشده و مقدار تهی را نشان می‌دهند، برجسته می‌کند:

تفاوت شبیه‌ساز Cloud Firestore با نسخه اصلی

شبیه‌ساز Cloud Firestore تلاش می‌کند تا با وجود برخی محدودیت‌های قابل توجه، رفتار سرویس تولید را به طور دقیق تکرار کند.

پشتیبانی از چندین پایگاه داده برای Cloud Firestore

در حال حاضر، Emulator Suite UI از ایجاد، ویرایش، حذف، نظارت بر درخواست و تجسم امنیتی تعاملی برای یک پایگاه داده پیش‌فرض پشتیبانی می‌کند، اما پایگاه‌های داده نامگذاری شده اضافی را پشتیبانی نمی‌کند.

با این حال، خود شبیه‌ساز بر اساس پیکربندی موجود در فایل firebase.json شما و به طور ضمنی در پاسخ به فراخوانی‌های SDK یا REST API، یک پایگاه داده نامگذاری شده ایجاد می‌کند.

تراکنش‌ها

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

شاخص‌ها

این شبیه‌ساز، اندیس‌های ترکیبی را ردیابی نمی‌کند و در عوض هر کوئری معتبری را اجرا می‌کند. حتماً برنامه خود را در برابر یک نمونه واقعی Cloud Firestore آزمایش کنید تا مشخص شود به کدام اندیس‌ها نیاز دارید.

محدودیت‌ها

شبیه‌ساز تمام محدودیت‌های اعمال‌شده در محیط عملیاتی را اعمال نمی‌کند. برای مثال، شبیه‌ساز ممکن است تراکنش‌هایی را مجاز بداند که توسط سرویس عملیاتی به دلیل حجم زیاد رد می‌شوند. مطمئن شوید که با محدودیت‌های مستند آشنا هستید و برنامه خود را طوری طراحی می‌کنید که به طور پیشگیرانه از آنها اجتناب کند.

بعدش چی؟

  • برای مجموعه‌ای منتخب از ویدیوها و مثال‌های آموزشی دقیق، لیست پخش آموزش شبیه‌سازهای Firebase را دنبال کنید.
  • موارد استفاده پیشرفته مربوط به تست قوانین امنیتی و Firebase Test SDK: Test Security Rules (Firestore) را بررسی کنید.
  • از آنجایی که توابع فعال‌شده معمولاً با Cloud Firestore ادغام می‌شوند، برای کسب اطلاعات بیشتر در مورد Cloud Functions for Firebase به Run functions locally مراجعه کنید.