با Firebase Data Connect شروع کنید

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

در کنسول Firebase شما موارد زیر را انجام خواهید داد:

  • Firebase Data Connect به پروژه فایربیس خود اضافه کنید.
  • با استفاده از تولید طرحواره با کمک هوش مصنوعی در کنسول Firebase ، یک طرحواره برای یک برنامه ایجاد کنید و آن را مستقر کنید.
  • یک نمونه Cloud SQL برای برنامه خود تهیه کنید.
  • با استفاده از Gemini در Firebase ، پایگاه داده خود را با داده‌های نمونه پر کنید.
  • با تولید عملیات به کمک هوش مصنوعی، کوئری‌ها و جهش‌ها را ایجاد کنید که می‌توانید آنها را مستقر کرده و برای توسعه کد کلاینت به صورت محلی استفاده کنید.

سپس، در محیط توسعه محلی خود، موارد زیر را انجام خواهید داد:

  • یک ابزار توسعه شامل افزونه‌ی Visual Studio Code برای کار با نمونه‌ی نهایی خود تنظیم کنید.
  • محیط محلی خود را با دارایی‌هایی که در کنسول ایجاد کرده‌اید، همگام‌سازی کنید.
  • SDK های با نوع داده Strongly Typed تولید کنید و از آنها در برنامه خود استفاده کنید.

جریان کنسول: از کمک هوش مصنوعی برای طراحی طرحواره خود استفاده کنید، سپس آن را در پایگاه داده خود مستقر کنید

  1. اگر هنوز این کار را نکرده‌اید، یک پروژه Firebase ایجاد کنید.
    1. در کنسول Firebase ، روی Add project کلیک کنید، سپس دستورالعمل‌های روی صفحه را دنبال کنید.
  2. به بخش Data Connect در کنسول Firebase بروید.
  3. روی دکمه‌ی «شروع با جمینی» کلیک کنید.
  4. در پنل گردش کار Schema Generator که ظاهر می‌شود، یک برنامه را توصیف کنید تا Gemini بتواند در ایجاد یک طرحواره GraphQL با شما کمک کند.
  5. طرح GraphQL را مرور کنید، سپس روی Upgrade and deploy کلیک کنید.

  6. پروژه خود را به طرح Blaze ارتقا دهید. این به شما امکان می‌دهد یک نمونه Cloud SQL برای PostgreSQL ایجاد کنید.

  7. گزینه «ایجاد یک نمونه جدید Cloud SQL» را انتخاب کنید. در پنجره‌ای که ظاهر می‌شود، یک مکان و نام برای پایگاه داده Cloud SQL for PostgreSQL خود انتخاب کنید.

    طرحواره برنامه شما به همراه پایگاه داده PostgreSQL مربوط به آن طرحواره مستقر شده است.

جریان کنسول: از کمک هوش مصنوعی برای ایجاد عملیات برای مشتریان خود استفاده کنید

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

ابزارهای کمکی هوش مصنوعی ما اینجا هستند تا به شما کمک کنند.

  1. وقتی از شما خواسته شد، روی دکمه‌ی «ایجاد عملیات با Gemini» کلیک کنید.

  2. پس از چند لحظه، در پنل «ایجاد گردش کار عملیات» که ظاهر می‌شود، لیست پرس‌وجوها و جهش‌های ارائه شده توسط Gemini را بر اساس طرحواره خود مرور کنید.

  3. برای مشاهده کد GraphQL که آن عملیات را تعریف می‌کند، روی هر ردیف عملیات کلیک کنید. در صورت لزوم، از کنترل trashcan برای حذف عملیاتی که نیازی به آنها ندارید استفاده کنید.

  4. برای افزودن عملیات، روی دکمه + Add کلیک کنید. سپس:

    1. عملیات خود را به زبان طبیعی شرح دهید.

      برای مثال:

      List all products

    2. GraphQL تولید شده را بررسی کنید.

    3. اگر عملیات قابل قبول است، روی درج کلیک کنید تا آن را به لیست عملیات خود اضافه کنید.

  5. حذف و اضافه کردن عملیات را تا زمانی که مجموعه عملیات شما قابل قبول شود، ادامه دهید.

  6. برای استقرار این لیست عملیات به عنوان یک مجموعه کانکتور قابل فراخوانی توسط کلاینت، نام کانکتور را انتخاب کنید، سپس روی Deploy کلیک کنید.

جریان کنسول: از Gemini در Firebase برای ایجاد یک جهش و پر کردن پایگاه داده خود استفاده کنید

با تکمیل مراحل قبلی، شما یک طرحواره Data Connect متشکل از انواع موجودیت‌های مرتبط ایجاد کردید و آن را در محیط عملیاتی مستقر کردید، به این معنی که یک پایگاه داده PostgreSQL با جداول مربوطه نیز ایجاد و مستقر شد.

برای پر کردن پایگاه داده خود، می‌توانید از Gemini در Firebase استفاده کنید تا به شما در ایجاد داده‌ها با جهش‌هایی که یک یا چند جدول شما را به‌روزرسانی می‌کنند، کمک کند.

  1. برگه داده را باز کنید.

  2. روی آیکون «به من کمک کن GraphQL بنویسم» (Help me write GraphQL pen_spark) کلیک کنید و روی تراشه داده Seed کلیک کنید.

  3. روی Generate کلیک کنید. جهش‌هایی برای پر کردن داده‌های شما بازگردانده می‌شوند.

  4. خروجی را بررسی کنید. در صورت نیاز، برای اصلاح اعلان، روی ویرایش کلیک کنید و سپس روی بازسازی کلیک کنید.

  5. سپس، روی «درج» کلیک کنید تا جهش در ویرایشگر داده وارد شود.

  6. روی اجرا کلیک کنید.

وقتی جهش‌ها را اجرا می‌کنید، داده‌ها در جدول(های) مربوطه در پایگاه داده PostgreSQL شما نوشته می‌شوند. می‌توانید برای مشاهده داده‌های ذخیره شده، یک کوئری در کنسول ایجاد کنید:

  1. مراحل قبلی را تکرار کنید، و با استفاده از دستور Help me write GraphQL pen_spark یک کوئری ایجاد کنید.

  2. در کادری که ظاهر می‌شود، ورودی خود را تایپ کنید.

    برای مثال:

    Query data for all sample products in my app.

  3. روی «تولید» و سپس «اجرا» کلیک کنید.

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

اکنون که داده‌ها را در پایگاه داده مستقر خود دارید و یک کانکتور نیز مستقر کرده‌اید، می‌توانید توسعه طرحواره و کانکتورهای خود را در محیط توسعه محلی خود ادامه دهید.

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

پیش‌نیازها

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

جریان محلی: راه‌اندازی محیط توسعه

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

جریان محلی: پروژه محلی خود را راه‌اندازی کنید

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

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

  3. روی دکمه‌ی Run firebase init کلیک کنید و مراحل را کامل کنید.

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

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

مرحله‌ی firebase init در بخش قبلی، دارایی‌ها را با محیط توسعه‌ی محلی شما همگام‌سازی می‌کند:
  • طرحواره‌ای که شما مستقر کرده‌اید را همگام‌سازی می‌کند
    • طرحواره خود را پیدا کنید: در دایرکتوری پروژه Firebase شما، در فایل /dataconnect/schema/schema.gql قرار دارد.
  • کوئری‌ها و جهش‌ها را در کانکتوری که مستقر کرده‌اید، همگام‌سازی می‌کند.
    • کانکتور خود را پیدا کنید: عملیات در دایرکتوری پروژه Firebase شما، در دایرکتوری /dataconnect/connector/ قرار دارند.

جریان محلی: طرحواره خود را درک کنید

مثال طرحواره: فیلم

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

# File `/dataconnect/schema/schema.gql`

# By default, a UUID id key will be created by default as primary key.
type Movie @table {
  id: UUID! @default(expr: "uuidV4()")
  title: String!
  imageUrl: String!
  genre: String
}

مثال طرحواره جدول ۱:۱: MovieMetadata

با فیلم‌ها، می‌توانید فراداده‌های فیلم را مدل‌سازی کنید.

برای مثال، در schema.gql ، می‌توانید قطعه کد یا کد بررسی زیر را که توسط Gemini تولید شده است، اضافه کنید.

# 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 ظاهر می‌شوند. درست همانطور که در کنسول انجام دادید، می‌توانید یک جهش برای افزودن داده‌ها به پایگاه داده عملیاتی خود ایجاد کنید.

کار به صورت محلی، برای اضافه کردن داده به یک جدول:

  1. در schema.gql ، روی دکمه‌ی «افزودن داده» (Add data) در بالای اعلان مربوط به یکی از انواع داده‌هایتان (مانند Movie ، Product ، Account ، بسته به ماهیت برنامه‌تان) کلیک کنید.
    دکمه افزودن داده برای اتصال داده فایربیس با Code Lens
  2. یک فایل جدید، <type>_insert.qgl ، به دایرکتوری کاری شما اضافه می‌شود، مانند Movie_insert.gql یا Product_insert.gql . داده‌های کد سخت در فیلدهای مربوط به آن نوع.
  3. روی دکمه اجرا (تولید) کلیک کنید.
    دکمه اجرای Code Lens برای Firebase Data Connect
  4. برای اضافه کردن یک رکورد به جداول دیگر، مراحل قبلی را تکرار کنید.

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

  1. به schema.gql برگردید، روی دکمه‌ی «خواندن داده» (Read data) در بالای اعلان نوع کلیک کنید.
  2. در فایل <type>_read.gql حاصل، مانند Product_read.gql ، برای اجرای پرس‌وجو روی دکمه‌ی Run (Production) کلیک کنید.

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

جریان محلی: تولید SDK

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

اکنون می‌توانید از افزونه‌ی VS Code برای تولید SDKهای کلاینت استفاده کنید تا فراخوانی‌های کوئری‌ها و جهش‌ها را در برنامه‌های iOS، اندروید، وب و Flutter پیاده‌سازی کنید.

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

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

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

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

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

وب

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

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

    • SDK تولید شده خود را وارد کنید
    • فراخوانی متدهای Data Connect .
    import React from 'react';
import ReactDOM from 'react-dom/client';

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

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

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

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 برای خط فرمان (CLI) نصب کنید.
  3. دستور flutterfire configure اجرا کنید.
  4. در تابع اصلی برنامه شما:
    • SDK تولید شده خود را وارد کنید
    • فراخوانی متدهای 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,
  );
  
  
  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();
            }),
      )
    ])));
  }
}

مراحل بعدی

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

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

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