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

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

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

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

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

إنشاء حزمة تطوير برامج Swift

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

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

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

connectorId: "movies"
generate:
  swiftSdk:
    outputDir: "../movies-generated"
    package: "Movies"

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

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

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

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

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

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

firebase dataconnect:sdk:generate --watch

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

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

في هذه الحالات، استخدِم 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 على النحو التالي.