Oluşturulan iOS 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. Şemaları, sorguları ve mutasyonları tasarlarken özel bir istemci SDK'sı oluşturursunuz. Bu şemalar, sorgular ve mutasyonlar SQL Connect hizmetinize dağıtılır. Ardından, bu SDK'daki yöntemleri istemci mantığınıza entegre edersiniz.

Başka bir yerde de belirttiğimiz gibi, SQL Connectsorguları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 nedenle, mevcut kullanıcıların (ör. eski uygulama sürümlerinde) deneyimini bozmamak için ilgili istemci tarafı değişiklikleri dağıtmanız gerekir.

Bu nedenle SQL Connect, sunucuya dağıtılan şemalarınızı, sorgularınızı ve mutasyonlarınızı prototip olarak 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ıma hazır olur.

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

Başlangıç bölümündeki adımları uyguladıysanız SQL Connect için genel geliştirme akışıyla tanışmışsınızdır. Bu kılavuzda, şemanızdan Swift SDK'leri oluşturma ve istemci sorguları ile mutasyonlarla çalışma hakkında daha ayrıntılı bilgi bulabilirsiniz.

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

1. Firebase'i iOS uygulamanıza ekleyin.

2. Oluşturulan SDK'yı kullanmak için Xcode'da bağımlılık olarak yapılandırın.

   Xcode'un üst gezinme çubuğunda File > Add Package Dependencies > Add Local'ı (Dosya > Paket Bağımlılıkları Ekle > Yerel Ekle) seçin ve oluşturulan Package.swift'yi içeren klasörü belirleyin.

Ardından:

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

2. SDK oluşturmayı ayarlama:

   • SQL Connect VS Code uzantımızdaki SDK'yı uygulamaya ekle düğmesiyle
   • connector.yaml cihazınızı güncelleyerek

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

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

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

Swift SDK'nızı oluşturma

Uygulamalarınızda SQL Connect 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

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

Firebase CLI'yı kullanarak CI/CD derleme süreçlerinde SQL Connect SDK'ları oluşturabilirsiniz.

firebase dataconnect:sdk:generate

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

SQL Connect örneğinizi, SQL Connect'yı ayarlamak için kullandığınız bilgileri kullanarak başlatın. Bu bilgileri Firebase konsolunun Veritabanları ve Depolama > SQL Connect sayfasında bulabilirsiniz.

Bağlayıcı örneği alma

Bağlayıcınızın kodu, SQL Connect emülatörü tarafından oluşturulur. Bağlayıcı adınız movies ve paketiniz movies ise (connector.yaml içinde belirtildiği gibi) bağlayıcı nesnesini şu işlevi çağırarak alın:

let connector = DataConnect.moviesConnector

Sorguları ve mutasyonları uygulama

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şturabilirsiniz:

let mutationResult = try await connector.createMovieMutation.execute(
  title: "Empire Strikes Back",
  releaseYear: 1980,
  genre: "Sci-Fi",
  rating: 5)

print("Movie ID: \(mutationResult.data.movie_insert.id)")

Bir filmi almak için sorgu referansı kullanırsınız. Tüm sorgu referansları Observable yayıncılarıdır. Yapılandırılan yayıncıya bağlı olarak (connector.yaml)) @Observable makrosunu (iOS 17+) destekler veya ObservableObject protokolünü uygular. Hiçbiri belirtilmemişse varsayılan olarak iOS 17 ve sonraki sürümlerde desteklenen @Observable makrosu kullanılır.

Bir SwiftUI görünümünde, sorgu sonuçlarını yayınlanmış data sorgu referansı değişkenini kullanarak bağlayabilir ve verileri güncellemek için sorgunun execute() yöntemini çağırabilirsiniz. data değişkeni, GQL sorgu tanımınızda tanımlanan verilerin şekliyle eşleşir.

Alınan tüm sonuçlar Decodable protokolüne uygundur. GQL getirme işleminize nesnenin birincil anahtarını dahil ettiyseniz nesneler de Identifiable olur. Böylece bunları yineleyicilerde kullanabilirsiniz.

struct ListMovieView: View {
    @StateObject private var queryRef = connector.listMoviesByGenreQuery.ref(genre: "Sci-Fi")
    var body: some View {
        VStack {
            Button {
                Task {
                    do {
                        try await refresh()
                    } catch {
                        print("Failed to refresh: \(error)")
                    }
                }
            } label: {
                Text("Refresh")
            }
                // use the query results in a view
            ForEach(queryRef.data?.movies ?? [], id: \.self.id) { movie in
                    Text(movie.title)
                }
            }
    }
    @MainActor
    func refresh() async throws {
        _ = try await queryRef.execute()
    }
}

Sorgular, tek seferlik yürütmeyi de destekler.

let resultData = try await DataConnect.moviesConnector.listMoviesByGenreQuery.execute(genre: "Sci-Fi")

Değişikliklere abone olma

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

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, desteklenen yeni enum değerleri 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.

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

Esnek uygulama örneği

Oluşturulan SDK, bilinmeyen değerlerin işlenmesini zorunlu kılar. Bunun nedeni, oluşturulan numaralandırmaların _UNKNOWN değeri içermesi ve Swift'in kapsamlı anahtar ifadelerini zorunlu kılmasıdır.

do {
    let result = try await DataConnect.moviesConnector.listMovies.execute()
    if let data = result.data {
        for movie in data.movies {
            switch movie.aspectratio {
                case .ACADEMY: print("academy")
                case .WIDESCREEN: print("widescreen")
                case .ANAMORPHIC: print("anamorphic")
                case ._UNKNOWN(let unknownAspect): print(unknownAspect)
            }
        }
    }
} catch {
    // handle error
}

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

SQL 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 da uygulamanızın yaptığı veritabanı isteklerinin sayısını azaltabilir ve ağ kullanılabilirliği kesintiye uğradığında uygulamanızın veritabanına bağlı bölümlerinin çalışmasını sağlayabilir.

İ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:
  swiftSdk:
    outputDir: "../ios"
    package: "FirebaseDataConnectGenerated"
    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'da ö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 kalır. iOS 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 tarafınızdan ek bir adım atılması gerekmez. 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 daha eski değilse önbelleğe alınan değer kullanılır. Bu varsayılan davranışa PREFER_CACHE politikası denir.

  Ayrıca, execute() öğesinin tek tek çağrılmaları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.

  try await execute(fetchPolicy: .cacheOnly)
  

  try await execute(fetchPolicy: .serverOnly)
  

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

  Uygulamanızı test etmek ve prototipini oluşturmak için yerel emülatörü kullanabilirsiniz.

  İstemcileri yerel bir emülatör kullanacak şekilde yapılandırma

  SQL Connect emülatörünü SQL 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.

  let connector = DataConnect.moviesConnector
  // Connect to the emulator on "127.0.0.1:9399"
  connector.useEmulator()
  
  // (alternatively) if you're running your emulator on non-default port:
  connector.useEmulator(port: 9999)
  
  // Make calls from your app
  

  SQL Connect SDK'larındaki veri 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	Swift
  Dize	Dize
  Int	Int
  Kayan	Çift
  Boole	Boole
  UUID	UUID
  Tarih	FirebaseDataConnect.LocalDate
  Zaman damgası	FirebaseCore.Timestamp
  Int64	Int64
  Hepsi	FirebaseDataConnect.AnyValue