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

در این شروع سریع، یاد خواهید گرفت که چگونه Firebase Data Connect در برنامه خود با یک نمونه تولیدی SQL ایجاد کنید.

در کنسول Firebase شما:

  • Firebase Data Connect به پروژه Firebase خود اضافه کنید.
  • با استفاده از Schema Assist یک طرح برای یک برنامه در کنسول Firebase ایجاد کنید و آن را اجرا کنید.
  • یک نمونه Cloud SQL برای برنامه خود تهیه کنید.
  • با Gemini Code Assist ، پایگاه داده خود را با داده های نمونه پر کنید.

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

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

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

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

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

  7. Create a new Cloud SQL instance را انتخاب کنید. در گفتگوی ظاهر شده، یک مکان و نامگذاری برای پایگاه داده Cloud SQL برای PostgreSQL خود انتخاب کنید.

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

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

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

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

  1. تب Data را باز کنید.

  2. روی نماد Help me write GraphQL pen_spark کلیک کنید و در کادری که ظاهر می‌شود، ورودی خود را تایپ کنید.

    به عنوان مثال:

    Add data for three sample products to my app.

  3. روی Generate کلیک کنید. جهش برگردانده شده است.

  4. خروجی را مرور کنید. در صورت نیاز، روی Edit کلیک کنید تا درخواست اصلاح شود و روی Regenerate کلیک کنید.

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

  6. روی Run کلیک کنید.

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

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

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

    به عنوان مثال:

    Query data for all sample products in my app.

  3. روی Generate و سپس Run کلیک کنید.

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

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

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

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

  1. یک دایرکتوری جدید برای پروژه محلی خود ایجاد کنید.

  2. دستور زیر را در دایرکتوری جدیدی که ایجاد کردید اجرا کنید.

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

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

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

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

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

  1. روی دکمه Sign in with Google کلیک کنید.
  2. روی دکمه Connect a Firebase project کلیک کنید و پروژه ای را که قبلا در کنسول ایجاد کردید انتخاب کنید.

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

  4. روی دکمه Start emulators کلیک کنید.

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

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

طرح خود را پیدا کنید: در فهرست پروژه Firebase شما، در فایل /dataconnect/schema/schema.gql قرار دارد.

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

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

در 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
}

جدول طرحواره 1:1: 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 ، روی دکمه افزودن داده در بالای اعلامیه برای یکی از انواع خود (مثل Movie ، Product ، Account ، بسته به ماهیت برنامه) کلیک کنید.
    لنز کد دکمه افزودن داده برای Firebase Data Connect
  2. یک فایل جدید، <type>_insert.qgl ، به فهرست کاری شما، مانند Movie_insert.gql یا Product_insert.gql اضافه می شود. داده های کد سخت در فیلدهای مربوط به آن نوع.
  3. روی دکمه Run (Production) کلیک کنید.
    دکمه اجرای کد لنز برای اتصال داده Firebase
  4. برای افزودن رکورد به جداول دیگر مراحل قبلی را تکرار کنید.

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

  1. به schema.gql برگردید، روی دکمه Read data بالای اعلان نوع کلیک کنید.
  2. در فایل <type>_read.gql ایجاد شده، مانند Product_read.gql ، روی دکمه Run (Production) کلیک کنید تا کوئری اجرا شود.

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

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

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

برای پیاده سازی یک پرس و جو، می توانید یکی را که با CodeLens ما ایجاد شده است، تطبیق دهید:

  1. در /dataconnect/schema/schema.gql ، بالای یک نوع ( Movie ، Product ، Account ، و غیره)، روی دکمه Read data CodeLens کلیک کنید.
  2. در فایل <type>_read.gql به دست آمده، پرس و جو را با کلیک کردن روی دکمه Run (Production) تست کنید.
  3. کوئری عملکردی را در /dataconnect/connector/queries.gql کپی کنید.

  4. برای اینکه این کوئری قابل اجرا باشد، یک نام منحصر به فرد برای آن اعلام کنید.

    برای مثال، در مثال عمومی زیر، query_name ممکن است ListMovies یا ListProducts یا ListAccounts باشد. 

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

# @auth() directives control who can call each operation.
query <query_name> @auth(level: PUBLIC) {
   <table_name> {
     <field_1>
     <field_2>
     <field_3>
  }
}

پرس و جو را با استفاده از دکمه CodeLens نزدیک اجرا کنید.

درباره پرسش‌های Data Connect در مستندات بیشتر بیاموزید

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

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

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

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

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

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

در پنجره IDE، در VS Code Extension UI، روی دکمه Deploy to production کلیک کنید.

پس از استقرار، به کنسول Firebase بروید تا تأیید کنید که به‌روزرسانی‌های طرحواره (در صورت وجود) و آپلود شدن عملیات در فضای ابری انجام شده است. شما باید بتوانید طرحواره را مشاهده کنید و عملیات خود را روی کنسول نیز اجرا کنید. Cloud SQL برای نمونه PostgreSQL با طرح و داده های تولید شده نهایی مستقر شده خود به روز می شود.

درباره استفاده از شبیه ساز Data Connect در مستندات بیشتر بیاموزید

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

اکنون که طرحواره به روز شده شما (در صورت وجود). و درخواست شما برای تولید مستقر می شود، می توانید از SDK که Data Connect ایجاد کرده است برای اجرای فراخوانی به درخواست ListMovies خود استفاده کنید.

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

  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 '@movie-app/movies';

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. Firebase را به برنامه 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. Firebase را به برنامه اندروید خود اضافه کنید.

  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. Firebase را به برنامه Flutter خود اضافه کنید.
  2. flutterfire CLI dart pub global activate flutterfire_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 نظارت کنید.

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