Inizia a utilizzare Firebase Data Connect localmente

In questa guida rapida, scoprirai come compilare Firebase Data Connect nella tua applicazione localmente senza configurare un'istanza SQL di produzione. Imparerai a:

  • Aggiungi Firebase Data Connect al tuo progetto Firebase.
  • Configura un ambiente di sviluppo che includa un'estensione di Visual Studio Code per lavorare con un'istanza locale.
  • Ti mostreremo come:
    • Creare uno schema per un'app di film
    • Definisci le query e le mutazioni che verranno utilizzate nella tua app
    • Testa le query e le mutazioni con dati di esempio su un emulatore locale
    • Genera SDK fortemente tipizzati e utilizzali nella tua app
    • Esegui il deployment dello schema, delle query e dei dati finali nel cloud (facoltativo, con un upgrade del piano Blaze).

Scegli un flusso di sviluppo locale

Data Connect offre due modi per installare gli strumenti di sviluppo e lavorare localmente.

Prerequisiti

Per utilizzare questa guida rapida, devi avere quanto segue.

  • Un progetto Firebase. Se non ne hai ancora creato uno, fallo nella console Firebase.

Configura l'ambiente di sviluppo

  1. Crea una nuova directory per il progetto locale.

  2. Esegui il seguente comando nella nuova directory creata.

      curl -sL https://firebase.tools/dataconnect | bash

    Questo script tenta di configurare l'ambiente di sviluppo e di avviare un IDE basato su browser. Questo IDE fornisce strumenti, inclusa un'estensione VS Code precompilata, per aiutarti a gestire lo schema e a definire query e mutazioni da utilizzare nella tua applicazione, nonché a generare SDK fortemente tipizzati.

alias dataconnect='curl -sL https://firebase.tools/dataconnect | bash'

Configura la directory del progetto

Per configurare il progetto locale, inizializza la directory del progetto. Nella finestra IDE, nel riquadro a sinistra, fai clic sull'icona di Firebase per aprire l'interfaccia utente dell'estensione VS Code di Data Connect:

  1. Fai clic sul pulsante Accedi con Google.
  2. Fai clic sul pulsante Collega un progetto Firebase e seleziona il progetto che hai creato in precedenza nella console.
  3. Fai clic sul pulsante Esegui firebase init.

  4. Fai clic sul pulsante Avvia emulatori.

Crea uno schema

Nella directory del progetto Firebase, nel file /dataconnect/schema/schema.gql, inizia a definire uno schema GraphQL sui film.

Film

In Data Connect, i campi GraphQL vengono mappati alle colonne. Il film ha id, title, imageUrl e genre. Data Connect riconosce i tipi di dati primitivi: String e UUID.

Copia lo snippet seguente o rimuovi il commento dalle righe corrispondenti nel file.

# By default, a UUID id key will be created by default as primary key.
# If you want to specify a primary key, say title, which you can do through
# the @table(key: "title") directive
type Movie @table {
  id: UUID! @default(expr: "uuidV4()")
  title: String!
  imageUrl: String!
  genre: String
}

MovieMetadata

Copia lo snippet seguente o rimuovi il commento dalle righe corrispondenti nel file.

# Movie - MovieMetadata is a one-to-one relationship
type MovieMetadata @table {
  # This time, we omit adding a primary key because
  # you can rely on Data Connect to manage it.

  # @unique indicates a 1-1 relationship
  movie: Movie! @unique
  # movieId: UUID <- this is created by the above reference
  rating: Float
  releaseYear: Int
  description: String
}

Tieni presente che il campo movie è mappato a un tipo di Movie. Data Connect è consapevole che si tratta di un rapporto tra Movie e MovieMetadata e gestirà questo rapporto per te.

Scopri di più sugli schemi di Data Connect nella documentazione

Aggiungere dati alle tabelle

Nel riquadro dell'editor IDE, vedrai i pulsanti CodeLens sopra i tipi GraphQL in /dataconnect/schema/schema.gql. Puoi utilizzare i pulsanti Aggiungi dati e Esegui (locale) per aggiungere dati al database locale.

Per aggiungere record alle tabelle Movie e MovieMetadata:

  1. In schema.gql, fai clic sul pulsante Aggiungi dati sopra la dichiarazione del tipo Movie.
    Pulsante Aggiungi dati di CodeLens per Firebase Data Connect
  2. Nel file Movie_insert.gql generato, inserisci i dati hardcoded per i tre campi.
  3. Fai clic sul pulsante Esegui (locale).
    Pulsante Esegui di CodeLens per Firebase Data Connect
  4. Ripeti i passaggi precedenti per aggiungere un record alla tabella MovieMetadata, fornendo il id del film nel campo movieId, come richiesto nella mutazione MovieMetadata_insert generata.

Per verificare rapidamente che i dati siano stati aggiunti:

  1. Torna in schema.gql e fai clic sul pulsante Leggi dati sopra la dichiarazione di tipo Movie.
  2. Nel file Movie_read.gql risultante, fai clic sul pulsante Esegui (locale) per eseguire la query.

Scopri di più sulle mutazioni di Data Connect nella documentazione

Definire la query

Ora la parte divertente: definiamo le query di cui avrai bisogno nella tua applicazione. In qualità di sviluppatore, sei abituato a scrivere query SQL anziché query GraphQL, quindi all'inizio può sembrare un po' diverso.

Tuttavia, GraphQL è molto più conciso e sicuro dal punto di vista del tipo rispetto a SQL non elaborato. Inoltre, la nostra estensione VS Code semplifica l'esperienza di sviluppo.

Inizia a modificare il file /dataconnect/connector/queries.gql. Se vuoi recuperare tutti i film, utilizza una query come questa.

# File `/dataconnect/connector/queries.gql`

# @auth() directives control who can call each operation.
# Anyone should be able to list all movies, so the auth level is set to PUBLIC
query ListMovies @auth(level: PUBLIC) {
  movies {
    id
    title
    imageUrl
    genre
  }
}

Esegui la query utilizzando il pulsante CodeLens nelle vicinanze.

Una funzionalità davvero interessante è la possibilità di trattare le relazioni del database come un grafo. Poiché un record MovieMetadata ha un campo movie che fa riferimento a un film, puoi nidificare il campo e recuperare le informazioni su le informazioni sul film. Prova ad aggiungere il tipo movieMetadata_on_movie generato alla query ListMovies.

query ListMovies @auth(level: PUBLIC) {
  movies {
    id
    title
    imageUrl
    genre
    movieMetadata_on_movie {
        rating
    }
  }
}

Scopri di più sulle query di Data Connect nella documentazione

Genera SDK e utilizzali nella tua app

Nel riquadro a sinistra dell'IDE, fai clic sull'icona di Firebase per aprire l'interfaccia utente dell'estensione Data Connect di VS Code:

  1. Fai clic sul pulsante Aggiungi SDK all'app.

  2. Nella finestra di dialogo visualizzata, seleziona una directory contenente il codice per la tua app. Il codice dell'SDK Data Connect verrà generato e salvato lì.

  3. Seleziona la piattaforma della tua app, quindi tieni presente che il codice SDK viene generato immediatamente nella directory selezionata.

Utilizzare gli SDK per chiamare la query da un'app

Puoi utilizzare l'SDK generato da Data Connect per implementare una chiamata alla tua query ListMovies. Puoi quindi eseguire questa query localmente utilizzando l'emulatore Data Connect.

Web

  1. Aggiungi Firebase alla tua app web.

  2. Nel file principale dell'app React:

    • Importa l'SDK generato
    • Esegui l'instrumentazione dell'app per connetterla all'emulatore Data Connect
    • chiama i metodi Data Connect.

    Puoi copiare il seguente snippet ed eseguirlo come app autonoma.

    import React from 'react';
import ReactDOM from 'react-dom/client';

import { connectDataConnectEmulator } from 'firebase/data-connect';

// Generated queries.
// Update as needed with the path to your generated SDK.
import { listMovies, ListMoviesData } from '@movie-app/movies';

const dataConnect = getDataConnect(connectorConfig);
connectDataConnectEmulator(dataConnect, 'localhost', 9399);

function App() {
  const [movies, setMovies] = useState<ListMoviesData['movies']>([]);
  useEffect(() => {
    listMovies.then(res => setMovies(res.data));
  }, []);
  return (
    movies.map(movie => <h1>{movie.title}</h1>);
  );
}

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<App />);

Swift

  1. Aggiungi Firebase alla tua app per iOS.

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

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

  3. Nel delegato principale dell'app:

    • Importa l'SDK generato
    • Esegui l'instrumentazione dell'app per connetterla all'emulatore Data Connect
    • chiama i metodi Data Connect.

    Puoi copiare il seguente snippet ed eseguirlo come app autonoma.

    import SwiftUI

import FirebaseDataConnect
// Generated queries.
// Update as needed with the package name of your generated SDK.
import <CONNECTOR-PACKAGE-NAME>

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)

struct ListMovieView: View {
@StateObject private var queryRef = connector.listMovies.ref()

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

    struct ContentView_Previews: PreviewProvider {
    static var previews: some View {
        ListMovieView()
    }
}

Kotlin per Android

  1. Aggiungi Firebase alla tua app Android.

  2. Per utilizzare l'SDK generato, configura Data Connect come dipendenza in Gradle.

    Aggiorna plugins e dependencies in app/build.gradle.kts.

    plugins {
  // Use whichever versions of these dependencies suit your application.
  // The versions shown here were the latest as of December 03, 2024.
  // Note, however, that the version of kotlin("plugin.serialization") must,
  // in general, match the version of kotlin("android").
  id("com.android.application") version "8.7.3"
  id("com.google.gms.google-services") version "4.4.2"
  val kotlinVersion = "2.1.0"
  kotlin("android") version kotlinVersion
  kotlin("plugin.serialization") version kotlinVersion
}

dependencies {
  // Use whichever versions of these dependencies suit your application.
  // The versions shown here were the latest versions as of December 03, 2024.
  implementation("com.google.firebase:firebase-dataconnect:16.0.0-beta03")
  implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
  implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.7.3")

  // These dependencies are not strictly required, but will very likely be used
  // when writing modern Android applications.
  implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0")
  implementation("androidx.appcompat:appcompat:1.7.0")
  implementation("androidx.activity:activity-ktx:1.9.3")
  implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.8.7")
  implementation("com.google.android.material:material:1.12.0")
}

  3. Nell'attività principale dell'app:

    • Importa l'SDK generato
    • Esegui l'instrumentazione dell'app per connetterla all'emulatore Data Connect
    • chiama i metodi Data Connect.

    Puoi copiare il seguente snippet ed eseguirlo come app autonoma.

    import android.os.Bundle
import android.widget.TextView
import androidx.appcompat.app.AppCompatActivity
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.repeatOnLifecycle
import kotlinx.coroutines.launch


private val connector = com.myapplication.MoviesConnector.instance
  .apply {
    // Connect to the emulator on "10.0.2.2:9399" (default port)
    dataConnect.useEmulator()

    // (alternatively) if you're running your emulator on non-default port:
    // dataConnect.useEmulator(port = 9999)
  }


class MainActivity : AppCompatActivity() {

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    val textView: TextView = findViewById(R.id.text_view)

    lifecycleScope.launch {
      lifecycle.repeatOnLifecycle(Lifecycle.State.STARTED) {
        
        val result = connector.listMovies.runCatching { execute { } }
        
        val newTextViewText = result.fold(
          onSuccess = {
            val titles = it.data.movies.map { it.title }
            "${titles.size} movies: " + titles.joinToString(", ")
          },
          onFailure = { "ERROR: ${it.message}" }
        )
        textView.text = newTextViewText
      }
    }
  }
}

Flutter

  1. Aggiungi Firebase alla tua app Flutter.
  2. Installa l'interfaccia a riga di comando flutterfire dart pub global activate flutterfire_cli.
  3. Esegui flutterfire configure.

  4. Nella funzione principale dell'app:

    • Importa l'SDK generato
    • Esegui l'instrumentazione dell'app per connetterla all'emulatore Data Connect
    • chiama i metodi Data Connect.

    Puoi copiare il seguente snippet ed eseguirlo come app autonoma.

import 'package:firebase_core/firebase_core.dart';
import 'package:flutter/material.dart';
import 'firebase_options.dart';

// Generated queries.
// Update as needed with the path to your generated SDK

import 'movies_connector/movies.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  await Firebase.initializeApp(
    options: DefaultFirebaseOptions.currentPlatform,
  );
  
  MoviesConnector.instance.dataConnect
      .useDataConnectEmulator(Uri.base.host, 443, isSecure: true);
  
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
        home: Scaffold(
            body: Column(children: [
      ConstrainedBox(
        constraints: const BoxConstraints(maxHeight: 200),
        child: FutureBuilder(
            future: MoviesConnector.instance.listMovies().execute(),
            builder: (context, snapshot) {
              if (snapshot.connectionState == ConnectionState.done) {
                return ListView.builder(
                  scrollDirection: Axis.vertical,
                  itemBuilder: (context, index) => Card(
                      child: Text(
                    snapshot.data!.data.movies[index].title,
                  )),
                  itemCount: snapshot.data!.data.movies.length,
                );
              }
              return const CircularProgressIndicator();
            }),
      )
    ])));
  }
}

Esegui il deployment dello schema e della query in produzione

Una volta completata la configurazione locale nell'app, puoi eseguire il deployment di schema, dati e query nel cloud. Per configurare un'istanza Cloud SQL, devi avere un progetto con piano Blaze.

  1. Vai alla sezione Data Connect della console Firebase e crea un'istanza Cloud SQL di prova senza costi.

  2. Nel terminale integrato dell'IDE, esegui firebase init dataconnect e seleziona l'ID regione/servizio che hai appena creato nella console.

  3. Seleziona "Y" quando viene visualizzato il messaggio "Il file dataconnect/dataconnect.yaml esiste già. Vuoi sovrascriverlo?".

  4. Nella finestra dell'IDE, nell'interfaccia utente dell'estensione VS Code, fai clic sul pulsante Esegui il deployment in produzione.

  5. Una volta eseguito il deployment, vai alla console Firebase per verificare che lo schema, le operazioni e i dati siano stati caricati sul cloud. Dovresti essere in grado di visualizzare lo schema ed eseguire le operazioni anche sulla console. L'istanza Cloud SQL per PostgreSQL verrà aggiornata con lo schema e i dati generati di cui è stato eseguito il deployment finale.

Passaggi successivi

Esamina il progetto di cui è stato eseguito il deployment e scopri altri strumenti:

  • Aggiungi dati al database, controlla e modifica gli schemi e monitora il servizio Data Connect nella console Firebase.

Per ulteriori informazioni, consulta la documentazione. Ad esempio, poiché hai completato la guida rapida: