Firebase Data Connect'i kullanmaya başlama

Bu hızlı başlangıç kılavuzunda şunları öğreneceksiniz:

• Firebase Data Connect'i Firebase projenize ekleyin.
• Bir üretim örneğiyle çalışmak için Visual Studio Code uzantısı içeren bir geliştirme ortamı oluşturun.
• Ardından aşağıdakileri nasıl yapacağınızı göstereceğiz:
  • Bir e-posta uygulaması örneği kullanarak şema oluşturun.
  • Şemanız için sorguları ve değişiklikleri tanımlayın.
  • İstemcilerinizden bu sorguları ve değişiklikleri çağırmak için otomatik olarak oluşturulan SDK'ları kullanın.
  • Son prototipinizi üretime dağıtın.

Ön koşullar

Bu hızlı başlangıç kılavuzunu kullanmak için aşağıdakilere ihtiyacınız olacaktır.

• Linux, macOS veya Windows
• Visual Studio Code

Projenize Data Connect'i ekleyin ve veri kaynağı oluşturun

1. Henüz yapmadıysanız bir Firebase projesi oluşturun.
   1. Firebase konsolunda Proje ekle'yi tıklayın ve ardından ekrandaki talimatları uygulayın.

2. Projenizi Blaze planına yükseltin. Bu sayede PostgreSQL için Cloud SQL örneği oluşturabilirsiniz.

3. Firebase konsolunun Data Connect bölümüne gidin ve ürün kurulumu iş akışını takip edin.

4. PostgreSQL için Cloud SQL veritabanınız için bir konum seçin.

5. Daha sonra onaylamak için proje, hizmet ve veritabanı adlarını ve kimliklerini not edin.

6. Kalan kurulum akışını uygulayıp Bitti'yi tıklayın.

Geliştirme ortamı seçme ve ayarlama

Visual Studio Code'da bir uygulamanın prototipini oluşturarak Data Connect ile başlayabilirsiniz.

İsteğe bağlı olarak Data Connect emülatörü ile yerel geliştirme için yerel bir PostgreSQL veritabanı yükleyebilirsiniz. Bu kurulum, bu hızlı başlangıç kılavuzunun sonunda ele alınmıştır.

Data Connect, prototip oluşturma için iki geliştirme deneyimini destekler:

• Web veya Kotlin Android geliştiricisiyseniz şema ve işlemlerin prototiplerini yerel olarak oluşturup PostgreSQL için Cloud SQL örneğinize bağlanabilir veya (isteğe bağlı) PostgreSQL'i yerel olarak çalıştırabilirsiniz.

• Web geliştiricisiyseniz PostgreSQL ile önceden yapılandırılmış IDX şablonu, Data Connect emülatörü olan VS Code uzantısı ve sizin için ayarlanmış hızlı başlangıç kodu olan bir IDX çalışma alanında prototip oluşturmak için IDX'i kullanabilirsiniz.

Yerel projenizi oluşturun

Normal talimatları uygulayarak KSA'yı yükleyin.

Ardından Firebase Data Connect denemesini etkinleştirin.

firebase experiments:enable dataconnect

Yerel projenizi kurmak için proje dizininizi başlatacağız ve kod oluşturmak için gereken birkaç yapılandırma dosyasını güncelleyeceğiz.

Proje dizininizi oluşturun

Proje dizininizi başlatın.

Her iki akış da yerel çalışma dizininizde firebase.json ile .firebaserc dosyaları ve önemli dataconnect.yaml ile connector.yaml dosyalarını içeren dataconnect alt dizin oluşturur.

SDK kodunun nerede oluşturulacağını yapılandırın

Data Connect, siz şemanızı düzenlerken otomatik olarak SDK kodu oluşturur.

SDK'ların nereden oluşturulduğunu belirtmek için dataconnect/connector/connector.yaml sayfasında ilk bağlayıcınıza ait dosyayı güncelleyin.

connectorId: "my-connector"
authMode: "PUBLIC"
generate:
  javascriptSdk:
    outputDir: "../../js-email-generated"
    package: "@email-manager/emails"
    packageJsonDir: "../../"
  kotlinSdk:
    outputDir: "../kotlin-email-generated"
    package: com.myemailapplication

Data Connect Araç Seti'ni tanıyın

Data Connect Araç Seti, doğrudan Visual Studio Code'dan şema geliştirmeye, sorgu ve mutasyon yönetimine yardımcı olan Firebase VS Code uzantısının bir bileşenidir.

Araç Seti özelliklerine göz atmak için:

1. Henüz açmadıysanız VS Code'da Firebase proje dizininizi açın.
2. VS Code'da, soldaki panelde Firebase simgesini tıklayarak Firebase VS Code uzantısı arayüzünü açın.

Geliştirme çalışmanız boyunca Araç Seti'nin hem yerel ortamınızla hem de üretim kaynaklarınızla etkileşim kurmanıza olanak tanıdığını unutmayın. Bu hızlı başlangıç kılavuzunda, üretim ortamınızla etkileşim kuracaksınız.

Uzantı kullanıcı arayüzü çeşitli yararlı özellikler sağlar:

VS Code Birincil Kenar Çubuğunda:

Birincil Kenar Çubuğu

• Google'da oturum açmanıza ve Firebase projesi seçmenize olanak tanıyan Config (Yapılandırma) paneli
• Yerleşik emülatörü kontrol etmenizi ve kaynakları üretim için dağıtmanızı sağlayan Firebase Data Connect paneli.
• Şemanıza göre otomatik olarak oluşturulan örtülü sorguları ve mutasyonları listeleyen bir FDC Gezgini paneli

VS Code alt panelinde:

Alt Panel

• İsteklerde veri iletmenize, kimlik doğrulamayı taklit etmenize ve sonuçları görüntülemenize olanak tanıyan araçların bulunduğu bir Data Connect Yürütme sekmesi.

Bir uygulama geliştirmeye başlamadan önce, uzantının bazı özelliklerine göz atın.

Data Connect şeması ve sorgusu oluşturma

Kurulumunuz tamamlandı. Artık Data Connect ile uygulama geliştirmeye başlayabiliriz.

Kullanıcıları ve e-postaları modellemek için GraphQL'i kullanmaya başlayın. Kaynakları şuralarda güncelleyeceksiniz:

• /dataconnect/schema/schema.gql
• /dataconnect/connector/queries.gql

Şema geliştirmeye başlayın

Firebase proje dizininizde dataconnect klasörünü not edin. Bu aşamada, GraphQL kullanarak Cloud SQL veritabanı için veri modelinizi tanımlarsınız.

/dataconnect/schema/schema.gql dosyasında, kullanıcıları ve e-postaları içeren bir şema tanımlamaya başlayın.

Kullanıcı

Data Connect'te GraphQL alanları sütunlarla eşlenir. Kullanıcıların uid, name ve e-posta adresi address olur. Data Connect birkaç temel veri türünü tanır: String ve Date.

Aşağıdaki snippet'i kopyalayın veya dosyadaki ilgili satırlardaki açıklamaları kaldırın.

# File `/dataconnect/schema/schema.gql`

type User @table(key: "uid") {
   uid: String!
   name: String!
   address: String!
}

Herhangi bir anahtar sağlanmamışsa Firebase Data Connect, varsayılan olarak bir UUID id anahtarı ekler. Ancak bu durumda, birincil anahtarın uid olmasını istiyorsunuz. Bunu @table(key: "uid") yönergesi ile yapabilirsiniz.

E-posta

Artık kullanıcılarınız olduğuna göre e-postalar için model oluşturabilirsiniz. Burada e-posta verileri için tipik alanları (veya sütunları) ekleyebilirsiniz. Bu sefer birincil anahtar ekleme işlemi Data Connect'e güvenebileceğinizden belirtilmiyor.

# File `/dataconnect/schema/schema.gql`

type Email @table {
   subject: String!
   date: Date!
   text: String!
   from: User!
}

from alanının bir User türüyle eşlendiğine dikkat edin. Data Connect, bunun Email ile User arasında bir ilişki olduğunu anlar ve bu ilişkiyi sizin adınıza yönetir.

Şemanızı üretime dağıtın

Üretim veritabanınızla çalışmak için Firebase VS Code uzantısını kullandığınız için devam etmeden önce şemanızı dağıtmanız gerekir.

1. Dağıtmak için Firebase VS Code uzantısını kullanabilirsiniz.
   • Uzantı kullanıcı arayüzünde, Firebase Data Connect panelinin altında Dağıt'ı tıklayın.

2. Alternatif olarak Firebase CLI'yı kullanabilirsiniz.

   firebase deploy
   

3. Uzantıda veya KSA akışında, şema değişikliklerini incelemeniz ve yıkıcı olabilecek değişiklikleri onaylamanız gerekebilir. Şunları yapmanız istenir:

   • firebase dataconnect:sql:diff kullanarak şema değişikliklerini inceleyin
   • İstediğiniz değişikliklerden memnun kalırsanız, firebase dataconnect:sql:migrate tarafından başlatılan akışı kullanarak bu değişiklikleri uygulayın.

Oluşturulan şema uzantılarına bakın

Siz e-posta şemanızı düzenlerken Data Connect, şema uzantıları, sorgular, değişimler, filtreler ve tablo ilişkileri otomatik olarak oluşturur. Oluşturulan bu kodu iki şekilde görüntüleyebilirsiniz.

• Oluşturulan örtülü sorguların ve mutasyonların listesini, Firebase uzantısı kullanıcı arayüzündeki FDC Explorer panelinin altında görebilirsiniz.
• Yerel olarak oluşturulan tüm kodları .dataconnect/schema dizinindeki kaynaklarda görüntüleyebilirsiniz.

Tablonuza veri eklemek için değişiklik yürütme

/dataconnect/schema/schema.gql içindeki GraphQL türlerinin üzerinde CodeLens düğmeleri görebilirsiniz.

Gelişim zamanı sorguları ve mutasyonları

Bu CodeLens düğmeleriyle ilişkilendirilen işlemler, bu durumda tabloya veri eklemek amacıyla hızlı ve faydalı işlemlerdir. Data Connect, veritabanı üzerinde nasıl ve kimin çalışabileceğini açıklamak için GraphQL mutasyonlarını kullanır. Bu düğmenin kullanılması, hızlı veri başlangıç noktası için geliştirme zamanı işlemi oluşturur.

Şemanızı üretime dağıttıktan sonra, bu işlemleri arka ucunuzda gerçekleştirmek için Çalıştır (Üretim) CodeLens düğmelerini kullanabilirsiniz.

E-postaları listelemek için bir sorgu yazın

Şimdi işin eğlenceli kısmına, yani sorgulara geldik. Geliştirici olarak, GraphQL sorguları yerine SQL sorguları yazmaya alışkınsınızdır. Dolayısıyla, başlangıçta biraz farklı görünebilir. Bununla birlikte, GraphQL, ham SQL'den çok daha basit ve tür açısından güvenlidir. VS Code uzantımız da geliştirme deneyimini kolaylaştırıyor.

/dataconnect/connector/queries.gql dosyasını düzenlemeye başlayın. Tüm e-postaları almak istiyorsanız şöyle bir sorgu kullanın.

# File `/dataconnect/connector/queries.gql`

query listEmails @auth(level: PUBLIC) {
  emails {
    id, subject, text, date
    from {
      name
    }
  }
}

Burada gerçekten heyecan verici bir özellik, veritabanının ilişkilerini bir grafik gibi ele alabiliyor. E-posta, bir Kullanıcıya başvuruda bulunan from alanı içerdiğinden, bu alanı içine alabilir ve kullanıcı hakkındaki bilgileri geri alabilirsiniz.

@auth yönergesi

Bu örnekte @auth yönergesi tam potansiyelinde kullanılmasa da kavram gerçekten güçlüdür. Veritabanına yönelik işlemler için yetkilendirme politikasını bu şekilde belirlersiniz.

Bu sorgu oldukça basittir. Data Connect'in gerçek heyecan verici özellikleri, çoka-çok ilişkiyle daha karmaşık birleştirmeler yaptığınızda kendini göstermeye başlar. Araçları ve belgeleri keşfettikçe bununla ilgili daha fazla bilgi edineceksiniz.

Sorgunuzu test etme

Bu sorguyu oluşturduktan sonra, sorguyu istemci koduna entegre etmeden önce çalışıp çalışmadığını kontrol edin. Data Connect geliştirici deneyiminin bir parçası da Data Connect Execution paneli ile sorgu sonuçlarını hızlı bir şekilde yineleme ve test etme özelliğidir.

Bu sorgu için gereken bağımsız değişkenleri sağlayabilir ve ardından sorgu adının üzerindeki CodeLens düğmesini tıklayabilirsiniz. Bunu yaptığınızda sorguyu yürütür ve sonuçları görüntüler, böylece sorgunun beklendiği gibi çalıştığını görebilirsiniz.

Bir istemci uygulamasından istemci SDK kodu ve sorgu verileri oluşturma

Geliştirme döngüsünü kapatmak için bu sorguyu istemci koduna entegre edin.

Sorguyu çağırmayı ve Data Connect hizmetinden yanıtları işlemeyi gösterecek bir istemci yazabilirsiniz.

1. Otomatik olarak oluşturulan kaynakları daha önce connector.yaml dosyanızda belirttiğiniz konumda bulun.

2. Firebase'i projenize ekleyin, uygulamanızı kaydedin ve ilgili Firebase temel SDK'sını yükleyin:

   • JavaScript için bu talimatları uygulayın.
   • Kotlin için şu talimatları uygulayın.

3. IDX kullanmıyorsanız komut satırından çağrılabilen bir istemci oluşturabilirsiniz.

const { initializeApp } = require("firebase/app");
const {
  connectDataConnectEmulator,
  getDataConnect,
} = require("firebase/data-connect");
const { listEmails, connectorConfig } = require("@email-manager/emails");

// TODO: Replace the following with your app's Firebase project configuration
const firebaseConfig = {
  //...
};

const app = initializeApp(firebaseConfig);
const dc = getDataConnect(app, connectorConfig);

// Remove the following line to connect directly to production
connectDataConnectEmulator(dc, "localhost", 9399);

listEmails().then(res => {
  console.log(res.data.emails);
  process.exit(0);
});
    

    node clientTest.js
    

class MainActivity : ComponentActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    lifecycleScope.launch {
      val connector = MyConnector.instance
      connector.dataConnect.useEmulator() // Remove to connect to production
      try {
        println(connector.listEmails.execute().data.emails)
      } catch (e: Throwable) {
        println("ERROR: $e")
      }
    }
  }
}
    

Tamamladığınız prototipinizi üretime dağıtın

Bir geliştirme iterasyonu üzerinden çalıştınız. Artık şemanızı, verilerinizi, sorgularınızı ve mutasyonlarınızı Firebase uzantısı kullanıcı arayüzü veya Firebase CLI ile sunucuya şemanızda yaptığınız gibi dağıtabilirsiniz.

Data Connect hizmetiniz dağıtıldıktan sonra istemcilerden gelen işlemleri işlemeye hazır hale gelir. PostgreSQL İçin Cloud SQL örneği, dağıtılan son oluşturulan şema ve verilerle güncellenir.

(İsteğe bağlı) PostgreSQL'i yerel olarak yükleme

PostgreSQL'i yerel olarak yüklemek ve emülatörle entegre etmek, tamamen yerel bir geliştirme ortamında prototip oluşturmanıza olanak tanır.

Yeni bir PostgreSQL örneği yükleyebilir veya mevcut bir örneği kullanabilirsiniz.

PostgreSQL'i yükle

Platformunuza ilişkin talimatları uygulayarak PostgreSQL sürüm 15.x'i yükleyin.

• macOS için geçerlidir. Postgres.app'i indirip yükleyin.
• Windows: PostgreSQL indirme sayfasındaki EDB yükleyiciyi kullanın.
• Docker: Hem PostgreSQL 15.x hem de vektör desteğiyle birlikte gelen pgvector/pgvector:15 görüntüsünü çekip çalıştırın.
• Linux: Önceki görüntüyle Docker'ı kullanmanızı öneririz ancak popüler dağıtımlar için alternatif talimatları da uygulayabilirsiniz.

Yükleme sırasında ana makine adı, bağlantı noktası, kullanıcı adı, şifre ve ilgili parametrelerin çıkışını not edin.

PostgreSQL örneğinize bağlanmak için emülatörün şunlara ihtiyacı vardır:

• Bu kurulum yapılandırma parametreleri
• dataconnect.yaml kaynağınızdaki veritabanı adı ve yerel örneğinizde başlatılan ve buna karşılık gelen adlı veritabanı.

.firebaserc öğenizi bağlantı dizesiyle güncelleme

.firebaserc dosyanızda aşağıdaki anahtara eklenecek bir bağlantı dizesi için yerel PostgreSQL kullanıcı adınız ve şifreniz de dahil olmak üzere yerel PostgreSQL yapılandırma ayrıntılarınızı kullanın.

{
  "projects": {},
  ...,
  ...,
  "dataconnectEmulatorConfig": {
    "postgres": {
      "localConnectionString": "postgresql://postgresusername:postgrespassword@localhost:5432?sslmode=disable"
    }}
}

Yerel PostgreSQL örneğinize bağlanın

Bu yapılandırma tamamlandıktan sonra yerel veritabanınıza bağlanmak için:

1. VS Code'da, soldaki panelde Firebase simgesini tıklayarak Firebase VS Code uzantısı arayüzünü açın.
2. Yerel PostgreSQL'e Bağlan düğmesini tıklayın.

Sonraki adımlar