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

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

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

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

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

ما هي خطوات سير عمل تطوير العملاء؟

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

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

  1. أضِف Firebase إلى تطبيق iOS.

  2. لاستخدام حزمة SDK التي تم إنشاؤها، عليك ضبطها كعنصر تابع في Xcode.

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

بعد ذلك:

  1. طوِّر مخطط تطبيقك.

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

    • باستخدام الزر إضافة حزمة تطوير البرامج (SDK) إلى التطبيق في إضافة Data Connect VS Code
    • من خلال تعديل connector.yaml

  3. تهيئة رمز العميل واستيراد المكتبات

  4. تنفيذ طلبات البحث والتعديلات

  5. إعداد Data Connect المحاكي واستخدامه والتكرار

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

كما هو الحال مع معظم مشاريع Firebase، يتم العمل على رمز Firebase Data Connectالعميل في دليل مشروع محلي. يُعدّ كل من إضافة Data Connect في Visual Studio Code وواجهة سطر الأوامر Firebase أداتَين محليتَين مهمتَين لإنشاء رمز العميل وإدارته.

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

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

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

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

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

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

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

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

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

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

firebase dataconnect:sdk:generate --watch

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

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

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

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

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

الحصول على مثيل موصّل

سيتم إنشاء رمز الموصل بواسطة محاكي 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. القيمة التلقائية، في حال عدم تحديد أي قيمة، هي الماكرو @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")

التعامل مع التغييرات في حقول التعداد

يمكن أن يحتوي مخطط التطبيق على تعدادات، ويمكن الوصول إليها من خلال طلبات بحث GraphQL.

عندما يتغيّر تصميم التطبيق، يمكنك إضافة قيم جديدة متوافقة مع التعداد. على سبيل المثال، لنفترض أنّك قرّرت في وقت لاحق من دورة حياة تطبيقك إضافة القيمة FULLSCREEN إلى تعداد AspectRatio.

في سير عمل Data Connect، يمكنك استخدام أدوات التطوير المحلية لتعديل الاستعلامات وحِزم SDK.

ومع ذلك، قبل طرح إصدار محدَّث من برامج العميل، قد تتعطّل الإصدارات القديمة التي تم نشرها.

مثال على عملية تنفيذ مرنة

تفرض حزمة تطوير البرامج (SDK) التي تم إنشاؤها التعامل مع القيم غير المعروفة لأنّ التعدادات التي تم إنشاؤها تحتوي على قيمة _UNKNOWN، ويفرض Swift عبارات switch شاملة.

do {
    let result = try await DataConnect.moviesConnector.listMovies.execute()
    if let data = result.data {
        for movie in data.movies {
            switch movie.aspectratio {
                case .ACADEMY: print("academy")
                case .WIDESCREEN: print("widescreen")
                case .ANAMORPHIC: print("anamorphic")
                case ._UNKNOWN(let unknownAspect): print(unknownAspect)
            }
        }
    }
} catch {
    // handle error
}

إنشاء نموذج أولي لتطبيق 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 على النحو التالي.

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