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

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

Firebase projesi seçme

Firebase Local Emulator Suite, tek bir Firebase projesi için ürünleri emüle eder.

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

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

Proje türü Özellikler Emülatörlerle kullanma
Real

Gerçek bir Firebase projesi, oluşturduğunuz ve yapılandırdığınız (büyük olasılıkla Firebase konsolu üzerinden) bir projedir.

Gerçek projelerde veritabanı örnekleri, depolama paketleri, işlevler veya söz konusu Firebase projesi için ayarladığınız 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üle etmediğiniz ürünler için uygulamalarınız ve kodunuz canlı kaynakla (veritabanı örneği, depolama alanı paketi, işlev vb.) etkileşim kurar.

Demo

Demo Firebase projesinde gerçek Firebase yapılandırması ve canlı kaynaklar yoktur. Bu projelere genellikle codelab'ler veya diğer eğitimler üzerinden erişilir.

Demo projelerinin proje kimliklerinde demo- ön eki 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 çalışmadığı bir kaynakla etkileşim kurmaya ç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ırabildiğiniz için daha kolay kurulum
  • Kodunuz yanlışlıkla emüle edilmemiş (ü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 sunulur.

Uygulamanızı emülatörlerle iletişim kuracak şekilde yapılandırma

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

Adlandırılmış veritabanları, emülatöre yapılan ve belirli bir veritabanına referans veren SDK veya REST API çağrılarına yanıt olarak da dolaylı şekilde oluşturulur. Bu şekilde dolaylı olarak oluşturulan veritabanları açık kurallarla çalışır.

Emulator Suite UI içinde 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ı örnekte gezinmek için localhost:4000/firestore/ecommerce/data sürümüne güncelleyin.

Emülatörü belirli bir sürümde başlatma

Emülatör, firebase.json dosyanızın firestore.edition bölümünde belirtilen sürümde başlatılır. Ayrıca firebase.json dosyanızın emulators.firestore.edition bölümünde bir sürüm belirtebilirsiniz. Sürüm için geçerli değerler standard ve enterprise şeklindedir. Her iki yapılandırmada da edition belirtirseniz emulators.firestore.edition öncelikli olur.

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

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şim kuracak ş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ı dışında ek veritabanları içeren örnekler için birden fazla veritabanı kılavuzuna bakın.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);
}

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

Admin SDK

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

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

Kodunuz Cloud Functions emülatöründe çalışıyorsa initializeApp çağrıldığında proje kimliğiniz ve diğer yapılandırmalar 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 kullanarak ayarladığınız proje kimliğini belirtmeniz gerekir. Proje kimliğini doğrudan initializeApp aracına iletebilir veya GCLOUD_PROJECT ortam değişkenini ayarlayabilirsiniz.

Node.js Admin SDK
admin.initializeApp({ projectId: "your-project-id" });
Ortam Değişkeni
export GCLOUD_PROJECT="your-project-id"

Cloud Firestore REST API

Cloud Firestore emülatörü, veritabanınızla etkileşim kurmak için bir REST uç noktası sağlar. Tüm REST API çağrıları http://localhost:8080/v1 uç noktasına yapılmalıdır.

REST çağrısının tam yolu şu kalıbı izler:

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

Örneğin, my-project-id projesinin users koleksiyonundaki tüm dokümanları listelemek için curl komutunu kullanabilirsiniz:

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

Testler arasında veritabanınızı temizleme

Üretim Firestore, veritabanını temizlemek için platform SDK'sı yöntemi sağlamaz ancak Firestore emülatörü, özellikle bu amaç için bir REST uç noktası sağlar.Bu uç nokta, test çerçevesi kurulum/kaldırma adımından, test sınıfından veya test başlatılmadan önce kabuktan (ör. curl ile) çağrılabilir. Bu yaklaşımı, emülatör işlemini kapatmaya alternatif olarak kullanabilirsiniz.

Uygun bir yöntemle, Firebase projectID'nizi (ör. firestore-emulator-example) aşağıdaki uç noktaya göndererek bir HTTP DELETE işlemi gerçekleştirin:

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

Doğal olarak kodunuz, temizleme işleminin tamamlandığına veya başarısız olduğuna dair REST onayını 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"

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

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 aktarmanıza olanak tanır. Birim testlerinizde veya sürekli entegrasyon iş akışlarınızda kullanmak üzere bir temel veri kümesi tanımlayın ve ardından bunu ekiple paylaşmak üzere dışa aktarın.

firebase emulators:export ./dir

Testlerde, emülatör başlatıldığında referans verileri içe aktarın.

firebase emulators:start --import=./dir

Emülatöre, kapatma sırasında verileri dışa aktarmasını söyleyebilirsiniz. Bunun için bir dışa aktarma yolu belirtebilir veya --import işaretine iletilen yolu kullanabilirsiniz.

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

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

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

Prototip ve test döngüleri üzerinde ç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 içindeki istemci isteklerini görselleştirmenize olanak tanır.

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

Güvenlik Kuralları değerlendirmelerini gösteren Firestore Emulator Requests Monitor

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

Prototipinize güvenlik kuralları ekledikçe Local Emulator Suite hata ayıklama araçlarıyla bu kurallarda hata ayıklayabilirsiniz.

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 açık bir uç noktayı sorgulayın. Tarayıcıda açılabilen bir sürüm için aşağıdaki URL'yi kullanın:

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

Bu, kurallarınızı ifadelere ve alt ifadelere ayırır. Değerlendirme sayısı ve döndürülen değerler gibi daha fazla bilgi için fareyle bunların üzerine gelebilirsiniz. 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

Burada, raporun HTML sürümü, tanımlanmamış ve boş değer hataları veren değerlendirmeleri vurgular:

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

Cloud Firestore emülatörü, üretim hizmetinin davranışını aslına uygun şekilde kopyalamaya çalışır ancak bazı önemli sınırlamaları vardır.

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

Emulator Suite UI şu anda varsayılan 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 SDK ya da REST API çağrılarına yanıt olarak dolaylı bir şekilde adlandırılmış bir veritabanı oluşturur.

İşlemler

Emülatör şu anda üretimde görülen tüm işlem davranışlarını uygulamaz. Bir dokümana aynı anda birden fazla yazma işlemi içeren özellikleri test ederken emülatör, yazma isteklerini yavaş tamamlayabilir. Bazı durumlarda kilitlerin açılması 30 saniyeyi bulabilir. Gerekirse test zaman aşımlarını buna göre ayarlayabilirsiniz.

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 olacağını belirlemek için uygulamanızı gerçek bir Cloud Firestore örneğiyle 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. Belgelenen sınırlamalar hakkında bilgi sahibi olduğunuzdan ve uygulamanızı bu sınırlamalardan proaktif olarak kaçınacak şekilde tasarladığınızdan emin olun.

Sonrasında ne olacak?