Uygulamanızı Cloud Firestore Emulator'a bağlayın

Uygulamanızı Cloud Firestore emülatörüne bağlamadan önce Firebase Local Emulator Suite iş akışını genel olarak anladığınızdan, Local Emulator Suite'yi yüklediğinizden ve yapılandırdığınızdan ve CLI komutlarını incelediğinizden emin olun.

Firebase projesi seçme

Firebase Local Emulator Suite, tek bir Firebase projesinin ürünlerini taklit eder.

Kullanılacak projeyi seçmek için emülatörleri başlatmadan önce CLI'de çalışma dizininizde firebase use komutunu çalıştırın. Alternatif olarak, her emülatör komutuna --project işaretini de iletebilirsiniz.

Local Emulator Suite, gerçek Firebase projelerinin ve demo projelerinin emülasyonunu destekler.

Proje türü Özellikler Emülatörlerle kullanma
Gerçek

Gerçek Firebase projesi, oluşturduğunuz ve yapılandırdığınız (muhtemelen Firebase konsolu üzerinden) projedir.

Gerçek projelerde veritabanı örnekleri, depolama alanı paketleri, işlevler veya söz konusu Firebase projesi için oluşturduğunuz diğer kaynaklar gibi canlı kaynaklar bulunur.

Gerçek Firebase projeleriyle çalışırken desteklenen ürünlerin herhangi biri veya tümü için emülatör çalıştırabilirsiniz.

Emülasyon oluşturmadığınız ürünlerde uygulamalarınız ve kodunuz canlı kaynakla (veritabanı örneği, depolama alanı paketi, işlev vb.) etkileşim kurar.

Demo

Demo Firebase projelerinde gerçek Firebase yapılandırması ve canlı kaynak bulunmaz. Bu projelere genellikle codelab'ler veya diğer eğitici içerikler üzerinden erişilir.

Demo projelerin proje kimliklerinde demo- ön ek bulunur.

Demo Firebase projeleriyle çalışırken uygulamalarınız ve kodunuz yalnızca emülatörlerle etkileşim kurar. Uygulamanız, emülatörünün çalışmadığı bir kaynağa etkileşime geçmeye çalışırsa bu kod başarısız olur.

Mümkün olduğunda demo projeleri kullanmanızı öneririz. Sunulan avantajlar arasında şunlar sayılabilir:

  • Firebase projesi oluşturmadan emülatörleri çalıştırabileceğiniz için daha kolay kurulum
  • Kodunuz yanlışlıkla taklit edilmeyen (üretim) kaynakları çağırırsa veri değişikliği, kullanım ve faturalandırma olasılığı olmadığından daha güçlü güvenlik
  • SDK yapılandırmanızı indirmek için internete erişmeniz gerekmediğinden daha iyi çevrimdışı destek.

Uygulamanızı, emülatörlerle konuşacak şekilde donatma

Cloud Firestore emülatörü, başlangıçta firebase.json dosyanızdaki her firestore yapılandırması için bir varsayılan veritabanı ve adlandırılmış veritabanı oluşturur.

Adlandırılmış veritabanları, belirli bir veritabanına atıfta bulunan emülatöre yönelik tüm SDK veya REST API çağrılarına yanıt olarak da dolaylı olarak oluşturulur. Bu tür dolaylı olarak oluşturulan veritabanları açık kurallar ile çalışır.

Emulator Suite UI'te varsayılan ve adlandırılmış veritabanlarınızla etkileşimli olarak çalışmak için tarayıcınızın adres çubuğunda URL'yi güncelleyerek varsayılan veya adlandırılmış bir veritabanı seçin.

  • Örneğin, varsayılan örneğinizdeki verilere göz atmak için URL'yi şu şekilde güncelleyin: localhost:4000/firestore/default/data
  • ecommerce adlı bir örneğe göz atmak için localhost:4000/firestore/ecommerce/data sürümüne güncelleyin.

Android, Apple platformları ve web SDK'ları

Uygulama içi yapılandırmanızı veya test sınıflarınızı Cloud Firestore ile etkileşime geçecek şekilde aşağıdaki gibi ayarlayın. Aşağıdaki örneklerde uygulama kodunun varsayılan proje veritabanına bağlandığını unutmayın. Varsayılan veritabanının dışındaki ek Cloud Firestore veritabanlarını içeren örnekler için birden fazla veritabanı kılavuzunu inceleyin.

Kotlin+KTX
// 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
Swift
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

Emülatör kullanarak Firestore etkinlikleri tarafından tetiklenen Cloud Functions'ı test etmek için ek kurulum gerekmez. Firestore ve Cloud Functions emülatörleri birlikte çalışırken otomatik olarak birlikte çalışır.

Admin SDK

FIRESTORE_EMULATOR_HOST ortam değişkeni ayarlandığında Firebase Admin SDK'ler otomatik olarak Cloud Firestore emülatörüne bağlanır:

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

Kodunuz Cloud Functions emülatöründe çalışıyorsa initializeApp çağrılırken proje kimliğiniz ve diğer yapılandırma otomatik olarak ayarlanır.

Admin SDK kodunuzun başka bir ortamda çalışan paylaşılan bir emülatöre bağlanmasını istiyorsanız Firebase CLI'yi kullanarak ayarladığınız proje kimliğini belirtmeniz gerekir. Proje kimliğini doğrudan initializeApp işlevine iletebilir veya GCLOUD_PROJECT ortam değişkenini ayarlayabilirsiniz.

Node.js Yönetici SDK'sı
admin.initializeApp({ projectId: "your-project-id" });
Ortam Değişkeni
export GCLOUD_PROJECT="your-project-id"

Testler arasında veritabanınızı temizleme

Üretim Firestore, veritabanı temizleme için platform SDK yöntemi sağlamaz ancak Firestore emülatöründe, test çerçevesi kurulum/yıkım adımında, test sınıfında veya test başlatılmadan önce kabuktan (ör. curl ile) çağrılabilecek, bu amaç için özel olarak tasarlanmış bir REST uç noktası bulunur. Bu yaklaşımı, emülatör sürecini kapatmanın alternatifi olarak kullanabilirsiniz.

Uygun bir yöntemde, aşağıdaki uç noktaya Firebase proje kimliğinizi (ör. firestore-emulator-example) sağlayarak bir HTTP DELETE işlemi gerçekleştirin:

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

Doğal olarak, kodunuz temizlemenin tamamlandığına veya başarısız olduğuna dair REST onayı beklemelidir.

Bu işlemi kabuktan gerçekleştirebilirsiniz:

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

Bu tür bir adım uyguladıktan sonra, testlerinizi sıralayabilir ve işlevlerinizi tetikleyebilirsiniz. Bu durumda, eski verilerin çalıştırmalar arasında temizleneceğinden ve yeni bir temel test yapılandırması kullandığınızdan emin olabilirsiniz.

Verileri içe ve dışa aktarma

Veritabanı ve Cloud Storage for Firebase emülatörleri, çalışan bir emülatör örneğinden veri dışa aktarmanıza olanak tanır. Birim testlerinizde veya sürekli entegrasyon iş akışlarınızda kullanılacak bir referans veri kümesi tanımlayın ve ardından ekip arasında paylaşılmak üzere dışa aktarın.

firebase emulators:export ./dir

Testlerde, emülatör başlatılırken temel verileri içe aktarın.

firebase emulators:start --import=./dir

Bir dışa aktarma yolu belirterek veya --import işaretçisine iletilen yolu kullanarak, kapatma sırasında verileri dışa aktarması için emülatöre talimat verebilirsiniz.

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

Bu veri içe aktarma ve dışa aktarma seçenekleri firebase emulators:exec komutuyla da çalışır. Daha fazla bilgi için emülatör komut referansı bölümüne bakın.

Güvenlik kuralları etkinliğini görselleştirme

Prototip ve test döngülerinde çalışırken Local Emulator Suite tarafından sağlanan görselleştirme araçlarını ve raporları kullanabilirsiniz.

İstek İzleyici'yi kullanma

Cloud Firestore emülatörü, Firebase Security Rules için değerlendirme izleme dahil olmak üzere Emulator Suite UI'teki istemci isteklerini görselleştirmenize olanak tanır.

Her istek için ayrıntılı değerlendirme sırasını görüntülemek üzere Firestore > İstekler sekmesini açın.

Güvenlik Kuralı değerlendirmelerini gösteren Firestore Emulator İstekler İzleyicisi

Kural değerlendirmesi raporlarını görselleştirme

Güvenlik kurallarını prototipinize eklerken Local Emulator Suite hata ayıklama araçlarıyla hata ayıklama yapabilirsiniz.

Bir dizi test çalıştırdıktan sonra, güvenlik kurallarınızın her birinin nasıl değerlendirildiğini gösteren test kapsamı raporlarına erişebilirsiniz.

Raporları almak için, emülatör çalışırken emülatörde açık bir uç noktayı sorgulayın. Tarayıcı dostu bir sürüm için aşağıdaki URL'yi kullanın:

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

Bu işlem, kurallarınızı ifade ve alt ifadelere ayırır. Fareyle üzerine geldiğinizde değerlendirmelerin sayısı ve döndürülen değerler gibi daha fazla bilgi edinebilirsiniz. Bu verilerin ham JSON sürümü için sorgunuza aşağıdaki URL'yi ekleyin:

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

Raporun HTML sürümünde, tanımlanmamış ve boş değer hataları veren değerlendirmeler vurgulanmıştır:

Cloud Firestore emülatörünün üretimden farkı

Cloud Firestore Emulator, bazı önemli sınırlamalarla üretim hizmetinin davranışını doğru bir şekilde kopyalamaya çalışır.

Cloud Firestore için birden fazla veritabanı desteği

Emulator Suite UI şu anda varsayılan bir veritabanı için etkileşimli oluşturma, düzenleme, silme, istek izleme ve güvenlik görselleştirmeyi destekler ancak ek adlandırılmış veritabanlarını desteklemez.

Ancak emülatör, firebase.json dosyanızdaki yapılandırmaya göre ve dolaylı olarak SDK veya REST API çağrılarına yanıt olarak adlandırılmış bir veritabanı oluşturur.

İşlemler

Emülatör şu anda üretimde görülen tüm işlem davranışlarını uygulamamaktadır. Tek bir belgeye birden fazla eşzamanlı yazma işlemi içeren özellikleri test ederken, emülatör yazma isteklerini tamamlamakta yavaş kalabilir. Bazı durumlarda kilitlerin açılması 30 saniye sürebilir. Gerekirse test zaman aşımları için uygun düzenlemeleri yapabilirsiniz.

Dizinler

Emülatör, bileşik dizinleri izlemez ve bunun yerine geçerli tüm sorguları yürütür. Hangi dizinlere ihtiyacınız olduğunu belirlemek için uygulamanızı gerçek bir Cloud Firestore örnekle test ettiğinizden emin olun.

Sınırlar

Emülatör, üretimde uygulanan tüm sınırları uygulamaz. Örneğin, emülatör, üretim hizmeti tarafından çok büyük olduğu için reddedilecek işlemlere izin verebilir. Belirtilen sınırlar hakkında bilgi sahibi olduğunuzdan ve uygulamanızı bu sınırlara takılmamak için proaktif bir şekilde tasarladığınızdan emin olun.

Sonrasında ne olacak?