این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

این آموزش سریع به شما کمک می‌کند تا با Firebase Data Connect آشنا شوید و برنامه‌های وب و موبایل خود را به پایگاه داده PostgreSQL متصل کنید. شما:

دایرکتوری پروژه محلی Firebase Data Connect خود را با VS Code و Firebase CLI تنظیم کنید.
طرحواره‌ها، کوئری‌ها و جهش‌های Data Connect را بر اساس ایده‌های برنامه خود به زبان طبیعی تولید کنید.
از SDK های Strongly-typed در برنامه‌های خود برای اجرای کوئری‌ها و جهش‌های Data Connect استفاده کنید.
ارائه یک نمونه Cloud SQL برای PostgreSQL، یک طرح Data Connect، پرس‌وجوها و جهش‌ها (نیاز به یک طرح Blaze دارد).

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

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

در دایرکتوری پروژه، دستور زیر را اجرا کنید.
این اسکریپت رابط خط فرمان فایربیس و افزونه Data Connect VS Code را نصب می‌کند و شما را در راه‌اندازی پروژه‌تان با استفاده از firebase init dataconnect راهنمایی می‌کند. اگر VS Code دسکتاپ را نصب نکرده‌اید، اسکریپت آن را در مرورگر باز می‌کند.
```
curl -sL https://firebase.tools/init/dataconnect | editor=true bash
```
با کلیک روی آیکون Firebase در پنل سمت چپ Visual Studio Code، صفحه افزونه Data Connect VS Code را باز کنید.
برای اجرای شبیه‌ساز با پایگاه داده محلی PGlite، روی «شروع شبیه‌سازها» کلیک کنید.

طرحواره بررسی

Firebase Data Connect از GraphQL برای تعریف مدل داده شما استفاده می‌کند. دستورالعمل @table یک نوع GraphQL را به یک جدول PostgreSQL نگاشت می‌کند. فیلدهای موجود در این نوع، ستون‌های PostgreSQL را نگاشت می‌کنند. می‌توانید با استفاده از فیلدهایی که به انواع دیگر @table ارجاع می‌دهند، روابط بین جداول را تعریف کنید، از جمله روابط چند به چند با استفاده از جداول join با کلیدهای اصلی مرکب.

در تنظیمات پیش‌فرض، می‌توانید فایل‌های طرحواره Data Connect را در دایرکتوری dataconnect/schema/ پیدا کنید. در اینجا دو جدول نمونه از طرحواره الگوی فیلم آورده شده است. اگر از Gemini برای تولید آن استفاده کرده‌اید، طرحواره شما ممکن است متفاوت باشد.

type Movie @table {
  # Every table has an implicit primary key field that looks something like:
  #  id: UUID! @default(expr: "uuidV4()")
  title: String!
  imageUrl: String!
  genre: String
}

type Review @table(key: ["movie", "user"]) {
  user: User!
  movie: Movie!
  rating: Int
  reviewText: String
  reviewDate: Date! @default(expr: "request.time")
}

درباره طرحواره‌های اتصال داده بیشتر بدانید

توسعه کوئری‌ها و جهش‌ها

Firebase Data Connect از GraphQL برای کوئری‌ها و جهش‌ها استفاده می‌کند. شما این موارد را در فایل‌های .gql تعریف می‌کنید و آنها را با نام از برنامه خود فراخوانی می‌کنید. سینتکس GraphQL، SDKهای نوع‌گذاری شده قوی و یک API انعطاف‌پذیر را برای دریافت داده‌های دقیق مورد نیاز برنامه شما فراهم می‌کند.

داده‌های اولیه در پایگاه داده شما

با اجرای شبیه‌ساز، می‌توانید آن را با داده‌های اولیه بارگذاری کنید. می‌توانید از فایل dataconnect/seed_data.gql ارائه شده استفاده کنید یا جهش‌های خودتان را بنویسید.

از دکمه‌ی Run (local) Code Lens در VS Code برای اجرای جهش‌ها و پر کردن پایگاه داده‌ی محلی PGlite خود استفاده کنید.

دکمه اجرای CodeLens برای داده‌های Firebase اتصال

بررسی کوئری‌ها و جهش‌ها

در تنظیمات پیش‌فرض، می‌توانید کوئری‌ها و جهش‌های Data Connect را در دایرکتوری dataconnect/example/ پیدا کنید.

شما می‌توانید داده‌های رابطه‌ای را با استفاده از کوئری‌های تو در تو (nested query) به طور دقیق جستجو کنید.

query ListMovies @auth(level: PUBLIC, insecureReason: "Anyone can list all movies and their reviews.") {
  movies {
    title imageUrl genre
    reviews_on_movie {
      rating reviewDate
      user { username }
    }
  }
}

Data Connect به شما کمک می‌کند تا با Firebase Auth، کوئری‌ها و جهش‌های امن بسازید.

برای ایمن نگه داشتن برنامه شما، برنامه‌های وب و موبایل فقط می‌توانند با استفاده از دستورالعمل‌های @auth به کوئری‌ها و جهش‌های Data Connect دسترسی داشته باشند. کوئری‌ها و جهش‌ها می‌توانند با استفاده از عبارتی مانند {field}_expr: "auth.uid" به طور ایمن به Firebase Auth UID دسترسی پیدا کنند.

mutation AddReview($movieId: UUID!, $rating: Int!, $reviewText: String!) @auth(level: USER) {
  review_upsert(
    data: {
      userId_expr: "auth.uid"
      movieId: $movieId
      rating: $rating
      reviewText: $reviewText
    }
  )
}

درباره کوئری‌های Data Connect بیشتر بدانید درباره جهش‌های Data Connect بیشتر بدانید درباره Data Connect Auth بیشتر بدانید

ایجاد پرس‌وجوها و جهش‌ها

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

در هر فایل .gql ، برای شروع یک کامنت و توصیف یک پرس‌وجو یا جهش # را تایپ کنید. سپس، از دکمه Generate/Refine Operation Code Lens برای تولید عملیات GraphQL استفاده کنید.

دکمه تولید CodeLens برای داده‌های Firebase اتصال

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

firebase init dataconnect به طور خودکار SDK های type-safe را برای برنامه‌های پروژه شما تنظیم می‌کند. در صورت نیاز، می‌توانید SDK را به صورت دستی با دکمه Add SDK to app در افزونه VS Code یا با اجرای firebase init dataconnect:sdk اضافه کنید.

وب

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

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

SDK تولید شده خود را وارد کنید:

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

برنامه خود را برای اتصال به شبیه‌ساز Data Connect آماده کنید:

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

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

متدهای Data Connect فراخوانی کنید.

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

سویفت

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

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

SDK Data Connect و SDK تولید شده خود را وارد کنید:

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

let connector = DataConnect.moviesConnector

برنامه خود را برای اتصال به شبیه‌ساز Data Connect آماده کنید:

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

متدهای Data Connect فراخوانی:

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

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

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

برای استفاده از 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")
}

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

یک نمونه کانکتور از SDK تولید شده خود دریافت کنید:

private val connector = com.myapplication.MoviesConnector.instance

برنامه خود را برای اتصال به شبیه‌ساز Data Connect آماده کنید:

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

متدهای Data Connect فراخوانی کنید.

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

فلوتر

فایربیس را به برنامه فلاتر خود اضافه کنید.
dart pub global activate flutterfire_cli برای خط فرمان flutterfire نصب کنید.
flutterfire configure اجرا کنید.

در تابع اصلی برنامه شما:

SDK تولید شده خود را وارد کنید:

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

import 'movies_connector/movies.dart';

برنامه خود را برای اتصال به شبیه‌ساز Data Connect آماده کنید:

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

متدهای Data Connect فراخوانی کنید.

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

استقرار در محیط تولید

برای استقرار طرحواره، کوئری‌ها و جهش‌های خود در محیط عملیاتی:

برای استفاده از طرح Blaze، پروژه Firebase را ارتقا دهید.
روی دکمه‌ی Deploy to production در افزونه‌ی Data Connect VS Code کلیک کنید یا آن را در ترمینال اجرا کنید:
```
firebase deploy --only dataconnect
```
پس از استقرار، برای مشاهده طرحواره خود و اجرای کوئری‌ها و جهش‌ها، به کنسول Firebase مراجعه کنید.
نکته: می‌توانید قبل از استقرار، منطقه Cloud SQL، نام نمونه و نام پایگاه داده PostgreSQL را در dataconnect.yaml پیکربندی کنید.
نکته: هر پروژه واجد شرایط دریافت یک نسخه آزمایشی رایگان ۳ ماهه Cloud SQL است. به محدودیت‌های آن مراجعه کنید.

درباره dataconnect.yaml بیشتر بدانید درباره نحوه کار Data Connect با Cloud SQL بیشتر بدانید

مراحل بعدی

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

با دنبال کردن codelab برای وب ، codelab برای iOS یا codelab برای اندروید ، یک مخزن برنامه با شروع سریع را کاوش کنید و یک برنامه Data Connect با امکانات کامل بسازید.
داده‌ها را به پایگاه داده خود اضافه کنید، طرحواره‌های خود را بررسی کنید و سرویس Data Connect خود را در کنسول Firebase نظارت کنید.
سرور Firebase MCP را با ابزارهای توسعه مبتنی بر هوش مصنوعی مانند Gemini Code Assist راه‌اندازی کنید.
درباره توسعه طرحواره ، پرس‌وجو و جهش بیشتر بدانید.
درباره نحوه مدیریت طرحواره PostgreSQL Data Connect بیشتر بدانید.
درباره SDK های کلاینت برای وب ، اندروید ، iOS و Flutter و همچنین SDK های ادمین برای Node.js بیشتر بدانید.