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 alla progettazione degli schemi, delle query e delle mutazioni che implementi nel tuo servizio Data Connect. Poi, integra i metodi di questo SDK nella logica del client.

Come abbiamo già detto, è importante notare che le Data Connect query e le mutazioni non vengono inviate dal codice client ed eseguite sul server. Al contrario, una volta eseguito il deployment, le operazioni Data Connect vengono archiviate sul server come Cloud Functions. Ciò significa che devi implementare le modifiche lato client corrispondenti per evitare di interrompere l'esperienza degli 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 prototipare schemi, query e mutazioni implementati sul server. Inoltre, genera automaticamente gli SDK lato client durante la prototipazione.

Una volta completati gli aggiornamenti iterativi del servizio e delle app client, gli aggiornamenti lato server e lato client sono pronti per il deployment.

Qual è il flusso di lavoro di sviluppo del client?

Se hai seguito la guida Inizia, hai appreso il flusso di sviluppo complessivo 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 tue app client, segui questi passaggi preliminari:

  1. Aggiungi Firebase alla tua app iOS.

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

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

Quindi:

  1. Sviluppa lo schema dell'app.

  2. Configura la generazione dell'SDK:

  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 e itera.

Genera l'SDK Swift

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

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

Inizializza la generazione dell'SDK

Nel tuo connector.yaml, aggiungi outputDir, package e (per l'SDK web) packageJsonDir. 
connectorId: "movies"
generate:
  swiftSdk:
    outputDir: "../movies-generated"
    package: "Movies"

outputDir specifica la posizione in cui deve essere generato l'output dell'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.

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

Aggiornare gli SDK durante la prototipazione

Se prototipi in modo interattivo con l'estensione VS Code Data Connect e il relativo emulatore Data Connect, i file di origine dell'SDK vengono generati e aggiornati automaticamente mentre modifichi i file .gql che definiscono schemi, query e mutazioni. Può essere una funzionalità utile nei flussi di lavoro di ricaricamento a caldo.

In altri scenari, se utilizzi l'emulatore Data Connect dalla CLI Firebase, puoi impostare un monitoraggio degli aggiornamenti .gql e anche aggiornare automaticamente le origini SDK.

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

firebase dataconnect:sdk:generate --watch

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

In alcuni scenari, ad esempio la preparazione delle origini del progetto da inviare per i test CI, puoi chiamare la CLI Firebase per un aggiornamento batch.

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

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

Recupero di un'istanza del connettore

Il codice per il 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

Implementare 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 alle query sono publisher osservabili. A seconda del publisher configurato (vedi connector.yaml)), supportano la macro @Observable (iOS 17+) 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 visualizzazione SwiftUI, puoi associare i risultati della query utilizzando la variabile data 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")

Prototipa e testa l'applicazione per iOS

Strumentare i client per utilizzare un emulatore locale

Puoi utilizzare l'emulatore Data Connect, sia dall'estensione VS Code Data Connect sia dalla CLI.

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. Questi sono rappresentati nell'SDK come segue.

Tipo di connessione Data Connect Swift
Stringa Stringa
Int Int
In virgola mobile Doppio
Booleano Bool
UUID UUID
Data FirebaseDataConnect.LocalDate
Timestamp FirebaseCore.Timestamp
Int64 Int64
Qualsiasi FirebaseDataConnect.AnyValue