Utilizzare gli SDK per iOS generati

Gli SDK client di 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 durante la progettazione degli schemi, delle query e delle mutazioni da eseguire nel servizio Data Connect. Quindi, puoi integrare i metodi di questo SDK nella logica del client.

Come accennato altrove, è importante notare che le query e le mutazioni Data Connect non vengono inviate dal codice client ed eseguite sul server. Al contrario, quando vengono di cui è stato eseguito il deployment, le operazioni Data Connect vengono memorizzate sul server come Cloud Functions. Ciò significa che devi implementare le modifiche lato client corrispondenti per evitare di interrompere gli utenti esistenti (ad esempio, nelle versioni precedenti dell'app).

Ecco perché Data Connect ti offre un ambiente di sviluppo e strumenti che ti consentono di prototipare schemi, query e mutazioni di cui è stato eseguito il deployment sul server. Inoltre, genera automaticamente gli SDK lato client durante la creazione del prototipo.

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

Generare l'SDK Swift

Come per la maggior parte dei progetti Firebase, il lavoro sul codice client Firebase Data Connect viene eseguito in una directory locale del progetto. Sia l'estensione VS Code di Data Connect sia la CLI di Firebase sono importanti strumenti locali per la generazione e la gestione del codice client.

Le opzioni di generazione dell'SDK sono associate a diverse voci nel file dataconnect.yaml generato al momento dell'inizializzazione del progetto.

Inizializza la generazione dell'SDK

connectorId: "movies"
generate:
  swiftSdk:
    outputDir: "../movies-generated"
    package: "Movies"

outputDir specifica dove deve essere generato l'SDK. Se non specificata, la cartella del connettore viene utilizzata come directory di output predefinita.

package specifica il nome del pacchetto che verrà generato. Il generatore creerà una cartella con il nome del pacchetto contenente Package.swift e il codice generato.

observablePublisher (facoltativo) specifica il publisher Observable da utilizzare nei riferimenti query. I valori possibili sono observableMacro (iOS 17 e versioni successive) e observableObject (precedenti a iOS 17). Se non viene specificato alcun valore, il valore predefinito è observableMacro.

Aggiornare gli SDK durante la prototipazione

Se stai creando una prototipazione in modo interattivo con l'estensione VS Code di Data Connect e il relativo emulatore Data Connect, i file di codice sorgente dell'SDK vengono generati e aggiornati automaticamente mentre modifichi i file Data Connect che definiscono schemi, query e mutazioni. Questa può essere una funzionalità utile nei flussi di lavoro di (ri)caricamento a caldo.

In alternativa, puoi utilizzare la CLI per rigenerare gli SDK ogni volta che i file .gql vengono modificati:

firebase dataconnect:sdk:generate --watch

Genera SDK per l'integrazione e per le release di produzione

In alcuni scenari, ad esempio per preparare le origini del progetto da inviare per i test CI, puoi chiamare la CLI Firebase per un aggiornamento collettivo.

In questi casi, utilizza firebase dataconnect:sdk:generate.

Configurare il codice client

Per configurare il codice client in modo che utilizzi Data Connect e l'SDK generato, segui prima le istruzioni di configurazione standard di Firebase.

Poi apri l'area di lavoro dell'app utilizzando Xcode.

Nella barra di navigazione in alto, seleziona File > Aggiungi dipendenze del pacchetto > Aggiungi Locale e scegli la cartella contenente il file di originePackage.swift generato.

Inizializza l'SDK Data Connect per iOS

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

Ottenere un'istanza del connettore

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

let connector = DataConnect.moviesConnector

Esecuzione di query e mutazioni

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

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

A questo punto, puoi creare un filmato 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 query sono publisher osservabili. A seconda del publisher configurato (vedi connector.yaml)), supportano la macro @Observable (iOS 17 e versioni successive) o implementano il protocollo ObservableObject. Se non viene specificato alcun valore, il valore predefinito è la macro @Observable supportata su iOS 17 e versioni successive.

In una vista SwiftUI, puoi associare i risultati della query utilizzando la variabile data pubblicata del riferimento della 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, anche gli oggetti sono Identifiable, consentendoti di utilizzarli in 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")

Prototipazione e test della tua applicazione iOS

Consenti ai client di utilizzare un emulatore locale

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

L'instrumentazione 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. Queste sono rappresentate nell'SDK come segue.