Utilizzare gli SDK per iOS generati

Gli SDK client Firebase Data Connect ti consentono di chiamare le query e le mutazioni lato server direttamente da un'app Firebase. Generi un SDK client personalizzato in parallelo mentre progetti gli schemi, le query e le mutazioni di cui esegui il deployment nel tuo Data Connect servizio. Poi, integri i metodi di questo SDK nella logica del client.

Come abbiamo già detto, è importante notare che Data Connect query e mutazioni non vengono inviate dal codice client ed eseguite sul server. Quando viene eseguito il deployment, le operazioni Data Connect vengono archiviate su il server come Cloud Functions. Ciò significa che devi eseguire il deployment delle modifiche lato client corrispondenti per evitare di interrompere gli utenti esistenti (ad esempio, nelle versioni precedenti dell'app ).

Per questo motivo, Data Connect ti fornisce un ambiente di sviluppo e strumenti che ti consentono di creare prototipi di schemi, query e mutazioni di cui è stato eseguito il deployment sul server. Genera anche automaticamente gli SDK lato client durante la creazione del prototipo.

Una volta eseguite le iterazioni degli aggiornamenti del servizio e delle app client, gli aggiornamenti lato server e lato client sono pronti per il deployment.

Che cos'è il flusso di lavoro di sviluppo client?

Se hai seguito la guida Introduzione, hai scoperto il flusso di sviluppo generale per Data Connect. In questa guida troverai informazioni più dettagliate sulla generazione di SDK Swift dallo schema e sull'utilizzo di query e mutazioni client.

Per riassumere, per utilizzare gli SDK Swift generati nelle app client, segui questi passaggi preliminari:

1. Aggiungi Firebase alla tua app per iOS.

2. Per utilizzare l'SDK generato, configurarlo come dipendenza in Xcode.

   Nella barra di navigazione in alto di Xcode, seleziona File > Add Package Dependencies > Add Local (File > Aggiungi dipendenze pacchetto > Aggiungi locale) e scegli la cartella contenente il file generato Package.swift.

Quindi:

1. Sviluppa lo schema dell'app.

2. Configura la generazione dell'SDK:

   • Con il pulsante Add SDK to app (Aggiungi SDK all'app) nella nostra estensione Data Connect VS Code
   • Aggiornando il file your connector.yaml

3. Inizializza il codice client e importa le librerie.

4. Implementa le chiamate a query e mutazioni.

5. Configura e utilizza l'Data Connect emulatore ed esegui le iterazioni.

Genera l'SDK Swift

Utilizza l'interfaccia a riga di comando Firebase per configurare gli SDK generati da Data Connect nelle tue app. Il comando init dovrebbe rilevare tutte le app nella cartella corrente e installare gli SDK generati automaticamente.

firebase init dataconnect:sdk

Aggiorna gli SDK durante la creazione del prototipo

Se hai installato l'estensione Data Connect VS Code, gli SDK generati saranno sempre aggiornati.

Se non utilizzi l'estensione Data Connect VS Code, puoi utilizzare l'interfaccia a riga di comando di Firebase per mantenere aggiornati gli SDK generati.

firebase dataconnect:sdk:generate --watch

Genera SDK nelle pipeline di build

Puoi utilizzare l'interfaccia a riga di comando di Firebase per generare gli SDK Data Connect nei processi di build CI/CD.

firebase dataconnect:sdk:generate

Inizializza l'SDK iOS Data Connect

Inizializza l'istanza Data Connect utilizzando le informazioni che hai utilizzato per configurare Data Connect (tutte disponibili nella console Firebasescheda Data Connect ).

Recupera un'istanza del connettore

Il codice del connettore verrà generato dall' Data Connect emulatore. Se il nome del connettore è movies e il pacchetto è movies, come specificato in connector.yaml, recupera l'oggetto connettore chiamando:

let connector = DataConnect.moviesConnector

Implementa query e mutazioni

Con l'oggetto connettore, puoi eseguire query e mutazioni come definito nel codice sorgente GraphQL. Supponiamo che il connettore abbia queste operazioni definite:

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
  }
}

Puoi quindi creare un film nel seguente modo:

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)")

Per recuperare un film, utilizzerai un riferimento alla query. Tutti i riferimenti alle query sono editori osservabili. A seconda dell'editore configurato (vedi connector.yaml), supportano la @Observable macro (iOS 17+) o implementano il ObservableObject protocollo. Il valore predefinito, se non ne viene specificato nessuno, è la @Observable macro supportata su iOS 17+.

In una visualizzazione SwiftUI, puoi associare i risultati della query utilizzando la data variabile pubblicata del riferimento alla query e chiamare il metodo execute() della query per aggiornare i dati. La variabile data corrisponderà alla forma dei dati definita nella definizione della query GQL.

Tutti i risultati recuperati sono conformi al protocollo Decodable. Se hai incluso la chiave primaria dell'oggetto nel recupero GQL, gli oggetti sono anche Identifiable, il che ti consente di utilizzarli negli iteratori.

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()
    }
}

Le query supportano anche l'esecuzione una tantum.

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

Gestisci le modifiche ai campi di enumerazione

Lo schema di un'app può contenere enumerazioni, a cui è possibile accedere tramite le query GraphQL.

Man mano che il design di un'app cambia, puoi aggiungere nuovi valori enum supportati. Ad esempio, supponiamo che in un secondo momento nel ciclo di vita dell'applicazione tu decida di aggiungere un valore FULLSCREEN all'enum AspectRatio.

Nel flusso di lavoro Data Connect, puoi utilizzare gli strumenti di sviluppo locali per aggiornare le query e gli SDK.

Tuttavia, prima di rilasciare una versione aggiornata dei client, i client di cui è stato eseguito il deployment precedente potrebbero non funzionare.

Esempio di implementazione resiliente

L'SDK generato impone la gestione dei valori sconosciuti, poiché gli enum generati contengono un valore _UNKNOWN e Swift applica istruzioni switch esaustive.

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
}

Crea prototipi e testa l'applicazione per iOS

Strumenta i client per utilizzare un emulatore locale

Puoi utilizzare l'emulatore Data Connect, sia dall' estensione Data Connect VS Code sia dall'interfaccia a riga di comando.

La strumentazione dell'app per la connessione all'emulatore è la stessa per entrambi gli scenari.

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

Tipi di dati negli SDK Data Connect

Il server Data Connect rappresenta i tipi di dati GraphQL comuni e personalizzati. Questi sono rappresentati nell'SDK come segue.