Pierwsze kroki z Firebase Data Connect na komputerze

Z tego krótkiego wprowadzenia dowiesz się, jak tworzyć Firebase Data Connect lokalnie w aplikacji bez konfigurowania produkcyjnej instancji SQL. W ramach ćwiczenia:

  • Dodaj Firebase Data Connect do projektu Firebase.
  • Skonfiguruj środowisko programistyczne, w tym rozszerzenie Visual Studio Code, aby pracować z lokalną instancją.
  • Następnie pokażemy Ci, jak:
    • Tworzenie schematu aplikacji filmowej
    • zdefiniuj zapytania i mutacje, które będą używane w aplikacji;
    • Testowanie zapytań i mutacji za pomocą przykładowych danych w lokalnym emulatorze
    • Generowanie pakietów SDK o ściśle określonym typie i ich używanie w aplikacji
    • Wdróż ostateczny schemat, zapytania i dane w chmurze (opcjonalnie, w ramach przeniesienia na abonament Blaze).

Wybierz lokalny proces tworzenia

Data Connect oferuje 2 sposoby instalowania narzędzi programistycznych i pracy lokalnie.

Wymagania wstępne

Aby skorzystać z tego samouczka, musisz mieć:

  • Masz projekt Firebase. Jeśli nie masz jeszcze konta, utwórz je w konsoli Firebase.

Konfigurowanie środowiska programistycznego

  1. Utwórz nowy katalog dla lokalnego projektu.

  2. W nowym katalogu uruchom to polecenie.

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

    Ten skrypt próbuje skonfigurować środowisko programistyczne i uruchomić środowisko IDE w przeglądarce. To środowisko IDE udostępnia narzędzia, w tym wstępnie skompilowane rozszerzenie VS Code, które ułatwia zarządzanie schematem i definiowanie zapytań oraz mutacji do wykorzystania w aplikacji, a także generowanie silnie typowanych pakietów SDK.

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

Konfigurowanie katalogu projektu

Aby skonfigurować projekt lokalny, zainicjuj katalog projektu. W oknie IDE w panelu po lewej stronie kliknij ikonę Firebase, aby otworzyć interfejs Data Connect w rozszerzeniu VS Code:

  1. Kliknij przycisk Zaloguj się przez Google.
  2. Kliknij przycisk Połącz z projektem Firebase i wybierz projekt utworzony wcześniej w konsoli.
  3. Kliknij przycisk Uruchom init Firebase.

  4. Kliknij przycisk Uruchom emulatory.

Tworzenie schematu

W katalogu projektu Firebase w pliku /dataconnect/schema/schema.gql zacznij definiować schemat GraphQL dotyczący filmów.

Film

W Data Connect pola GraphQL są mapowane na kolumny. Film zawiera id, title, imageUrl i genre. Data Connect rozpoznaje prymitywne typy danych: String i UUID.

Skopiuj ten fragment kodu lub odkomentuj odpowiednie wiersze w pliku.

# 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

Skopiuj ten fragment kodu lub odkomentuj odpowiednie wiersze w pliku.

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

Zwróć uwagę, że pole movie jest zmapowane na typ Movie. Data Connect rozumie, że jest to relacja między Movie a MovieMetadata i będzie zarządzać tą relacją w Twoim imieniu.

Więcej informacji o schematach Data Connect znajdziesz w dokumentacji

Dodawanie danych do tabel

W panelu edytora IDE zobaczysz przyciski CodeLens nad typami GraphQL w /dataconnect/schema/schema.gql. Za pomocą przycisków Dodaj dane i Uruchom (lokalnie) możesz dodawać dane do lokalnej bazy danych.

Aby dodać rekordy do tabel Movie i MovieMetadata:

  1. W schema.gql nad deklaracją typu Movie kliknij przycisk Dodaj dane.
    Przycisk CodeLens Dodaj dane w Firebase Data Connect
  2. W wygenerowanym pliku Movie_insert.gql zakoduj na stałe dane dla tych 3 pol.
  3. Kliknij przycisk Uruchom (lokalnie).
    Przycisk Uruchom CodeLens w Firebase Data Connect
  4. Powtórz poprzednie czynności, aby dodać rekord do tabeli MovieMetadata, podając w polu movieId id swojego filmu zgodnie z wytycznymi w wygenerowanej mutacji MovieMetadata_insert.

Aby szybko sprawdzić, czy dane zostały dodane:

  1. W pliku schema.gql kliknij przycisk Odczytaj dane nad deklaracją typu Movie.
  2. Aby wykonać zapytanie, w wygenerowanym pliku Movie_read.gql kliknij przycisk Uruchom (lokalnie).

Więcej informacji o mutacjach w Data Connect znajdziesz w dokumentacji

Definiowanie zapytania

Teraz najciekawsza część: zdefiniujmy zapytania, których potrzebujesz w aplikacji. Jako programista jesteś przyzwyczajony do pisania zapytań SQL, a nie zapytań GraphQL, więc na początku może to być nieco dziwne.

Jednak GraphQL jest znacznie bardziej zwięzły i bezpieczny pod względem typów niż zwykły SQL. Nasz dodatek do VS Code ułatwia programowanie.

Zacznij edytować plik /dataconnect/connector/queries.gql. Jeśli chcesz uzyskać wszystkie filmy, użyj takiego zapytania.

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

Wykonaj zapytanie za pomocą przycisku CodeLens.

Naprawdę interesującą funkcją jest możliwość traktowania relacji w bazie danych jak grafu. Rekord MovieMetadata zawiera pole movie, które odwołuje się do filmu, więc możesz zagnieżdżając to pole, uzyskać informacje o filmie. Spróbuj dodać wygenerowany typ movieMetadata_on_movie do zapytania ListMovies.

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

Więcej informacji o zapytaniach Data Connect znajdziesz w dokumentacji

Generowanie pakietów SDK i używanie ich w aplikacji

W panelu po lewej stronie w IDE kliknij ikonę Firebase, aby otworzyć interfejs rozszerzenia Data Connect w VS Code:

  1. Kliknij przycisk Dodaj pakiet SDK do aplikacji.

  2. W wyświetlonym oknie wybierz katalog zawierający kod aplikacji. Data Connect Kod pakietu SDK zostanie wygenerowany i tam zapisany.

  3. Wybierz platformę aplikacji, a potem zwróć uwagę, że kod SDK zostanie natychmiast wygenerowany w wybranym katalogu.

Używanie pakietów SDK do wywoływania zapytania z aplikacji

Aby zaimplementować wywołanie zapytania ListMovies, możesz użyć pakietu SDK wygenerowanego przez Data Connect. Następnie możesz wykonać to zapytanie lokalnie za pomocą emulatora Data Connect.

Sieć

  1. Dodaj Firebase do aplikacji internetowej.

  2. W pliku głównym aplikacji React:

    • zaimportować wygenerowany pakiet SDK;
    • zaimplementować w aplikacji możliwość łączenia się z emulatorem Data Connect.
    • wywołać metody Data Connect.

    Możesz skopiować ten fragment kodu i uruchomić go jako samodzielną aplikację.

    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. Dodaj Firebase do aplikacji na iOS.

  2. Aby używać wygenerowanego pakietu SDK, skonfiguruj go jako zależność w Xcode.

    Na górnym pasku nawigacyjnym Xcode wybierz Plik > Dodaj zależności pakietu > Dodaj lokalnie i wskaż folder zawierający wygenerowany plik Package.swift.

  3. W głównym delegacie aplikacji:

    • zaimportować wygenerowany pakiet SDK;
    • zaimplementować w aplikacji możliwość łączenia się z emulatorem Data Connect.
    • wywołać metody Data Connect.

    Możesz skopiować ten fragment kodu i uruchomić go jako samodzielną aplikację.

    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 na Androidzie

  1. Dodaj Firebase do aplikacji na Androida.

  2. Aby używać wygenerowanego pakietu SDK, skonfiguruj pakiet Data Connect jako zależność w Gradle.

    Zaktualizuj wartości plugins i dependencies w konfiguracji 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. W głównym działaniu aplikacji:

    • zaimportować wygenerowany pakiet SDK;
    • zaimplementować w aplikacji możliwość łączenia się z emulatorem Data Connect.
    • wywołać metody Data Connect.

    Możesz skopiować ten fragment kodu i uruchomić go jako samodzielną aplikację.

    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. Dodaj Firebase do aplikacji Flutter.
  2. Zainstaluj interfejs wiersza poleceń flutterfire dart pub global activate flutterfire_cli.
  3. Uruchom flutterfire configure.

  4. W głównej funkcji aplikacji:

    • zaimportować wygenerowany pakiet SDK;
    • zaimplementować w aplikacji możliwość łączenia się z emulatorem Data Connect.
    • wywołać metody Data Connect.

    Możesz skopiować ten fragment kodu i uruchomić go jako samodzielną aplikację.

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();
            }),
      )
    ])));
  }
}

Wdrażanie schematu i zapytania do wersji produkcyjnej

Po skonfigurowaniu aplikacji lokalnie możesz wdrożyć w chmurze schemat, dane i zapytania. Aby skonfigurować instancję Cloud SQL, musisz mieć projekt w abonamencie Blaze.

  1. Otwórz sekcję Data Connect w konsoli Firebase i utwórz bezpłatną wersję próbną instancji Cloud SQL.

  2. W zintegrowanym z IDE terminalu uruchom firebase init dataconnect i wybierz Region/identyfikator usługi, który został utworzony na konsoli.

  3. Gdy pojawi się komunikat "Plik dataconnect/dataconnect.yaml już istnieje, czy chcesz go zastąpić?", wybierz "Y".

  4. W oknie IDE w interfejsie rozszerzenia VS Code kliknij przycisk Wdróż w środowisku produkcyjnym.

  5. Po wdrożeniu przejdź do konsoli Firebase, aby sprawdzić, czy schemat, operacje i dane zostały przesłane do chmury. W konsoli powinieneś mieć możliwość wyświetlania schematu i wykonywania operacji. Instancja Cloud SQL for PostgreSQL zostanie zaktualizowana o ostateczny wdrożony schemat i dane.

Dalsze kroki

Sprawdź wdrożony projekt i odkryj więcej narzędzi:

  • Dodawaj dane do bazy danych, sprawdzaj i modyfikuj schematy oraz monitoruj usługę Data Connect w konsoli Firebase.

Więcej informacji znajdziesz w dokumentacji. Na przykład po ukończeniu krótkiego wprowadzenia: