استخدام حِزم تطوير البرامج (SDK) لنظام التشغيل iOS التي تم إنشاؤها

تتيح لك حِزم تطوير البرامج (SDK) لعملاء Firebase Data Connect طلب طلبات البحث وعمليات التحويل من جهة الخادم مباشرةً من تطبيق Firebase. يمكنك إنشاء حزمة تطوير برامج (SDK) مخصّصة للعملاء في وقتٍ موازي أثناء تصميم المخططات وطلبات البحث وعمليات التحويل التي يتم نشرها في خدمة Data Connect. بعد ذلك، يمكنك دمج طرق من حزمة SDK هذه في منطق العميل.

كما ذكرنا في مكان آخر، من المهم الإشارة إلى أنّ Data Connect طلبات البحث والطفرات لا يتم إرسالها بواسطة رمز العميل ويتم تنفيذها على الخادم. بدلاً من ذلك، عند نشرها، يتم تخزين عمليات Data Connect على الخادم مثل "وظائف السحابة الإلكترونية". وهذا يعني أنّك بحاجة إلى نشر التغييرات المقابلة من جهة العميل لتجنّب إيقاف المستخدمين الحاليين (على سبيل المثال، في الإصدارات القديمة من التطبيق).

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

بعد تكرار التحديثات على تطبيقَي الخدمة والعملاء، تصبح التحديثات من جهة الخادم وجانب العميل جاهزة للنشر.

إنشاء حزمة تطوير البرامج (SDK) لتطبيق Swift

كما هو الحال مع معظم مشاريع Firebase، يتم تنفيذ العمل على Firebase Data Connect العميل الرمز البرمجي في دليل مشروع على الجهاز. إنّ كلًّا من Firebase CLI وإضافة Data Connect في VS Code مهمّان على مستوى الأدوات المحلية لإنشاء رمز العميل وإدارته.

ترتبط خيارات إنشاء حزمة SDK بعدة إدخالات في dataconnect.yamlملف الذي تم إنشاؤه عند بدء مشروعك.

إعداد عملية إنشاء حزمة تطوير البرامج (SDK)

في connector.yaml، أضِف outputDir وpackage و (بالنسبة إلى حزمة تطوير البرامج (SDK) على الويب) packageJsonDir. 
connectorId: "movies"
generate:
  swiftSdk:
    outputDir: "../movies-generated"
    package: "Movies"

outputDir لتحديد المكان الذي يجب أن يتم فيه إنشاء حزمة SDK. في حال عدم تحديده، يتم استخدام مجلد الموصِّل كدليل الإخراج التلقائي.

package يحدِّد اسم الحزمة التي سيتم إنشاؤها. سيُنشئ أداة الإنشاء مجلدًا باسم الحزمة يحتوي على Package.swift والرمز الذي تم إنشاؤه.

observablePublisher (اختيارية) تحدّد الناشر في Observable المطلوب استخدامه في مراجع طلبات البحث. القيم المحتمَلة هي observableMacro (الإصدار 17 من نظام التشغيل iOS والإصدارات الأحدث) و observableObject (الإصدارات الأقدم من نظام التشغيل iOS). القيمة التلقائية، في حال عدم تحديد أي قيمة، هي observableMacro.

تعديل حِزم تطوير البرامج (SDK) أثناء إنشاء النماذج الأولية

إذا كنت بصدد إنشاء النماذج الأولية بشكل تفاعلي باستخدام إضافة Data Connect في VS Code ومحاكي Data Connect، يتم تلقائيًا إنشاء ملفات مصدر حزمة تطوير البرامج (SDK) وتعديلها أثناء تعديل ملفات .gql التي تحدّد المخططات وطلبات البحث والعمليات. يمكن أن تكون هذه ميزة مفيدة في سير عمل (إعادة) التحميل السريع.

في سيناريوهات أخرى، إذا كنت تستخدم محاكي Data Connect من سطر أوامر Firebase، يمكنك ضبط ميزة "مراقبة" على تحديثات .gql وتعديل مصادر SDK تلقائيًا.

بدلاً من ذلك، يمكنك استخدام سطر الأوامر لإعادة إنشاء حِزم تطوير البرامج (SDK) عند تغيير ملفات ‎ .gql:

firebase dataconnect:sdk:generate --watch

إنشاء حِزم SDK للدمج والإصدارات العلنية

في بعض السيناريوهات، مثل إعداد مصادر المشاريع لإرسالها إلى اختبارات التكامل المستمر، يمكنك استدعاء Firebase CLI لإجراء تحديث مجمّع.

في هذه الحالات، استخدِم firebase dataconnect:sdk:generate.

إعداد رمز العميل

لإعداد رمز العميل لاستخدام Data Connect وحزمة تطوير البرامج (SDK) التي تم إنشاؤها، عليك أولاً اتّباع تعليمات الإعداد العادية لمنصّة Firebase.

بعد ذلك، افتح مساحة عمل تطبيقك باستخدام Xcode.

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

إعداد حزمة تطوير البرامج (SDK) لنظام التشغيل iOS من Data Connect

ابدأ تشغيل مثيل Data Connect باستخدام المعلومات التي استخدَمتها لإعداد Data Connect (كلّها متوفّرة في Firebase console علامة التبويب Data Connect).

الحصول على نسخة من الموصِّل

سينشئ محاكي Data Connect رمز الموصّل. إذا كان اسم الموصِّل هو movies وكانت الحزمة هي movies، كما هو محدّد في connector.yaml، يمكنك استرداد عنصر الموصِّل من خلال الاتصال:

let connector = DataConnect.moviesConnector

تنفيذ طلبات البحث والطفرات

باستخدام عنصر الموصّل، يمكنك تنفيذ طلبات البحث والتغييرات كما هو محدّد في ملف برمجة تطبيقات GraphQL المصدر. لنفترض أنّ عملية الربط قد حدّدت العمليات التالية:

mutation createMovie($title: String!, $releaseYear: Int!, $genre: String!, $rating: Int!) {
  movie_insert(data: {
    title: $title
    releaseYear: $releaseYear
    genre: $genre
    rating: $rating
  })
}

query getMovieByKey($key: Movie_Key!) {
  movie(key: $key) { id title }
}

query listMoviesByGenre($genre: String!) {
  movies(where: {genre: {eq: $genre}}) {
    id
    title
  }
}

يمكنك بعد ذلك إنشاء فيلم باتّباع الخطوات التالية:

let mutationResult = try await connector.createMovieMutation.execute(
  title: "Empire Strikes Back",
  releaseYear: 1980,
  genre: "Sci-Fi",
  rating: 5)

print("Movie ID: \(mutationResult.data.movie_insert.id)")

لاسترداد فيلم، ستستخدم مرجع طلب بحث. جميع مراجع طلبات البحث هي ناشرون قابلون للتتبّع. استنادًا إلى الناشر الذي تم ضبطه (راجِع connector.yaml))، يمكن أن يكونا متوافقَين مع وحدة الماكرو @Observable (الإصدار 17 من نظام التشغيل iOS والإصدارات الأحدث) أو ينفِّذان بروتوكول ObservableObject. الإعداد التلقائي، في حال عدم تحديد أي إعداد، هو macro @Observable المتوافق مع الإصدار 17 من نظام التشغيل iOS والإصدارات الأحدث.

في عرض SwiftUI، يمكنك ربط نتائج طلب البحث باستخدام المتغيّر data المنشور لمرجع طلب البحث واستدعاء طريقة execute() لطلب البحث لتعديل البيانات. سيتطابق المتغيّر data مع شكل البيانات التي تم تحديدها في تعريف طلب البحث بتنسيق GQL.

تتوافق جميع النتائج التي يتم استرجاعها مع بروتوكول Decodable. إذا أدرجت المفتاح الأساسي للعنصر في طلب جلب GQL، تكون العناصر أيضًا Identifiable، مما يتيح لك استخدامها في الدوالّ المتكرّرة. 

struct ListMovieView: View {
    @StateObject private var queryRef = connector.listMoviesByGenreQuery.ref(genre: "Sci-Fi")
    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()
    }
}

تتيح طلبات البحث أيضًا التنفيذ لمرة واحدة. 

let resultData = try await DataConnect.moviesConnector.listMoviesByGenreQuery.execute(genre: "Sci-Fi")

إنشاء نموذج أولي لتطبيق iOS واختباره

إعداد التطبيقات لاستخدام محاكي محلي

يمكنك استخدام محاكي Data Connect، سواء من إضافة Data Connect في VS Code أو من سطر الأوامر.

لا يختلف إعداد التطبيق للاتصال بالمحاكي في كلا السيناريوهَين.

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)

// Make calls from your app

أنواع البيانات في حِزم SDK من Data Connect

يمثّل خادم Data Connect أنواع بيانات GraphQL الشائعة والمخصّصة. يتم تمثيل هذه العناصر في حزمة SDK على النحو التالي.

نوع ربط البيانات Swift
سلسلة سلسلة
Int Int
عائم مزدوج
منطقي منطقية
معرِّف فريد عالمي (UUID) معرِّف فريد عالمي (UUID)
التاريخ FirebaseDataConnect.LocalDate
الطابع الزمني FirebaseCore.Timestamp
Int64 Int64
أي FirebaseDataConnect.AnyValue