برنامه‌تان را به «شبیه‌ساز Cloud Firestore» متصل کنید

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

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

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

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

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

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

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

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

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

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

پخش نمایشی

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

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

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

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

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

برنامه‌تان را برای صحبت با شبیه‌سازها آماده کنید

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

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

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

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

شروع کردن «شبیه‌ساز» در ویرایشی خاص

شبیه‌ساز در نسخه مشخص‌شده در بخش firestore.edition فایل firebase.json شما شروع خواهد شد. همچنین گزینه‌ای برای مشخص کردن نسخه در بخش emulators.firestore.edition در firebase.json دارید. مقادیر معتبر برای نسخه عبارت‌اند از standard و enterprise. اگر edition را در هر دو پیکربندی مشخص کنید، emulators.firestore.edition اولویت دارد.

    {
      ...
      "firestore": {
        "rules": "firestore.rules",
        "indexes": "firestore.indexes.json",
        "edition": "enterprise"
      },
      "emulators": {
        "firestore": {
          "port": 8080,
          "edition": "enterprise" // Takes precedence over `firestore.edition`
        }
      },
      ...
    }

Android، پلاتفرم‌های Apple، و کیت‌های توسعه نرم‌افزار وب

پیکربندی درون‌برنامه‌ای یا کلاس‌های آزمایشی را برای تعامل با 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
}
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);
Swift
let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
Unity
FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
// Connects to the Firestore Emulator running on port 8080
db.Settings.Host = "127.0.0.1:8080";
db.Settings.SslEnabled = false;

Web

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

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

Web

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

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

Admin SDK ثانیه

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

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

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

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

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

Cloud Firestore REST API

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

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

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

طبیعتاً کد شما باید منتظر تأیید REST باشد که تخلیه تمام شده یا ناموفق بوده است.

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

// 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 نیز کار می‌کنند. برای اطلاعات بیشتر، به مرجع فرمان شبیه‌ساز مراجعه کنید.

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

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

استفاده از «پایشگر درخواست‌ها»

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

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

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

مشاهده گزارش‌های ارزیابی «قوانین»

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

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

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

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 ایجاد می‌کند.

تراکنش‌ها

شبیه‌ساز درحال‌حاضر همه رفتارهای تراکنش را که در تولید دیده می‌شود پیاده‌سازی نمی‌کند. When you're testing features that involve multiple concurrent writes to one document, the emulator may be slow to complete write requests. در برخی موارد، ممکن است تا ۳۰ ثانیه طول بکشد تا قفل‌ها باز شوند. درصورت نیاز، زمان‌های اتمام آزمایش را بر این اساس تنظیم کنید.

نمایه‌ها

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

محدودیت‌ها

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

بعد چه می‌شود؟