کیتهای توسعه نرمافزار (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
}
فعال کردن حافظه پنهان سمت کلاینت
Data Connect یک ویژگی ذخیرهسازی (caching) اختیاری در سمت کلاینت دارد که میتوانید با ویرایش فایل connector.yaml آن را فعال کنید. وقتی این ویژگی فعال باشد، SDK های کلاینت تولید شده، پاسخهای کوئری را به صورت محلی ذخیره میکنند که میتواند تعداد درخواستهای پایگاه دادهای که برنامه شما ایجاد میکند را کاهش دهد و بخشهای وابسته به پایگاه داده برنامه شما را قادر سازد تا در صورت قطع دسترسی به شبکه، کار کنند.
برای فعال کردن ذخیرهسازی سمت کلاینت، پیکربندی ذخیرهسازی سمت کلاینت را به پیکربندی کانکتور خود اضافه کنید:
generate:
swiftSdk:
outputDir: "../ios"
package: "FirebaseDataConnectGenerated"
clientCache:
maxAge: 5s
storage: persistent
این پیکربندی دو پارامتر دارد که هر دو اختیاری هستند:
maxAge: حداکثر سنی که یک پاسخ ذخیره شده میتواند داشته باشد قبل از اینکه SDK کلاینت مقادیر جدید را دریافت کند. مثالها: "0"، "30s"، "1h30m".مقدار پیشفرض برای
maxAge0است، به این معنی که پاسخها ذخیره میشوند، اما SDK کلاینت همیشه مقادیر تازه را دریافت میکند. مقادیر ذخیره شده فقط زمانی استفاده میشوند کهCACHE_ONLYبرایexecute()مشخص شده باشد.storage: SDK کلاینت را میتوان طوری پیکربندی کرد که پاسخها را در حافظهیpersistentیا درmemoryذخیره کند. نتایج ذخیرهشده در حافظهیpersistentدر طول راهاندازی مجدد برنامه باقی میمانند. در SDKهای iOS، پیشفرضpersistentاست.
پس از بهروزرسانی پیکربندی ذخیرهسازی کانکتور، SDKهای کلاینت خود را مجدداً تولید کرده و برنامه خود را از نو بسازید. پس از انجام این کار، execute() پاسخها را ذخیره کرده و از مقادیر ذخیره شده طبق سیاستی که پیکربندی کردهاید استفاده میکند. این کار معمولاً به طور خودکار و بدون هیچ مرحله اضافی از جانب شما انجام میشود. با این حال، به موارد زیر توجه کنید:
رفتار پیشفرض
execute()همانطور که در بالا توضیح داده شد، است: اگر نتیجهای برای یک پرسوجو ذخیره شده باشد و مقدار ذخیره شده قدیمیتر ازmaxAgeنباشد، در این صورت از مقدار ذخیره شده استفاده کنید. این رفتار پیشفرض، سیاستPREFER_CACHEنامیده میشود.همچنین میتوانید برای فراخوانیهای مجزای
execute()مشخص کنید که یا فقط مقادیر ذخیرهشده در حافظه پنهان (CACHE_ONLY) را ارائه دهند یا بدون قید و شرط مقادیر تازه را از سرور دریافت کنند (SERVER_ONLY).try await execute(fetchPolicy: .cacheOnly)try await execute(fetchPolicy: .serverOnly)نمونه اولیه برنامه 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 به شرح زیر نمایش داده شدهاند.
نوع Data Connect سویفت رشته رشته بین المللی بین المللی شناور دو برابر بولی بول شناسه کاربری شناسه کاربری تاریخ اتصال پایگاه داده فایربیس. تاریخ محلی مهر زمانی هسته فایربیس. مهر زمانی بینرشتهای64 بینرشتهای64 هر اتصال به پایگاه داده فایربیس. هر مقداری