يساعدك هذا الدليل السريع في بدء استخدام Firebase Data Connect لربط تطبيقات الويب والأجهزة الجوّالة بقاعدة بيانات PostgreSQL. عليك إجراء ما يلي:
- اضبط دليل مشروعك المحلي Firebase Data Connect باستخدام VS Code وFirebase CLI.
- إنشاء مخططات Data Connect وعمليات بحث وتعديل استنادًا إلى أفكار تطبيقاتك باللغة الطبيعية
- استخدِم حِزم SDK ذات الأنواع المحدّدة بدقة في تطبيقاتك لتنفيذ طلبات البحث وعمليات التغيير.Data Connect
- توفير مثيل Cloud SQL for PostgreSQL ومخطط Data Connect والاستعلامات والتعديلات (يتطلّب خطة Blaze)
إعداد دليل المشروع المحلي
يمكنك تثبيت أدوات التطوير المحلية لـ Data Connect بطريقتَين.
في دليل المشروع، نفِّذ الأمر التالي.
يُثبِّت النص البرمجي واجهة سطر الأوامر (CLI) الخاصة بـ Firebase وإضافة Data Connect VS Code، ويرشدك خلال
firebase init dataconnectلإعداد مشروعك. إذا لم يكن تطبيق VS Code مثبّتًا على الكمبيوتر، سيفتح النص البرمجي في المتصفّح.curl -sL https://firebase.tools/init/dataconnect | editor=true bashافتح شاشة إضافة Data Connect في Visual Studio Code من خلال النقر على رمز Firebase في اللوحة اليمنى من Visual Studio Code.
انقر على بدء المحاكيات لتشغيل المحاكي باستخدام قاعدة بيانات PGlite محلية.
مخطط المراجعة
تستخدم Firebase Data Connect GraphQL لتحديد نموذج البيانات. يربط التوجيه
@table نوع GraphQL بجدول PostgreSQL. تربط الحقول في خريطة النوع بأعمدة PostgreSQL. يمكنك تحديد العلاقات بين الجداول باستخدام الحقول التي تشير إلى أنواع @table أخرى، بما في ذلك علاقات متعددة إلى متعددة باستخدام جداول الربط مع المفاتيح الأساسية المركّبة.
في الإعداد التلقائي، يمكنك العثور على ملفات مخطط 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")
}
مزيد من المعلومات عن مخططات Data Connect
تطوير طلبات البحث وعمليات التعديل
تستخدم Firebase Data Connect GraphQL للاستعلامات والتعديلات. يمكنك تحديد هذه العناصر في ملفات .gql واستدعاؤها بالاسم من تطبيقك. يوفّر تركيب GraphQL مجموعات أدوات SDK ذات الأنواع المحدّدة بدقة وواجهة برمجة تطبيقات مرنة لاسترداد البيانات الدقيقة التي يحتاجها تطبيقك.
بيانات أولية في قاعدة البيانات
بعد تشغيل المحاكي، يمكنك إضافة بيانات أولية إليه. يمكنك استخدام ملف dataconnect/seed_data.gql المقدَّم أو كتابة عمليات التحويل الخاصة بك.
استخدِم زر تشغيل (محلي) في Code Lens في VS Code لتنفيذ عمليات التغيير وتعبئة قاعدة بيانات PGlite المحلية.

مراجعة طلبات البحث وعمليات التغيير
في الإعداد التلقائي، يمكنك العثور على طلبات البحث وعمليات التغيير في Data Connect ضمن الدليل dataconnect/example/.
يمكنك الاستعلام عن البيانات العلائقية بدقة باستخدام طلبات البحث المتداخلة.
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 يمكن لطلبات البحث وعمليات التعديل الوصول بشكل آمن إلى معرّف UID في Firebase Auth
باستخدام عبارة مثل {field}_expr: "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
إنشاء طلبات بحث وعمليات تغيير
لست بحاجة إلى أن تكون خبيرًا في GraphQL لاستخدام Data Connect بفعالية. يمكنك إنشاء طلبات بحث وعمليات تغيير من أوصاف باللغة الطبيعية.Data Connect
في أي ملف .gql، اكتب # لبدء تعليق ووصف طلب بحث أو عملية تغيير. بعد ذلك، استخدِم زر إنشاء/تحسين العملية في Code Lens
لإنشاء عملية GraphQL.

استخدام حزمة SDK التي تم إنشاؤها في تطبيقك
تُعدّ firebase init dataconnect تلقائيًا حِزم SDK آمنة الأنواع للتطبيقات في مشروعك. إذا لزم الأمر، يمكنك إضافة حزمة تطوير البرامج (SDK) يدويًا باستخدام الزر إضافة حزمة تطوير البرامج إلى التطبيق في إضافة VS Code أو عن طريق تنفيذ firebase init
dataconnect:sdk.
الويب
- أضِف Firebase إلى تطبيقك على الويب.
في الملف الرئيسي لتطبيق 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 />);
Swift
- أضِف Firebase إلى تطبيق 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() } }
Kotlin على Android
- أضِف Firebase إلى تطبيق Android.
لاستخدام حزمة تطوير البرامج (SDK) التي تم إنشاؤها، عليك ضبط Data Connect كعنصر تابع في Gradle.
تعديل
pluginsوdependenciesفيapp/build.gradle.ktsplugins { // 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 } } } }
Flutter
- أضِف Firebase إلى تطبيق Flutter.
- ثبِّت أداة سطر الأوامر flutterfire
dart pub global activate flutterfire_cli. - نفِّذ الأمر
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(); }), ) ]))); } }
النشر في مرحلة الإنتاج
لنشر المخطط والاستعلامات والتعديلات في مرحلة الإنتاج، اتّبِع الخطوات التالية:
ترقية مشروع Firebase لاستخدام خطة Blaze
انقر على الزر نشر في الإصدار العلني في إضافة Data Connect VS Code أو نفِّذ ما يلي في الوحدة الطرفية:
firebase deploy --only dataconnectبعد النشر، انتقِل إلى وحدة تحكّم Firebase لعرض المخطط وتنفيذ طلبات البحث وعمليات التعديل.
مزيد من المعلومات عن dataconnect.yaml مزيد من المعلومات عن كيفية عمل Data Connect مع Cloud SQL
الخطوات التالية
بعد إكمال دليل البدء السريع، إليك بعض الخطوات التالية:
- يمكنك استكشاف مستودع لتطبيق سريع التشغيل وإنشاء تطبيق Data Connect كامل الميزات باتّباع الدرس التطبيقي حول الترميز للويب أو الدرس التطبيقي حول الترميز لنظام التشغيل iOS أو الدرس التطبيقي حول الترميز لنظام التشغيل Android.
- أضِف بيانات إلى قاعدة البيانات، وافحص المخططات، وراقِب خدمة Data Connect في وحدة تحكّم Firebase.
- إعداد خادم Firebase MCP باستخدام أدوات تطوير مستندة إلى الذكاء الاصطناعي، مثل Gemini Code Assist
- يمكنك الاطّلاع على مزيد من المعلومات حول تطوير المخطط والاستعلام والتعديل.
- Data Connect مزيد من المعلومات حول كيفية إدارة مخطط PostgreSQL
- يمكنك الاطّلاع على مزيد من المعلومات عن حِزم تطوير البرامج (SDK) الخاصة بالعملاء لكل من الويب وAndroid وiOS وFlutter، بالإضافة إلى حِزم تطوير البرامج (SDK) الخاصة بالمشرفين لكل من Node.js.