کیت‌های توسعه نرم‌افزار (SDK) کلاینت Firebase Data Connect به شما امکان می‌دهند کوئری‌ها و جهش‌های سمت سرور خود را مستقیماً از یک برنامه Firebase فراخوانی کنید. شما همزمان با طراحی طرحواره‌ها، کوئری‌ها و جهش‌هایی که در سرویس Data Connect خود پیاده‌سازی می‌کنید، یک SDK کلاینت سفارشی ایجاد می‌کنید. سپس، متدهای این SDK را در منطق کلاینت خود ادغام می‌کنید.
همانطور که در جای دیگری اشاره کردیم، توجه به این نکته مهم است که کوئری‌ها و جهش‌های Data Connect توسط کد کلاینت ارسال و روی سرور اجرا نمی‌شوند. در عوض، هنگام استقرار، عملیات Data Connect مانند توابع ابری روی سرور ذخیره می‌شوند. این بدان معناست که برای جلوگیری از اختلال در عملکرد کاربران موجود (به عنوان مثال، در نسخه‌های قدیمی‌تر برنامه)، باید تغییرات مربوطه در سمت کلاینت را اعمال کنید.
به همین دلیل است که Data Connect یک محیط توسعه‌دهنده و ابزار در اختیار شما قرار می‌دهد که به شما امکان می‌دهد طرح‌ها، کوئری‌ها و جهش‌های مستقر در سرور خود را نمونه‌سازی کنید. همچنین، همزمان با نمونه‌سازی شما، SDKهای سمت کلاینت را به طور خودکار تولید می‌کند.
وقتی به‌روزرسانی‌های مکرر را برای سرویس و برنامه‌های کلاینت خود انجام دادید، به‌روزرسانی‌های سمت سرور و کلاینت آماده‌ی استقرار هستند.
گردش کار توسعه کلاینت چیست؟
اگر بخش « شروع به کار» را دنبال کرده باشید، با جریان کلی توسعه Data Connect آشنا شده‌اید. در این راهنما، اطلاعات دقیق‌تری در مورد تولید SDKهای Swift از طرحواره خود و کار با کوئری‌ها و جهش‌های کلاینت پیدا خواهید کرد.
به طور خلاصه، برای استفاده از SDK های تولید شده Swift در برنامه های کلاینت خود، این مراحل پیش نیاز را دنبال خواهید کرد:
- فایربیس را به برنامه iOS خود اضافه کنید.
برای استفاده از SDK تولید شده، آن را به عنوان یک وابستگی در Xcode پیکربندی کنید.
در نوار ناوبری بالای Xcode، مسیر File > Add Package Dependencies > Add Local را انتخاب کنید و پوشه‌ای که فایل
Package.swiftتولید شده در آن قرار دارد را انتخاب کنید.
سپس:
- طرحواره برنامه خود را توسعه دهید.
تنظیم تولید SDK:
- با دکمه‌ی «افزودن SDK به برنامه» در افزونه‌ی Data Connect VS Code ما
- با به‌روزرسانی
connector.yamlخود
کد کلاینت خود را مقداردهی اولیه کنید و کتابخانه‌ها را وارد کنید .
شبیه‌ساز Data Connect را راه‌اندازی و استفاده کنید و مراحل را تکرار کنید.
سوئیفت SDK خود را ایجاد کنید
از رابط خط فرمان Firebase CLI) برای تنظیم SDK های تولید شده توسط Data Connect در برنامه‌های خود استفاده کنید. دستور init باید تمام برنامه‌های موجود در پوشه فعلی را شناسایی کرده و SDK های تولید شده را به طور خودکار نصب کند.
firebase init dataconnect:sdk
به‌روزرسانی SDKها هنگام نمونه‌سازی اولیه
اگر افزونه‌ی Data Connect VS Code را نصب کرده باشید، این افزونه همیشه SDKهای تولید شده را به‌روز نگه می‌دارد.
اگر از افزونه Data Connect VS Code استفاده نمی‌کنید، می‌توانید از Firebase CLI برای به‌روز نگه داشتن SDKهای تولید شده استفاده کنید.
firebase dataconnect:sdk:generate --watchتولید SDK در خطوط لوله ساخت
شما می‌توانید از Firebase CLI برای تولید SDK های Data Connect در فرآیندهای ساخت CI/CD استفاده کنید.
firebase dataconnect:sdk:generateمقداردهی اولیه‌ی Data Connect iOS SDK
نمونه 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)")
برای بازیابی یک فیلم، از یک مرجع پرس‌وجو استفاده خواهید کرد. همه مراجع پرس‌وجو، ناشران Observable هستند. بسته به ناشر پیکربندی‌شده (به connector.yaml) ، آنها یا از ماکروی @Observable (iOS 17+) پشتیبانی می‌کنند یا پروتکل ObservableObject را پیاده‌سازی می‌کنند. پیش‌فرض، اگر هیچ‌کدام مشخص نشده باشند، ماکروی @Observable است که در iOS 17+ پشتیبانی می‌شود.
در یک نمای SwiftUI، می‌توانید نتایج پرس‌وجو را با استفاده از متغیر data منتشر شده از ref پرس‌وجو متصل کنید و متد 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()
}
}
کوئری‌ها همچنین از اجرای یک‌باره (one-shot execution) پشتیبانی می‌کنند.
let resultData = try await DataConnect.moviesConnector.listMoviesByGenreQuery.execute(genre: "Sci-Fi")
مدیریت تغییرات در فیلدهای شمارشی
طرحواره یک برنامه می‌تواند شامل شمارشگرها باشد که می‌توانند توسط کوئری‌های GraphQL شما قابل دسترسی باشند.
با تغییر طراحی یک برنامه، ممکن است مقادیر جدیدی که توسط enum پشتیبانی می‌شوند را اضافه کنید. برای مثال، تصور کنید که بعداً در چرخه حیات برنامه خود تصمیم می‌گیرید یک مقدار FULLSCREEN به enum مربوط به AspectRatio اضافه کنید.
در گردش کار Data Connect ، می‌توانید از ابزار توسعه محلی برای به‌روزرسانی کوئری‌ها و SDKهای خود استفاده کنید.
با این حال، قبل از اینکه نسخه به‌روز شده‌ای از کلاینت‌های خود را منتشر کنید، کلاینت‌های قدیمی‌تر ممکن است از کار بیفتند.
مثال پیاده‌سازی انعطاف‌پذیر
SDK تولید شده، مدیریت مقادیر ناشناخته را اجباری می‌کند، زیرا enumهای تولید شده حاوی مقدار _UNKNOWN هستند و Swift دستورات سوئیچ جامع را اعمال می‌کند.
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 خود را بسازید و آزمایش کنید
کلاینت‌های Instrument برای استفاده از یک شبیه‌ساز محلی
شما می‌توانید از شبیه‌ساز Data Connect ، چه از طریق افزونه Data Connect VS Code و چه از طریق رابط خط فرمان (CLI)، استفاده کنید.
آماده‌سازی برنامه برای اتصال به شبیه‌ساز برای هر دو سناریو یکسان است.
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 به شرح زیر نمایش داده شده‌اند.
| نوع اتصال داده | سویفت |
|---|---|
| رشته | رشته |
| بین المللی | بین المللی |
| شناور | دو برابر |
| بولی | بول |
| شناسه کاربری | شناسه کاربری |
| تاریخ | اتصال پایگاه داده فایربیس. تاریخ محلی |
| مهر زمانی | هسته فایربیس. مهر زمانی |
| بین‌رشته‌ای64 | بین‌رشته‌ای64 |
| هر | اتصال به پایگاه داده فایربیس. هر مقداری |