Oluşturulan Android SDK'larını kullanma

Firebase SQL Connect istemci SDK'ları, sunucu tarafı sorgularınızı ve mutasyonlarınızı doğrudan bir Firebase uygulamasından çağırmanıza olanak tanır. SQL Connect hizmetinize dağıttığınız şemaları, sorguları ve mutasyonları tasarlarken paralel olarak özel bir istemci SDK'sı oluşturursunuz. Ardından, bu SDK'daki yöntemleri istemci mantığınıza entegre edersiniz.

Başka yerlerde de belirttiğimiz gibi, SQL Connect sorguların ve mutasyonların istemci kodu tarafından gönderilmediğini ve sunucuda yürütülmediğini unutmayın. Bunun yerine, dağıtıldığında SQL Connect işlemleri Cloud Functions gibi sunucuda depolanır. Bu, mevcut kullanıcıların (örneğin, uygulamanın eski sürümlerinde) sorun yaşamaması için istemci tarafında ilgili değişiklikleri yapmanız gerektiği anlamına gelir.

Bu nedenle SQL Connect, sunucuya dağıtılan şemalarınızın, sorgularınızın ve mutasyonlarınızın prototipini oluşturmanıza olanak tanıyan bir geliştirici ortamı ve araçlar sunar. Ayrıca prototip oluştururken istemci tarafı SDK'ları otomatik olarak oluşturur.

Hizmet ve istemci uygulamalarınızda güncellemeleri yinelediğinizde hem sunucu hem de istemci tarafı güncellemeleri dağıtıma hazır olur.

İstemci geliştirme iş akışı nedir?

Başlangıç bölümünü takip ettiyseniz SQL Connect için genel geliştirme akışını öğrenmişsinizdir. Bu kılavuzda, şemanızdan Android SDK'ları oluşturma ve istemci sorguları ile mutasyonlarıyla çalışma hakkında daha ayrıntılı bilgi bulabilirsiniz.

Özetlemek gerekirse, oluşturulan Android SDK'larını istemci uygulamalarınızda kullanmak için aşağıdaki ön koşul adımlarını uygulamanız gerekir:

  1. Firebase'i Android uygulamanıza ekleyin.
  2. SQL Connect'i Gradle'da bağımlılık olarak yapılandırın.
  3. Kotlin Serialization Gradle eklentisini ve Gradle bağımlılığını ekleyin.

Ardından:

  1. Uygulama şemanızı geliştirin.

  2. SDK oluşturma işlemini ayarlama:

  3. İstemci kodunuzu ilk kullanıma hazırlayın ve kitaplıkları içe aktarın.

  4. Sorgulara ve mutasyonlara çağrıları uygulama

  5. SQL Connect emülatörünü kurup kullanın ve yineleyin.

Kotlin SDK'nızı oluşturma

Uygulamalarınızda SQL Connect tarafından oluşturulan SDK'ları ayarlamak için Firebase CLI'yı kullanın. init komutu, mevcut klasördeki tüm uygulamaları algılamalı ve oluşturulan SDK'ları otomatik olarak yüklemelidir.

firebase init dataconnect:sdk

Prototip oluştururken SDK'ları güncelleme

SQL Connect VS Code uzantısı yüklüyse oluşturulan SDK'lar her zaman güncel tutulur.

SQL Connect VS Code uzantısını kullanmıyorsanız oluşturulan SDK'ları güncel tutmak için Firebase CLI'yı kullanabilirsiniz.

firebase dataconnect:sdk:generate --watch

Derleme ardışık düzenlerinde SDK oluşturma

CI/CD derleme süreçlerinde SQL Connect SDK'ları oluşturmak için Firebase CLI'yı kullanabilirsiniz.

firebase dataconnect:sdk:generate

İstemci kodunu ayarlama

SQL Connect öğesini istemci kodunuza dahil etme

İstemci kodunuzu SQL Connect ve oluşturulan SDK'nızı kullanacak şekilde ayarlamak için önce standart Firebase kurulum talimatlarını uygulayın.

Ardından, app/build.gradle.kts dosyasındaki plugins bölümüne aşağıdakileri ekleyin:

// The Firebase team tests with version 1.8.22; however, other 1.8 versions,
// and all newer versions are expected work too.
kotlin("plugin.serialization") version "1.8.22" // MUST match the version of the Kotlin compiler

Ardından, app/build.gradle.kts dosyasındaki dependencies bölümüne aşağıdakileri ekleyin:

implementation(platform("com.google.firebase:firebase-bom:35.0.1"))
implementation("com.google.firebase:firebase-dataconnect")
implementation("com.google.firebase:firebase-auth") // Optional
implementation("com.google.firebase:firebase-appcheck") // Optional
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3") // Newer versions should work too
implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1") // Newer versions should work too

SQL Connect Android SDK'sını başlatma

SQL Connect örneğinizi, SQL Connect kurulumu için kullandığınız bilgileri kullanarak başlatın. Bu bilgileri Firebase konsolunun Databases & Storage (Veritabanları ve Depolama Alanı) > SQL Connect sayfasında bulabilirsiniz.

ConnectorConfig nesnesi

SDK için bir bağlayıcı yapılandırma nesnesi gerekir.

Bu nesne, dataconnect.yaml içindeki serviceId ve location ile connector.yaml içindeki connectorId kullanılarak otomatik olarak oluşturulur.

Bağlayıcı örneği alma

Yapılandırma nesnesini oluşturduğunuza göre artık bir SQL Connect bağlayıcı örneği alabilirsiniz. Bağlayıcınızın kodu SQL Connect emülatörü tarafından oluşturulur. Bağlayıcınızın adı movies ve Kotlin paketi com.myapplication ise (connector.yaml içinde belirtildiği gibi) bağlayıcı nesnesini şu çağrıyla alın:

val connector = com.myapplication.MoviesConnector.instance

Android SDK'nızdaki sorguları ve mutasyonları kullanma

Bağlayıcı nesnesiyle, GraphQL kaynak kodunda tanımlanan sorguları ve mutasyonları çalıştırabilirsiniz. Bağlayıcınızda aşağıdaki işlemlerin tanımlandığını varsayalım:

mutation createMovie($title: String!, $releaseYear: Int!, $genre: String!, $rating: Int!) {
  movie_insert(data: {
    title: $title
    releaseYear: $releaseYear
    genre: $genre
    rating: $rating
  })
}

query getMovieByKey($key: Movie_Key!) {
  movie(key: $key) { id title }
}

query listMoviesByGenre($genre: String!) {
  movies(where: {genre: {eq: $genre}}) {
    id
    title
  }
}

Ardından, aşağıdaki gibi bir film oluşturup alabilirsiniz:

val connector = MoviesConnector.instance

val addMovieResult1 = connector.createMovie.execute(
  title = "Empire Strikes Back",
  releaseYear = 1980,
  genre = "Sci-Fi",
  rating = 5
)

val movie1 = connector.getMovieByKey.execute(addMovieResult1.data.key)

println("Empire Strikes Back: ${movie1.data.movie}")

Birden fazla film de alabilirsiniz:

val connector = MoviesConnector.instance

val addMovieResult2 = connector.createMovie.execute(
  title="Attack of the Clones",
  releaseYear = 2002,
  genre = "Sci-Fi",
  rating = 5
)

val listMoviesResult = connector.listMoviesByGenre.execute(genre = "Sci-Fi")

println(listMoviesResult.data.movies)

Ayrıca, yalnızca sorgunun execute() yöntemine yapılan bir çağrı kullanılarak yeni bir sorgu sonucu alındığında sonuç üretecek bir Flow toplayabilirsiniz.

val connector = MoviesConnector.instance

connector.listMoviesByGenre.flow(genre = "Sci-Fi").collect { data ->
  println(data.movies)
}

connector.createMovie.execute(
  title="A New Hope",
  releaseYear = 1977,
  genre = "Sci-Fi",
  rating = 5
)

connector.listMoviesByGenre.execute(genre = "Sci-Fi") // will cause the Flow to get notified

Anlık değişikliklere abone olma

SQL Connect uygulamasından anlık güncellemeler alma başlıklı makaleyi inceleyin.

Numaralandırma alanlarındaki değişiklikleri işleme

Bir uygulamanın şeması, GraphQL sorgularınız tarafından erişilebilen numaralandırmalar içerebilir.

Uygulamanın tasarımı değiştikçe yeni enum desteklenen değerler ekleyebilirsiniz. Örneğin, uygulamanızın yaşam döngüsünün ilerleyen aşamalarında AspectRatio enum'una FULLSCREEN değerini eklemeye karar verdiğinizi varsayalım.

SQL Connect iş akışında, sorgularınızı ve SDK'larınızı güncellemek için yerel geliştirme araçlarını kullanabilirsiniz.

Ancak istemcilerinizin güncellenmiş bir sürümünü yayınlamadan önce, daha önce dağıtılan istemciler bozulabilir.

Esnek uygulama örneği

Oluşturulan SDK, bilinmeyen değerlerin işlenmesini zorunlu kılar. Bunun nedeni, müşterinin kodunun EnumValue nesnesini sarmalamadan çıkarması gerekmesidir. Bu nesne, bilinen enum değerleri için EnumValue.Known, bilinmeyen değerler için ise EnumValue.Unknown olur.

val result = connector.listMoviesByAspectRatio.execute(AspectRatio.WIDESCREEN)
val encounteredAspectRatios = mutableSetOf<String>()

result.data.movies
  .mapNotNull { it.otherAspectRatios }
  .forEach { otherAspectRatios ->
    otherAspectRatios
      .filterNot { it.value == AspectRatio.WIDESCREEN }
      .forEach {
        when (it) {
          is EnumValue.Known -> encounteredAspectRatios.add(it.value.name)
          is EnumValue.Unknown ->
            encounteredAspectRatios.add("[unknown ratio: ${it.stringValue}]")
        }
      }
  }

println(
  "Widescreen movies also include additional aspect ratios: " +
    encounteredAspectRatios.sorted().joinToString()
)

İstemci tarafı önbelleğe almayı etkinleştirme

SQL Connect, connector.yaml dosyasını düzenleyerek etkinleştirebileceğiniz isteğe bağlı bir istemci tarafı önbelleğe alma özelliğine sahiptir. Bu özellik etkinleştirildiğinde, oluşturulan istemci SDK'ları sorgu yanıtlarını yerel olarak önbelleğe alır. Bu sayede uygulamanızın yaptığı veritabanı isteklerinin sayısı azalır ve ağ bağlantısı kesildiğinde uygulamanızın veritabanına bağlı bölümleri çalışmaya devam eder.

İstemci tarafı önbelleğe almayı etkinleştirmek için bağlayıcı yapılandırmanıza bir istemci önbelleğe alma yapılandırması ekleyin:

generate:
  kotlinSdk:
    outputDir: "../android"
    package: "com.google.firebase.dataconnect.generated"
    clientCache:
      maxAge: 5s
      storage: persistent

Bu yapılandırmanın her ikisi de isteğe bağlı olan iki parametresi vardır:

  • maxAge: İstemci SDK'sı yeni değerleri getirmeden önce önbelleğe alınmış bir yanıtın sahip olabileceği maksimum yaş. Örnekler: "0", "30s", "1h30m".

    maxAge için varsayılan değer 0 olduğundan yanıtlar önbelleğe alınır ancak istemci SDK'sı her zaman yeni değerleri getirir. Önbelleğe alınan değerler yalnızca CACHE_ONLY, execute() olarak belirtildiğinde kullanılır.

  • storage: İstemci SDK'sı, yanıtları persistent depolama alanında veya memory içinde önbelleğe alacak şekilde yapılandırılabilir. persistent depolama alanında önbelleğe alınan sonuçlar, uygulama yeniden başlatıldığında da korunur. Android SDK'larında varsayılan değer persistent şeklindedir.

Bağlayıcınızın önbelleğe alma yapılandırmasını güncelledikten sonra istemci SDK'larınızı yeniden oluşturun ve uygulamanızı yeniden derleyin. Bu işlemi tamamladıktan sonra execute(), yanıtları önbelleğe alır ve yapılandırdığınız politikaya göre önbelleğe alınmış değerleri kullanır. Bu işlem genellikle sizin ek bir işlem yapmanıza gerek kalmadan otomatik olarak gerçekleşir. Ancak aşağıdakilere dikkat edin:

  • execute() için varsayılan davranış yukarıda açıklandığı gibidir: Bir sorgu için sonuç önbelleğe alınmışsa ve önbelleğe alınan değer maxAge değerinden daha eski değilse önbelleğe alınan değer kullanılır. Bu varsayılan davranış, PREFER_CACHE politikası olarak adlandırılır.

    Ayrıca, execute() için tek tek çağrılar belirterek yalnızca önbelleğe alınmış değerleri yayınlamasını (CACHE_ONLY) veya sunucudan koşulsuz olarak yeni değerleri getirmesini (SERVER_ONLY) sağlayabilirsiniz.

    val queryResult = queryRef.execute(QueryRef.FetchPolicy.CACHE_ONLY)

    val queryResult = queryRef.execute(QueryRef.FetchPolicy.SERVER_ONLY)

    Android uygulamanızın prototipini oluşturma ve test etme

    İstemcileri yerel emülatör kullanacak şekilde ayarlama

    SQL Connect emülatörünü SQL Connect VS Code uzantısından veya CLI'dan kullanabilirsiniz.

    Uygulamayı emülatöre bağlanacak şekilde yapılandırma işlemi her iki senaryoda da aynıdır.

    val connector = MoviesConnector.instance

// Connect to the emulator on "10.0.2.2:9399"
connector.dataConnect.useEmulator()

// (alternatively) if you're running your emulator on non-default port:
connector.dataConnect.useEmulator(port = 9999)

// Make calls from your app

    Üretim kaynaklarına geçmek için emülatöre bağlanma satırlarını açıklama satırı yapın.

    SQL Connect SDK'larındaki SQL türleri

    SQL Connect sunucusu, yaygın ve özel GraphQL veri türlerini temsil eder. Bunlar SDK'da aşağıdaki gibi gösterilir.

    SQL Connect Türü Kotlin
    Dize Dize
    Int Int (32 bit tam sayı)
    Kayan Double (64 bit kayan nokta)
    Boole Boole
    UUID java.util.UUID
    Tarih com.google.firebase.dataconnect.LocalDate (16.0.0-beta03 sürümüne kadar java.util.Date idi)
    Zaman damgası com.google.firebase.Timestamp
    Int64 Uzun
    Hepsi com.google.firebase.dataconnect.AnyValue