با Firebase Data Connect به صورت محلی شروع کنید، با Firebase Data Connect به صورت محلی شروع کنید

در این آموزش سریع، یاد خواهید گرفت که چگونه Firebase Data Connect در برنامه خود به صورت محلی و بدون تنظیم یک نمونه SQL در محیط عملیاتی بسازید. شما:

  • Firebase Data Connect به پروژه فایربیس خود اضافه کنید.
  • یک محیط توسعه شامل افزونه‌های ویژوال استودیو کد برای کار با یک نمونه محلی راه‌اندازی کنید.
  • سپس به شما نشان خواهیم داد که چگونه:
    • از ابزار افزونه VS Code به همراه Gemini Code Assist برای موارد زیر استفاده کنید:
      • ایجاد یک طرحواره برای یک برنامه
      • ایجاد کوئری‌های مدیریتی و جهش‌ها برای پر کردن پایگاه داده محلی شما
      • به شما کمک می‌کند تا کوئری‌ها و جهش‌ها را برای برنامه خود در یک کانکتور قابل استقرار پیاده‌سازی کنید.
    • کوئری‌ها و جهش‌های خود را با داده‌های نمونه در برابر یک شبیه‌ساز محلی آزمایش کنید
    • SDK های با نوع داده Strongly تولید کنید و از آنها در برنامه خود استفاده کنید.
    • طرحواره و رابط نهایی خود را به فضای ابری (اختیاری، با ارتقاء طرح Blaze) مستقر کنید .

یک جریان توسعه محلی انتخاب کنید

Data Connect دو روش برای نصب ابزارهای توسعه و کار به صورت محلی ارائه می‌دهد.

پیش‌نیازها

برای استفاده از این راهنمای سریع، به موارد زیر نیاز دارید.

محیط توسعه را تنظیم کنید

  1. یک دایرکتوری جدید برای پروژه محلی خود ایجاد کنید.
  2. VS Code را در دایرکتوری جدید باز کنید.
  3. افزونه‌ی Firebase Data Connect را از Visual Studio Code Marketplace نصب کنید.

دایرکتوری پروژه خود را تنظیم کنید

برای راه‌اندازی پروژه محلی خود، دایرکتوری پروژه خود را راه‌اندازی کنید. در پنجره IDE، در پنل سمت چپ، روی آیکون Firebase کلیک کنید تا رابط کاربری افزونه Data Connect VS Code باز شود:

  1. روی دکمه ورود با گوگل کلیک کنید.
  2. روی دکمه‌ی «اتصال به پروژه‌ی فایربیس» کلیک کنید و پروژه‌ای را که قبلاً در کنسول ایجاد کرده‌اید، انتخاب کنید.
  3. روی دکمه‌ی اجرای آغازگر فایربیس کلیک کنید.

  4. روی دکمه‌ی شروع شبیه‌سازها کلیک کنید.

ایجاد یک طرحواره

در دایرکتوری پروژه Firebase خود، در فایل /dataconnect/schema/schema.gql ، شروع به تعریف یک طرحواره GraphQL در مورد، مثلاً نقد فیلم، کنید.

برای ساخت یک طرحواره از Gemini Code Assist استفاده کنید

برای ایجاد یک طرحواره برنامه نقد فیلم با استفاده از Gemini Code Assist :

  1. روی آیکون افزونه‌ی Data Connect VS Code کلیک کنید تا نوار کناری آن باز شود.
  2. روی «ساخت طرحواره و پرس‌وجوهای خود با هوش مصنوعی» کلیک کنید. پنجره چت Gemini Code Assist باز می‌شود.
  3. در پایین پنجره چت، مطمئن شوید که حالت Agent فعال است.
  4. روی کادر چت در پایین پنجره چت کلیک کنید و شروع به تایپ توضیحی به زبان طبیعی در مورد نوع اپلیکیشنی که می‌سازید، کنید.
  5. اینتر را بزنید و Gemini دستور سرور MCP را که برای شروع توسعه طرحواره اجرا می‌شود، نمایش می‌دهد.
  6. روی پذیرش کلیک کنید. پس از چند لحظه، یک طرح پیشنهادی ظاهر می‌شود. طرح را بررسی کنید.

  7. برای افزودن کد به schema.gql :

    1. منتظر بمانید تا Gemini Code Assist از شما بخواهد که فایل را به‌روزرسانی کنید.
    2. برای تغییر فایل، روی «پذیرش» کلیک کنید، یا قبل از ثبت، روی «مشاهده تغییرات» کلیک کنید.

فیلم

در Data Connect ، فیلدهای GraphQL به ستون‌ها نگاشت می‌شوند. Movie دارای id ، title ، imageUrl و genre است. Data Connect انواع داده‌های اولیه مانند String و UUID را تشخیص می‌دهد.

قطعه کد زیر را کپی کنید یا خطوط مربوطه را در فایل از حالت کامنت خارج کنید.

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

فراداده فیلم

ممکن است تعریف نوعی مانند زیر را ببینید. یا می‌توانید قطعه کد زیر را کپی کنید یا خطوط مربوطه را در فایل پیش‌فرض از حالت کامنت خارج کنید.

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

توجه داشته باشید که فیلد movie به نوعی از Movie نگاشت شده است. Data Connect متوجه می‌شود که این یک رابطه بین Movie و MovieMetadata است و این رابطه را برای شما مدیریت خواهد کرد.

برای کسب اطلاعات بیشتر در مورد طرحواره‌های Data Connect به مستندات مراجعه کنید.

داده ها را به جداول خود اضافه کنید

در پنل ویرایشگر IDE، دکمه‌های CodeLens را خواهید دید که روی انواع GraphQL در /dataconnect/schema/schema.gql ظاهر می‌شوند. می‌توانید از دکمه‌های Add data و Run (Local) برای اضافه کردن داده‌ها به پایگاه داده محلی خود استفاده کنید.

برای افزودن رکورد به جداول Movie و MovieMetadata :

  1. در schema.gql ، روی دکمه‌ی «افزودن داده» (Add data) در بالای تعریف نوع Movie type) کلیک کنید.
    دکمه افزودن داده در CodeLens برای اتصال داده Firebase
  2. در فایل Movie_insert.gql که تولید می‌شود، داده‌های مربوط به سه فیلد به صورت کد سخت (hard code) قرار می‌گیرند.
  3. روی دکمه اجرا (محلی) کلیک کنید.
    دکمه اجرای CodeLens برای اتصال داده Firebase
  4. مراحل قبلی را برای اضافه کردن یک رکورد به جدول MovieMetadata تکرار کنید و id فیلم خود را در فیلد movieId وارد کنید، همانطور که در جهش MovieMetadata_insert تولید شده از شما خواسته شده است.

برای تأیید سریع داده‌ها اضافه شد:

  1. به schema.gql برگردید، روی دکمه‌ی «خواندن داده» (Read data) در بالای اعلان نوع Movie (Movie type) کلیک کنید.
  2. در فایل Movie_read.gql حاصل، روی دکمه‌ی Run (Local) کلیک کنید تا کوئری اجرا شود.

درباره جهش‌های Data Connect در مستندات بیشتر بدانید

تعریف یک پرس و جو

حالا برای سرگرمی بیشتر: کوئری‌هایی که در برنامه‌تان نیاز دارید را تعریف کنید. به عنوان یک توسعه‌دهنده، شما به نوشتن کوئری‌های SQL به جای کوئری‌های GraphQL عادت دارید، بنابراین این می‌تواند در ابتدا کمی متفاوت به نظر برسد.

با این حال، GraphQL بسیار مختصرتر و از نظر نوع داده ایمن‌تر از SQL خام است. و افزونه VS Code ما، تجربه توسعه را هم برای کوئری‌ها و هم برای جهش‌ها آسان‌تر می‌کند.

برای ایجاد یک پرس و جو با استفاده از Gemini Code Assist :

  1. روی آیکون افزونه‌ی Data Connect VS Code کلیک کنید تا نوار کناری آن باز شود.
  2. روی «ساخت طرحواره و پرس‌وجوهای خود با هوش مصنوعی» کلیک کنید. پنجره چت Gemini Code Assist باز می‌شود.
  3. در پایین پنجره چت، مطمئن شوید که حالت Agent فعال است.
  4. روی کادر چت در پایین پنجره چت کلیک کنید و شروع به تایپ توضیحی به زبان طبیعی در مورد نوع عملیاتی که می‌خواهید توسعه دهید، کنید.
  5. اینتر را بزنید، و Gemini دستور سرور MCP را که برای شروع توسعه عملیات اجرا خواهد کرد، نمایش می‌دهد.
  6. روی پذیرش کلیک کنید. پس از چند لحظه، یک پرسش پیشنهادی ظاهر می‌شود. پرسش را مرور کنید.

  7. برای اضافه کردن کد به queries.gql :

    1. منتظر بمانید تا Gemini Code Assist از شما بخواهد که فایل را به‌روزرسانی کنید.
    2. برای تغییر فایل، روی «پذیرش» کلیک کنید، یا قبل از ثبت، روی «مشاهده تغییرات» کلیک کنید.

با استفاده از دکمه CodeLens که در نزدیکی آن قرار دارد، کوئری را اجرا کنید.

برای کسب اطلاعات بیشتر در مورد کوئری‌های Data Connect به مستندات مراجعه کنید.

SDK ها را تولید کنید و از آنها در برنامه خود استفاده کنید

در پنل سمت چپ IDE، روی آیکون Firebase کلیک کنید تا رابط کاربری افزونه Data Connect VS Code باز شود:

  1. روی دکمه‌ی «افزودن SDK به برنامه» کلیک کنید.

  2. در پنجره‌ای که ظاهر می‌شود، پوشه‌ای که حاوی کد برنامه شماست را انتخاب کنید. کد Data Connect SDK در آنجا تولید و ذخیره خواهد شد.

  3. پلتفرم برنامه خود را انتخاب کنید، سپس توجه داشته باشید که کد SDK بلافاصله در دایرکتوری انتخابی شما تولید می‌شود.

از SDK ها برای فراخوانی کوئری خود از یک برنامه استفاده کنید

شما می‌توانید از SDK تولید شده توسط Data Connect برای پیاده‌سازی فراخوانی کوئری ListMovies خود استفاده کنید. سپس می‌توانید این کوئری را به صورت محلی با استفاده از شبیه‌ساز Data Connect اجرا کنید.

وب

  1. فایربیس را به برنامه وب خود اضافه کنید.

  2. در فایل اصلی برنامه React شما:

    • SDK تولید شده خود را وارد کنید
    • برنامه خود را برای اتصال به شبیه‌ساز Data Connect آماده کنید
    • فراخوانی متدهای Data Connect .
    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 '@dataconnect/generated';

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 />);

سویفت

  1. فایربیس را به برنامه iOS خود اضافه کنید.

  2. برای استفاده از SDK تولید شده، آن را به عنوان یک وابستگی در Xcode پیکربندی کنید.

    در نوار ناوبری بالای Xcode، مسیر File > Add Package Dependencies > Add Local را انتخاب کنید و پوشه‌ای که فایل Package.swift تولید شده در آن قرار دارد را انتخاب کنید.

  3. در نماینده اصلی برنامه شما:

    • SDK تولید شده خود را وارد کنید
    • برنامه خود را برای اتصال به شبیه‌ساز Data Connect آماده کنید
    • فراخوانی متدهای Data Connect . 
    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 ?? []) { movie in
                    Text(movie.title)
                }
            }
    }
    @MainActor
    func refresh() async throws {
        _ = try await queryRef.execute()
    }

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

کاتلین اندروید

  1. فایربیس را به برنامه اندروید خود اضافه کنید.

  2. برای استفاده از SDK تولید شده، Data Connect به عنوان یک وابستگی در Gradle پیکربندی کنید.

    plugins و dependencies را در app/build.gradle.kts خود به‌روزرسانی کنید.

    plugins {
  // Use whichever versions of these dependencies suit your application.
  // The versions shown here were the latest as of March 14, 2025.
  // Note, however, that the version of kotlin("plugin.serialization") must,
  // in general, match the version of kotlin("android").
  id("com.android.application") version "8.9.0"
  id("com.google.gms.google-services") version "4.4.2"
  val kotlinVersion = "2.1.10"
  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 March 14, 2025.
  implementation("com.google.firebase:firebase-dataconnect:16.0.0-beta04")
  implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.1")
  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.10.1")
  implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.8.7")
  implementation("com.google.android.material:material:1.12.0")
}

  3. در اکتیویتی اصلی برنامه شما:

    • SDK تولید شده خود را وارد کنید
    • برنامه خود را برای اتصال به شبیه‌ساز Data Connect آماده کنید
    • فراخوانی متدهای Data Connect . 
    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
      }
    }
  }
}

فلوتر

  1. فایربیس را به برنامه فلاتر خود اضافه کنید.
  2. dart pub global activate flutterfire_cli برای خط فرمان flutterfire نصب کنید.
  3. flutterfire configure اجرا کنید.
  4. در تابع اصلی برنامه شما:
    • SDK تولید شده خود را وارد کنید
    • برنامه خود را برای اتصال به شبیه‌ساز Data Connect آماده کنید
    • فراخوانی متدهای Data Connect . 
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();
            }),
      )
    ])));
  }
}

طرحواره و پرس و جوی خود را به محیط تولید منتقل کنید

پس از اینکه تنظیمات محلی برنامه خود را انجام دادید، می‌توانید طرحواره و کانکتور خود را در فضای ابری مستقر کنید. برای راه‌اندازی یک نمونه Cloud SQL به یک پروژه Blaze plan نیاز دارید.

  1. به بخش Data Connect در کنسول Firebase بروید و یک نمونه آزمایشی رایگان Cloud SQL ایجاد کنید.
  2. در ترمینال یکپارچه IDE، firebase init dataconnect را اجرا کنید و شناسه منطقه/سرویسی که اخیراً در کنسول ایجاد کرده‌اید را انتخاب کنید.
  3. وقتی از شما پرسیده شد «فایل dataconnect/dataconnect.yaml از قبل وجود دارد، بازنویسی شود؟»، «Y» را انتخاب کنید.
  4. در پنجره‌ی IDE، در رابط کاربری افزونه‌ی VS Code، روی دکمه‌ی Deploy to production کلیک کنید.
  5. پس از استقرار، به کنسول Firebase بروید تا تأیید کنید که طرحواره، عملیات و داده‌ها در ابر بارگذاری شده‌اند. شما باید بتوانید طرحواره را مشاهده کنید و عملیات خود را نیز روی کنسول اجرا کنید. نمونه Cloud SQL برای PostgreSQL با طرحواره و داده‌های نهایی تولید شده مستقر شده خود به‌روزرسانی خواهد شد.

مراحل بعدی

پروژه مستقر شده خود را بررسی کنید و ابزارهای بیشتری را کشف کنید:

  • داده‌ها را به پایگاه داده خود اضافه کنید، طرحواره‌های خود را بررسی و اصلاح کنید و سرویس Data Connect خود را در کنسول Firebase نظارت کنید.

برای اطلاعات بیشتر به مستندات مراجعه کنید. برای مثال، از آنجایی که شروع سریع را تکمیل کرده‌اید: