Firebase SQL Connect تتيح لك حِزم تطوير البرامج (SDK) من جهة العميل إرسال طلبات البحث والتعديلات من جهة الخادم مباشرةً من تطبيق Firebase. ويمكنك إنشاء حزمة تطوير برامج (SDK) مخصّصة من جهة العميل بالتزامن مع تصميم المخططات وطلبات البحث والتعديلات التي تنشرها في خدمة SQL Connect. بعد ذلك، يمكنك دمج طرق من حزمة تطوير البرامج هذه في منطق العميل.
كما ذكرنا في موضع آخر، من المهم الإشارة إلى أنّ SQL Connect طلبات البحث وعمليات التعديل لا يتم إرسالها من خلال رمز العميل وتنفيذها على الخادم. بدلاً من ذلك، عند نشر عمليات SQL Connect، يتم تخزينها على الخادم مثل "وظائف السحابة الإلكترونية". وهذا يعني أنّه عليك نشر تغييرات مقابلة من جهة العميل لتجنُّب تعطيل التطبيق للمستخدمين الحاليين (على سبيل المثال، في إصدارات التطبيق القديمة).
لهذا السبب، يوفّر لك SQL Connect بيئة تطوير وأدوات تتيح لك إنشاء نماذج أولية للمخططات وطلبات البحث وعمليات التعديل التي يتم نشرها على الخادم. تنشئ أيضًا حِزم SDK من جهة العميل تلقائيًا أثناء إنشاء النماذج الأولية.
بعد تكرار التعديلات على خدمتك وتطبيقات العميل، يصبح كلا التعديلين على جهة الخادم ومن جهة العميل جاهزًا للنشر.
ما هي خطوات تطوير التطبيق؟
إذا اتّبعت الخطوات الواردة في البدء، تعرّفت على سير عملية التطوير بشكل عام في SQL Connect. في هذا الدليل، ستجد معلومات أكثر تفصيلاً حول إنشاء حِزم تطوير برامج (SDK) بلغة Swift من المخطط الخاص بك والتعامل مع طلبات البحث وعمليات التعديل من جهة العميل.
باختصار، لاستخدام حِزم تطوير البرامج (SDK) التي تم إنشاؤها بلغة Swift في تطبيقات العميل، عليك اتّباع خطوات المتطلبات الأساسية التالية:
- أضِف Firebase إلى تطبيق iOS.
لاستخدام حزمة تطوير البرامج (SDK) التي تم إنشاؤها، اضبطها كعنصر تابع في Xcode.
في شريط التنقّل العلوي في Xcode، انقر على ملف (File) > إضافة موارد الاعتمادية للحزمة (Add Package Dependencies) > إضافة محلية (Add Local)، ثم اختَر المجلد الذي يحتوي على حزمة
Package.swiftالتي تم إنشاؤها.
بعد ذلك:
- طوِّر مخطّط تطبيقك.
إعداد إنشاء حزمة تطوير البرامج (SDK):
- باستخدام الزر إضافة حزمة تطوير البرامج (SDK) إلى التطبيق في إضافة SQL Connect VS Code
- من خلال تعديل
connector.yaml
إعداد SQL Connect المحاكي واستخدامه والتكرار.
إنشاء حزمة تطوير البرامج (SDK) بلغة Swift
استخدِم واجهة سطر الأوامر Firebase لإعداد حِزم تطوير البرامج (SDK) التي تم إنشاؤها باستخدام SQL Connect في تطبيقاتك.
من المفترض أن يرصد الأمر init جميع التطبيقات في المجلد الحالي ويثبّت حِزم SDK التي تم إنشاؤها تلقائيًا.
firebase init dataconnect:sdk
تعديل حِزم SDK أثناء إنشاء النماذج الأولية
إذا كانت لديك إضافة SQL Connect VS Code مثبَّتة، ستحرص دائمًا على إبقاء حِزم SDK التي تم إنشاؤها محدّثة.
إذا كنت لا تستخدم إضافة SQL Connect في VS Code، يمكنك استخدام Firebase CLI لإبقاء حِزم تطوير البرامج (SDK) التي تم إنشاؤها محدّثة.
firebase dataconnect:sdk:generate --watchإنشاء حِزم SDK في مسارات الإنشاء
يمكنك استخدام Firebase CLI لإنشاء حِزم تطوير البرامج (SDK) الخاصة بـ SQL Connect في عمليات إنشاء CI/CD.
firebase dataconnect:sdk:generateإعداد حزمة تطوير البرامج SQL Connect لنظام التشغيل iOS
ابدأ مثيل SQL Connect باستخدام المعلومات التي استخدمتها لإعداد SQL Connect. يمكنك العثور على هذه المعلومات في صفحة قواعد البيانات ومساحة التخزين > SQL Connect في وحدة تحكّم Firebase.
الحصول على مثيل موصّل
سيتم إنشاء الرمز الخاص بالموصّل من خلال محاكي SQL 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")
الاشتراك في تلقّي إشعارات بالتغييرات
اطّلِع على تلقّي آخر الأخبار من SQL Connect.
التعامل مع التغييرات في حقول التعداد
يمكن أن يحتوي مخطط التطبيق على تعدادات، ويمكن الوصول إليها من خلال طلبات بحث GraphQL.
عندما يتغير تصميم التطبيق، يمكنك إضافة قيم جديدة متوافقة مع التعداد. على سبيل المثال،
لنفترض أنّك قرّرت في وقت لاحق من دورة حياة تطبيقك إضافة
القيمة FULLSCREEN إلى تعداد AspectRatio.
في سير عمل SQL 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
}
تفعيل التخزين المؤقت من جهة العميل
يتضمّن SQL Connect ميزة اختيارية للتخزين المؤقت من جهة العميل، ويمكنك تفعيلها من خلال تعديل ملف connector.yaml. عند تفعيل هذه الميزة، ستخزّن حِزم SDK للعميل التي تم إنشاؤها ردود طلبات البحث مؤقتًا على الجهاز، ما قد يقلّل عدد طلبات قاعدة البيانات التي يرسلها تطبيقك ويتيح تشغيل أجزاء تطبيقك التي تعتمد على قاعدة البيانات عند انقطاع الاتصال بالشبكة.
لتفعيل التخزين المؤقت من جهة العميل، أضِف إعدادات التخزين المؤقت من جهة العميل إلى إعدادات الموصل:
generate:
swiftSdk:
outputDir: "../ios"
package: "FirebaseDataConnectGenerated"
clientCache:
maxAge: 5s
storage: persistent
يتضمّن هذا الإعداد مَعلمتَين، وكلاهما اختياري:
maxAge: الحد الأقصى لعمر الرد المخزّن مؤقتًا قبل أن تجلب حزمة SDK الخاصة بالعميل قيمًا جديدة. أمثلة: "0" أو "30 ثانية" أو "ساعة و30 دقيقة".القيمة التلقائية لـ
maxAgeهي0، ما يعني أنّه يتم تخزين الردود مؤقتًا، ولكن ستحصل حزمة تطوير البرامج (SDK) الخاصة بالعميل دائمًا على قيم جديدة. لن يتم استخدام القيم المخزّنة مؤقتًا إلا عندما تكون قيمةCACHE_ONLYهيexecute().
storage: يمكن ضبط حزمة تطوير البرامج (SDK) الخاصة بالعميل لتخزين الردود مؤقتًا إما في مساحة التخزينpersistentأو فيmemory. ستظل النتائج المخزّنة مؤقتًا في مساحة تخزينpersistentمتاحة عند إعادة تشغيل التطبيق. في حِزم تطوير البرامج لنظام التشغيل iOS، تكون القيمة التلقائية هيpersistent.
بعد تعديل إعدادات التخزين المؤقت للموصل، أعِد إنشاء حِزم تطوير البرامج (SDK) الخاصة بالعميل وأعِد إنشاء تطبيقك. بعد الانتهاء من ذلك، سيخزّن execute() الردود مؤقتًا ويستخدم القيم المخزّنة مؤقتًا وفقًا للسياسة التي أعددتها. يحدث ذلك تلقائيًا بشكل عام، بدون أي خطوات إضافية من جانبك، ولكن يُرجى ملاحظة ما يلي:
يكون السلوك التلقائي لـ
execute()كما هو موضّح أعلاه: إذا تم تخزين نتيجة مؤقتًا لطلب بحث وكانت القيمة المخزَّنة مؤقتًا ليست أقدم منmaxAge، يتم استخدام القيمة المخزَّنة مؤقتًا. يُعرف هذا السلوك التلقائي باسم سياسةPREFER_CACHE.يمكنك أيضًا تحديد ما إذا كان سيتم عرض القيم المخزّنة مؤقتًا فقط (
CACHE_ONLY) أو جلب قيم جديدة من الخادم بدون شروط (SERVER_ONLY) عند كل استدعاء فردي للدالةexecute().try await execute(fetchPolicy: .cacheOnly)try await execute(fetchPolicy: .serverOnly)إنشاء نموذج أولي لتطبيق iOS واختباره
يمكنك استخدام المحاكي المحلي لاختبار تطبيقك وإنشاء نموذج أولي له.
تجهيز العملاء لاستخدام محاكي محلي
يمكنك استخدام محاكي SQL Connect، سواء من إضافة SQL Connect في Visual Studio 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) التي تحمل الرقم SQL Connect
يمثّل خادم SQL Connect أنواع بيانات GraphQL الشائعة والمخصّصة. ويتم تمثيلها في حزمة SDK على النحو التالي.
SQL Connect النوع Swift سلسلة سلسلة Int Int عائم مزدوج قيمة منطقية Bool معرِّف فريد عالمي (UUID) معرِّف فريد عالمي (UUID) التاريخ FirebaseDataConnect.LocalDate الطابع الزمني FirebaseCore.Timestamp Int64 Int64 أي FirebaseDataConnect.AnyValue