查看 2022 年 Google I/O 大会上介绍的 Firebase 新动态。了解详情

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

بدء استخدام Firebase Data Connect على الجهاز

في هذا الدليل السريع، ستتعرّف على كيفية إنشاء Firebase Data Connect في تطبيقك على الجهاز بدون إعداد مثيل SQL في مرحلة الإنتاج. ويمكنك إجراء ما يلي:

أضِف Firebase Data Connect إلى مشروعك على Firebase.
إعداد بيئة تطوير تتضمّن إضافة Visual Studio Code للعمل مع مثيل محلي
بعد ذلك، سنوضّح لك كيفية:
- إنشاء مخطّط لتطبيق أفلام
- تحديد طلبات البحث والطفرات التي سيتم استخدامها في تطبيقك
- اختبار طلبات البحث والطفرات باستخدام عيّنات البيانات في محاكي محلي
- إنشاء حِزم تطوير برامج (SDK) ذات أنواع محدّدة بدقة واستخدامها في تطبيقك
- نشر المخطّط النهائي وطلبات البحث والبيانات في السحابة الإلكترونية (اختياري، مع ترقية خطة Blaze)

اختيار عملية تطوير على الجهاز

يوفّر لك Data Connect طريقتَين لتثبيت أدوات التطوير والعمل على الجهاز.

المتطلبات الأساسية

لاستخدام دليل البدء السريع هذا، ستحتاج إلى ما يلي:

مشروع على Firebase إذا لم يسبق لك إنشاء حساب، يمكنك إجراء ذلك في وحدة تحكّم Firebase.

إعداد بيئة التطوير

أنشئ دليلاً جديدًا لمشروعك على الجهاز.
نفِّذ الأمر التالي في الدليل الجديد الذي أنشأته.
```
  curl -sL https://firebase.tools/dataconnect | bash
```
يحاول هذا النص البرمجي إعداد بيئة التطوير نيابةً عنك وبدء IDE المستند إلى المتصفّح. توفّر بيئة تطوير البرامج هذه أدوات، بما في ذلك ملف تم تجميعه مسبقًا لإضافته إلى VS Code، لمساعدتك في إدارة مخطّطك وتحديد طلبات البحث و عمليات التحويل التي سيتم استخدامها في تطبيقك، وإنشاء حِزم SDK ذات أنواع محدّدة بدقة.

ملاحظة: إذا كان إصدار VS Code المخصّص للكمبيوتر المكتبي مثبّتًا لديك، سيفتحه الرمز المبرمَج تلقائيًا.
ملاحظة: إذا تعذّر تشغيل الرمز المبرمَج، استخدِم خطوات التثبيت اليدوي.

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

إعداد دليل المشروع

لإعداد مشروعك على الجهاز، عليك بدء دليل المشروع. في IDE النافذة، في اللوحة اليمنى، انقر على رمز Firebase لفتح واجهة مستخدم ملف ترميز VS Code لإضافة Data Connect:

انقر على الزر تسجيل الدخول باستخدام حساب Google.
انقر على الزر ربط مشروع Firebase واختَر المشروع الذي أنشأته سابقًا في وحدة التحكّم.
انقر على الزر Run firebase init (تشغيل firebase init).
انقر على الزر بدء المحاكيات.

ملاحظة: في Terminal المدمج، تأكَّد من بدء تشغيل المحاكيات التي تم ضبطها. بعد تشغيلهما، من المفترض أن يظهر لك تحديث واجهة مستخدم الإضافة مع تفاصيل المحاكي.

إنشاء مخطّط

في دليل مشروع Firebase، في ملف /dataconnect/schema/schema.gql ، ابدأ بتحديد مخطّط GraphQL عن الأفلام.

فيلم

في Data Connect، يتم ربط حقول GraphQL بالأعمدة. يتضمّن الفيلم id، title، imageUrl وgenre. يتعرّف Data Connect على نوعَي data primitiv: 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
}

MovieMetadata

انسخ المقتطف التالي أو أزِل التعليقات من الأسطر المقابلة في الملف.

# 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. يمكنك استخدام الزرَّين إضافة بيانات وتنفيذ (محلي) لإضافة بيانات إلى قاعدة البيانات المحلية.

لإضافة سجلّات إلى جدولَي Movie وMovieMetadata:

في schema.gql، انقر على الزر إضافة بيانات أعلى Movie نوع بيان.
في ملف Movie_insert.gql الذي يتم إنشاؤه، أدخِل البيانات في ملف ثابت لثلاثة حقول.
انقر على الزر تشغيل (محلي).
كرِّر الخطوات السابقة لإضافة سجلّ إلى جدول MovieMetadata، مع توفير id لفيلمك في الحقل movieId، كما هو مطلوب في تحوُّل MovieMetadata_insert الذي تم إنشاؤه.

للتحقّق بسرعة من إضافة البيانات، اتّبِع الخطوات التالية:

في schema.gql، انقر على الزر قراءة البيانات فوق بيان نوع Movie.
في ملف Movie_read.gql الناتج، انقر على الزر تشغيل (محلي) ل ejecutant طلب البحث.

مزيد من المعلومات عن طفرات "ربط البيانات" في المستندات

تحديد طلب البحث

الآن، نأتي إلى الجزء الممتع: لنحدّد طلبات البحث التي ستحتاج إليها في طلبك. بصفتك مطوّرًا، اعتدت كتابة طلبات بحث SQL بدلاً من طلبات بحث GraphQL، لذا قد يبدو لك هذا الأمر مختلفًا بعض الشيء في البداية.

ومع ذلك، فإنّ GraphQL أكثر إيجازًا وأمانًا من لغة SQL الأوّلية. وتسهّل إضافة VS Code تجربة التطوير.

ابدأ بتعديل ملف /dataconnect/connector/queries.gql. إذا أردت الحصول على كل الأفلام، استخدِم طلب بحث مثل هذا.

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

# @auth() directives control who can call each operation.
# Anyone should be able to list all movies, so the auth level is set to PUBLIC
query ListMovies @auth(level: PUBLIC) {
  movies {
    id
    title
    imageUrl
    genre
  }
}

نفِّذ الطلب باستخدام زر CodeLens القريب.

من الميزات المثيرة للاهتمام هنا إمكانية التعامل مع علاقات قاعدة البيانات كرسم بياني. بما أنّ سجلّ MovieMetadata يحتوي على حقل movie يشير إلى فيلم، يمكنك التداخل في الحقل والحصول على معلومات عن معلومات الفيلم. حاوِل إضافة النوع الذي تم إنشاؤه movieMetadata_on_movie إلى طلب البحث ListMovies.

query ListMovies @auth(level: PUBLIC) {
  movies {
    id
    title
    imageUrl
    genre
    movieMetadata_on_movie {
        rating
    }
  }
}

مزيد من المعلومات حول طلبات البحث في Data Connect في المستندات

إنشاء حِزم تطوير برامج (SDK) واستخدامها في تطبيقك

في اللوحة اليمنى لتطوير البرامج المتكاملة (IDE)، انقر على رمز Firebase لفتح واجهة مستخدم ملف ترميز إضافة Data Connect في VS Code:

انقر على الزر إضافة حزمة تطوير البرامج (SDK) إلى التطبيق.
في مربّع الحوار الذي يظهر، اختَر دليلاً يحتوي على رمز لتطبيقك. Data Connect سيتم إنشاء رمز حزمة SDK و حفظه هناك.

ملاحظة: إذا لم يكن لديك دليل تطبيقات حتى الآن، يمكنك إنشاء ملف تعريف جديد لشفرة حزمة SDK وتحديده في الوقت الحالي وربطه بتطبيقك لاحقًا.
اختَر نظام أساسي لتطبيقك، ثم لاحِظ أنّه يتم إنشاء رمز حزمة SDK على الفور في الدليل الذي اخترته.

استخدام حِزم SDK للاتّصال بطلب البحث من تطبيق

يمكنك استخدام حزمة SDK التي أنشأها Data Connect لتنفيذ طلب إلى طلب البحث ListMovies. يمكنك بعد ذلك تنفيذ هذا الاستعلام محليًا باستخدام محاكي Data Connect.

الويب

أضِف Firebase إلى تطبيق الويب.

في الملف الرئيسي لتطبيق 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 '@movie-app/movies';

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

Swift

أضِف Firebase إلى تطبيقك المتوافق مع iOS.
لاستخدام حزمة SDK التي تم إنشاؤها، عليك ضبطها كعنصر تابع في Xcode.

في شريط التنقّل العلوي في Xcode، اختَر ملف > إضافة متطلّبات الحزمة > إضافة ملف محلي، ثم اختَر المجلد الذي يحتوي على Package.swift الذي تم إنشاؤه.

في المفوَّض الرئيسي لتطبيقك:

استيراد حزمة 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 ?? [], id: \.self.id) { 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.kts.

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

في النشاط الرئيسي لتطبيقك:

استيراد حزمة 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
      }
    }
  }
}

Flutter

أضِف Firebase إلى تطبيق Flutter.
ثبِّت حزمة flutterfire CLI dart pub global activate flutterfire_cli.
شغِّل flutterfire configure.
في الوظيفة الرئيسية لتطبيقك:
- استيراد حزمة 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();
            }),
      )
    ])));
  }
}

نشر المخطّط وطلب البحث في قناة الإصدار العلني

بعد الانتهاء من الإعداد على جهازك، يمكنك الآن نشر المخطّط والبيانات وطلبات البحث في السحابة الإلكترونية. يجب أن يكون لديك مشروع في خطة Blaze لإعداد مثيل Cloud SQL.

انتقِل إلى قسم "ربط البيانات" في وحدة تحكّم Firebase وأنشئ مثيلًا مجانيًا في Cloud SQL.

ملاحظة: قد يستغرق توفير مثيل Cloud SQL لـ PostgreSQL ما يصل إلى 15 دقيقة. لن تتمكّن من النشر إلى أن يصبح المثيل جاهزًا.
ملاحظة: إذا كنت تريد استخدام مفاتيح التشفير التي يديرها العميل (CMEK)، تأكَّد من اختيار استخدام مثيل Cloud SQL الحالي واختيار قاعدة بيانات Cloud SQL حالية تتضمّن مفاتيح CMEK.
في وحدة التحكّم المدمجة في IDE، شغِّل firebase init dataconnect و اختَر رقم تعريف المنطقة/الخدمة الذي أنشأته للتو في وحدة التحكّم.
اختَر "نعم" عندما يُطلب منك "ملف dataconnect/dataconnect.yaml يوجد حاليًا، هل تريد استبداله؟".
في نافذة IDE، في واجهة مستخدم إضافة VS Code، انقر على الزر النشر في قناة الإصدار العلني.
بعد نشر النموذج، انتقِل إلى وحدة تحكّم Firebase للتحقّق من تحميل المخطّط والعمليات والبيانات إلى السحابة الإلكترونية. من المفترض أن تتمكّن من عرض المخطّط وتنفيذ عملياتك على وحدة التحكّم أيضًا. سيتم تعديل مثيل Cloud SQL لـ PostgreSQL بالبيانات والمخطّط النهائيين المُنشئَين والمُنفَّذَين.

الخطوات التالية

راجِع مشروعك المنشور واستكشِف المزيد من الأدوات:

يمكنك إضافة بيانات إلى قاعدة بياناتك، وفحص المخططات وتعديلها، وتتبُّع خدمة Data Connect في وحدة تحكُّم Firebase.

يمكنك الاطّلاع على مزيد من المعلومات في المستندات. على سبيل المثال، بعد أن اكتملت الخطوة الأولى:

اطّلِع على مزيد من المعلومات عن تطوير المخططات وطلبات البحث والطفرات.
اطّلِع على مزيد من المعلومات عن إنشاء حِزم تطوير برامج (SDK) للعملاء واستدعاء طلبات البحث والتغييرات من код العميل لالويب وAndroid وiOS وFlutter.