Oluşturulan Android SDK'larını kullanma

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

Başka bir yerde de belirttiğimiz gibi, Data Connectsorguların ve mutasyonların istemci kodu tarafından gönderilmediğini ve sunucuda yürütülmediğini unutmamak önemlidir. Bunun yerine, dağıtıldığında Data Connect işlemleri Cloud Functions gibi sunucuda depolanır. Bu nedenle, mevcut kullanıcıların (ör. uygulamanın eski sürümlerinde) deneyimini bozmamak için ilgili istemci tarafı değişiklikleri dağıtmanız gerekir.

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

Hizmetinizde ve istemci uygulamalarınızda güncellemeleri yineledikten sonra hem sunucu hem de istemci tarafı güncellemeleri dağıtılmaya hazır olur.

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

Başlayın bölümündeki talimatları uyguladıysanız Data Connect için genel geliştirme akışıyla tanışmışsınızdır. Bu kılavuzda, şemanızdan Android SDK'ları oluşturma, istemci sorguları ve mutasyonlarla ç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. Gradle'da Data Connect bağımlılığını 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şturmayı ayarlayın:

  3. İstemci kodunuzu başlatın ve kitaplıkları içe aktarın.

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

  5. Data Connect emülatörünü ayarlayıp kullanın ve yineleyin.

Kotlin SDK'nızı oluşturun

Uygulamalarınızda Data Connect tarafından oluşturulan SDK'ları ayarlamak için Firebase KSA'yı kullanın. init komutu, geçerli 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

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

Data 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

Firebase CLI'yı kullanarak CI/CD derleme işlemlerinde Data Connect SDK'ları oluşturabilirsiniz.

firebase dataconnect:sdk:generate

Müşteri kodunu ayarlama

Data Connect simgesini müşteri kodunuza ekleyin.

İstemci kodunuzu Data Connect ve oluşturduğunuz SDK'yı kullanacak şekilde ayarlamak için öncelikle standart Firebase kurulumu talimatlarını uygulayın.

Ardından, app/build.gradle.kts içindeki 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 bölümüne aşağıdakileri ekleyin: dependencies:

implementation(platform("com.google.firebase:firebase-bom:34.11.0"))
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

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

Data Connect hizmetini kurarken kullandığınız bilgileri kullanarak Data Connect örneğinizi başlatın (tümü Firebase konsolunun Data Connect sekmesinde mevcuttur).

ConnectorConfig nesnesi

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

Bu nesne, dataconnect.yaml içindeki serviceId ve location ile connector.yaml içindeki connectorId öğelerinden otomatik olarak oluşturulur.

Bağlayıcı örneği alma

Yapılandırma nesnesi oluşturduktan sonra Data Connectbağlayıcı örneği alın. Bağlayıcınızın kodu, Data Connect emülatörü tarafından oluşturulur. connector.yaml içinde belirtildiği gibi bağlayıcı adınız movies ve Kotlin paketiniz com.myapplication ise bağlayıcı nesnesini şu kodu çağırarak alın:

val connector = com.myapplication.MoviesConnector.instance

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

Bağlayıcı nesnesiyle, GraphQL kaynak kodunda tanımlandığı şekilde sorgu ve mutasyon ç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 şekilde 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 filmi 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, sorgunun execute() yöntemiyle yapılan bir çağrı kullanılarak yeni bir sorgu sonucu alındığında yalnızca sonuç üretecek bir Flow de 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

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

Bir uygulamanın şeması, numaralandırmalar içerebilir. Bu numaralandırmalara GraphQL sorgularınızla erişilebilir.

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

Data 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ılmış eski istemciler bozulabilir.

Esnek uygulama örneği

Oluşturulan SDK, bilinmeyen değerlerin işlenmesini zorunlu kılar. Bunun nedeni, müşterinin kodunun EnumValue nesnesini sarmalamayı açması gerektiğidir. 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

Data Connect, connector.yaml dosyası düzenlenerek etkinleştirilebilen 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ı azaltılabilir ve ağ kullanılabilirliği kesintiye uğradığında uygulamanızın veritabanına bağlı bölümlerinin çalışması sağlanabilir.

İstemci tarafı önbelleğe almayı etkinleştirmek için bağlayıcı yapılandırmanıza 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ırmada iki parametre vardır ve her ikisi de isteğe bağlıdır:

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

    maxAge için varsayılan değer 0'dir. Bu, yanıtların önbelleğe alındığı ancak istemci SDK'sının her zaman yeni değerler getireceği anlamına gelir. Ö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'de ö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 geçerli olmaya devam eder. Android SDK'larında varsayılan değer persistent'dır.

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 oluşturun. Bunu yaptı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 otomatik olarak gerçekleşir ve sizin herhangi bir ek işlem yapmanıza gerek yoktur. Ancak aşağıdakileri unutmayın:

  • execute()'nın varsayılan davranışı yukarıda açıklandığı gibidir: Bir sorgu için sonuç önbelleğe alınırsa ve önbelleğe alınan değer maxAge'dan eski değilse önbelleğe alınan değer kullanılır. Bu varsayılan davranışa PREFER_CACHE politikası denir.

    Ayrıca, execute()'nın tek tek çağrılarında yalnızca önbelleğe alınmış değerlerin sunulmasını (CACHE_ONLY) veya sunucudan koşulsuz olarak yeni değerlerin getirilmesini (SERVER_ONLY) de belirtebilirsiniz.

    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 bir emülatör kullanacak şekilde yapılandırma

    Data Connect emülatörünü, Data Connect VS Code uzantısından veya KSA'dan kullanabilirsiniz.

    Uygulamayı emülatöre bağlanacak şekilde ayarlama 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ı yorum satırı yapın.

    Data Connect SDK'larındaki veri türleri

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

    Data Connect Tür Kotlin
    Dize Dize
    Int SV (32 bit tam sayı)
    Kayan Çift (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