۱. مرور کلی
در این آزمایشگاه کد، شما Firebase Data Connect را با یک پایگاه داده Cloud SQL ادغام خواهید کرد تا یک برنامه اندروید نقد فیلم بسازید. شما یاد خواهید گرفت که چگونه:
- یک طرح GraphQL برای Firebase Data Connect بنویسید
- نوشتن کوئریها و جهشها
- احراز هویت کاربر را برای ایمنسازی دادههای خود پیادهسازی کنید
پیشنیازها
- آخرین نسخه اندروید استودیو
- شبیهساز اندروید با API سطح ۲۳ یا بالاتر
آنچه یاد خواهید گرفت
- نحوه راهاندازی Firebase Data Connect با شبیهسازهای محلی.
- نحوه طراحی یک طرح داده با استفاده از Data Connect و GraphQL.
- نحوه نوشتن کوئریها و جهشها برای یک اپلیکیشن نقد فیلم.
- نحوه تولید SDK کاتلین و استفاده از آن در یک برنامه اندروید.
- (اختیاری) نحوهی استقرار سرویس Data Connect در محیط عملیاتی.
۲. پروژه نمونه را تنظیم کنید
ایجاد یک پروژه فایربیس
- با استفاده از حساب گوگل خود وارد کنسول فایربیس شوید.
- برای ایجاد یک پروژه جدید، روی دکمه کلیک کنید و سپس نام پروژه را وارد کنید (برای مثال،
Movie Review). - روی ادامه کلیک کنید.
- در صورت درخواست، شرایط Firebase را مرور و قبول کنید و سپس روی ادامه کلیک کنید.
- (اختیاری) دستیار هوش مصنوعی را در کنسول Firebase (با نام "Gemini در Firebase") فعال کنید.
- برای این codelab، به گوگل آنالیتیکس نیاز ندارید ، بنابراین گزینه گوگل آنالیتیکس را غیرفعال کنید .
- روی ایجاد پروژه کلیک کنید، منتظر بمانید تا پروژه شما آماده شود و سپس روی ادامه کلیک کنید.
کد را دانلود کنید
دستور زیر را برای کپی کردن کد نمونه برای این codelab اجرا کنید. این کار یک دایرکتوری به نام codelab-dataconnect-android در دستگاه شما ایجاد میکند:
git clone https://github.com/firebaseextended/codelab-dataconnect-android.git
اگر گیت را روی دستگاه خود ندارید، میتوانید کد را مستقیماً از گیتهاب دانلود کنید .
پیکربندی Firebase را اضافه کنید
- در کنسول Firebase ، در منوی سمت چپ، گزینه Project Overview را انتخاب کنید. برای انتخاب پلتفرم، روی دکمه Android کلیک کنید. در صورت درخواست نام بسته،
com.google.firebase.example.dataconnectاستفاده کنید. - روی ثبت برنامه کلیک کنید و دستورالعملها را برای دانلود فایل
google-services.jsonدنبال کنید و آن را به پوشهapp/کدی که دانلود کردهاید منتقل کنید. سپس روی Next کلیک کنید.
۳. اتصال داده را راهاندازی کنید
نصب
نصب خودکار
دستور زیر را در پوشه codelab-dataconnect-android اجرا کنید:
curl -sL https://firebase.tools/dataconnect | bash
این اسکریپت سعی میکند محیط توسعه را برای شما راهاندازی کند و یک IDE مبتنی بر مرورگر را راهاندازی کند. این IDE ابزارهایی از جمله یک افزونه VS Code از پیش بستهبندی شده را ارائه میدهد تا به شما در مدیریت طرحواره خود و تعریف پرسوجوها و جهشهایی که باید در برنامه خود استفاده کنید و SDK های با نوع قوی تولید کند، کمک کند.
پس از اجرای اسکریپت، VS Code باید به طور خودکار باز شود.
نکته: اگر از قبل نسخه دسکتاپ VS Code را نصب کردهاید، اسکریپت باید آن را به طور خودکار باز کند. اگر اسکریپت اجرا نشد، از مراحل نصب دستی زیر استفاده کنید.
نصب دستی
- نصب ویژوال استودیو کد
- نصب Node.js
- در VS Code، پوشه
codelab-dataconnect-androidرا باز کنید. - افزونهی Firebase Data Connect را از Visual Studio Code Marketplace نصب کنید.
مقداردهی اولیه Data Connect در پروژه
در پنل سمت چپ، روی آیکون Firebase کلیک کنید تا رابط کاربری افزونه Data Connect VS Code باز شود:
- روی دکمهی «ورود با گوگل» کلیک کنید. یک پنجرهی مرورگر باز میشود؛ دستورالعملها را دنبال کنید تا با حساب گوگل خود وارد افزونه شوید.
- روی دکمهی «اتصال به پروژهی فایربیس» کلیک کنید و پروژهای را که قبلاً در کنسول ایجاد کردهاید، انتخاب کنید.
روی دکمهی Run firebase init کلیک کنید و مراحل موجود در ترمینال یکپارچه را دنبال کنید.
پیکربندی تولید SDK
زمانی که روی دکمهی Run firebase init کلیک کنید، افزونهی Firebase Data Connect باید یک دایرکتوری dataconnect/ را برای شما مقداردهی اولیه کند.
در VS Code، فایل dataconnect/connector/connector.yaml را باز کنید تا پیکربندی پیشفرض را پیدا کنید. برای اینکه تجسم تولید کد در این codelab آسانتر شود، connectorId را به movies و پکیج را به com.google.firebase.example.dataconnect.generated تغییر دهید:
connectorId: movies
generate:
kotlinSdk:
outputDir: ../../app/src/main/java
package: com.google.firebase.example.dataconnect.generated
برای اینکه بفهمید هر کدام از اینها به چه معناست:
- connectorId - یک نام منحصر به فرد برای این کانکتور.
- outputDir - مسیری که SDK تولید شده Data Connect در آن ذخیره خواهد شد. این مسیر نسبت به دایرکتوری حاوی فایل connector.yaml است.
- package - نام بستهای که قرار است در SDK تولید شده استفاده شود.
شبیهسازهای Firebase را اجرا کنید
در VS Code، روی دکمهی Start emulators کلیک کنید.
شما باید ببینید که شبیهساز در ترمینال یکپارچه شروع به کار میکند. اگر به درستی شروع به کار کند، باید خروجیای شبیه به این ببینید:
پیکربندی برنامه اندروید برای استفاده از شبیهساز محلی
- اندروید استودیو را باز کنید.
- در صفحه خوشامدگویی اندروید استودیو، روی دکمه Open کلیک کنید و پوشه
codelab-dataconnect-androidرا انتخاب کنید. منتظر بمانید تا Gradle همگامسازی شود. - پس از اتمام همگامسازی Gradle، فایل
app/src/main/java/com/google/firebase/example/dataconnect/MainActivity.ktرا باز کنید وuseEmulator()را فراخوانی کنید:
import com.google.firebase.example.dataconnect.generated.MoviesConnector
import com.google.firebase.example.dataconnect.generated.instance
class MainActivity : ComponentActivity() {
...
// Initialize Firebase Data Connect
MoviesConnector.instance.dataConnect.useEmulator("10.0.2.2", 9399)
...
}
۴. طرحواره را تعریف کنید و پایگاه داده را از قبل پر کنید
در این بخش، ساختار و روابط بین موجودیتهای کلیدی در برنامه فیلم را در یک طرحواره تعریف خواهید کرد. موجودیتهایی مانند Movie ، User و Review به جداول پایگاه داده نگاشت میشوند و روابط آنها با استفاده از دستورالعملهای طرحواره Firebase Data Connect و GraphQL برقرار میشود.
موجودیتهای اصلی و روابط
نوع Movie (Movie type) جزئیات کلیدی مانند عنوان، ژانر و برچسبها را در خود جای داده است که برنامه برای جستجوها و پروفایلهای فیلم از آنها استفاده میکند. نوع User (User type) تعاملات کاربر، مانند نقدها و موارد دلخواه را پیگیری میکند. Review کاربران را به فیلمها متصل میکند و به برنامه اجازه میدهد رتبهبندیها و بازخوردهای ایجاد شده توسط کاربر را نشان دهد.
جدول کاربر
نوع کاربر، یک موجودیت کاربری را تعریف میکند که با گذاشتن نقد یا اضافه کردن فیلم به لیست علاقهمندیها، با فیلمها تعامل دارد.
در VS Code، فایل dataconnect/schema/schema.gql را باز کنید و تعریف جدول User را از حالت کامنت خارج کنید (یا اضافه کنید):
# Users
# Suppose a user can leave reviews for movies
# user -> reviews is a one to many relationship,
# movie -> reviews is a one to many relationship
# movie <-> user is a many to many relationship
type User @table {
id: String! @col(name: "user_auth")
username: String! @col(name: "username", dataType: "varchar(50)")
# The following are generated by the user: User! field in the Review table
# reviews_on_user
# movies_via_Review
}
میز سینما
نوع فیلم، ساختار اصلی یک موجودیت فیلم را تعریف میکند، از جمله فیلدهایی مانند عنوان، ژانر، سال انتشار و رتبهبندی.
در VS Code، فایل dataconnect/schema/schema.gql را باز کنید و تعریف جدول Movie را از حالت کامنت خارج کنید (یا اضافه کنید):
# Movies
type Movie @table {
# The below parameter values are generated by default with @table, and can be edited manually.
# implies directive `@col(name: "movie_id")`, generating a column name
id: UUID! @default(expr: "uuidV4()")
title: String!
imageUrl: String!
genre: String
}
جدول متادیتای فیلم
نوع MovieMetadata یک رابطه یک به یک با نوع Movie برقرار میکند. این نوع شامل دادههای اضافی مانند کارگردان فیلم نیز میشود.
در VS Code، فایل dataconnect/schema/schema.gql را باز کنید و تعریف جدول MovieMetadata را از حالت کامنت خارج کنید (یا اضافه کنید):
# Movie - MovieMetadata is a one-to-one relationship
type MovieMetadata @table {
# @unique indicates a 1-1 relationship
movie: Movie! @unique
# movieId: UUID <- this is created by the above reference
rating: Float
releaseYear: Int
description: String
}
جدول بررسی
نوع Review نشاندهندهی موجودیت نقد است و نوعهای User و Movie را در یک رابطهی چند به چند به هم مرتبط میکند (یک کاربر میتواند نقدهای زیادی بگذارد و هر فیلم میتواند نقدهای زیادی داشته باشد).
در VS Code، فایل dataconnect/schema/schema.gql را باز کنید و تعریف جدول Review را از حالت کامنت خارج کنید (یا اضافه کنید):
# Reviews
type Review @table(name: "Reviews", key: ["movie", "user"]) {
id: UUID! @default(expr: "uuidV4()")
user: User!
movie: Movie!
rating: Int
reviewText: String
reviewDate: Date! @default(expr: "request.time")
}
فیلدهای تولید شده خودکار و پیشفرضها
این طرحواره از عباراتی مانند @default(expr: "uuidV4()") برای تولید خودکار شناسهها و مهرهای زمانی منحصر به فرد استفاده میکند. برای مثال، فیلد id در انواع Movie و Review هنگام ایجاد یک رکورد جدید به طور خودکار با یک UUID پر میشود.
درج دادههای ساختگی
با تعریف طرحواره، اکنون میتوانید پایگاه داده را با دادههای آزمایشی برای آزمایش از قبل پر کنید.
- در VS Code،
dataconnect/moviedata_insert.gqlباز کنید. مطمئن شوید که شبیهسازها در افزونهی Firebase Data Connect در حال اجرا هستند. - شما باید دکمهی «اجرا (محلی)» را در بالای فایل ببینید. برای وارد کردن دادههای فیلم آزمایشی به پایگاه دادهی خود، روی این دکمه کلیک کنید.
- برای تأیید اینکه دادهها با موفقیت اضافه شدهاند، ترمینال Data Connect Execution را بررسی کنید.
با قرار دادن دادهها در جای خود، به مرحله بعدی بروید تا نحوه ایجاد پرسوجوها در Data Connect را بیاموزید.
۵. یک کوئری برای لیست کردن فیلمها ایجاد کنید
با ایجاد یک کوئری برای فهرست کردن فیلمها شروع کنید. برای هر فیلم، شناسه (id)، عنوان (title)، آدرس تصویر (imageUrl) و ژانر (genre) را دریافت خواهید کرد.
پرس و جو را تعریف کنید
در VS Code، فایل dataconnect/connector/queries.gql را باز کنید و کوئری ListMovies را از حالت کامنت خارج کنید (یا اضافه کنید):
query ListMovies @auth(level: PUBLIC) {
movies {
id
title
imageUrl
genre
}
}
برای آزمایش کوئری جدید، روی دکمهی Run (local) کلیک کنید تا کوئری روی پایگاه دادهی محلی شما اجرا شود. لیست فیلمهای موجود در پایگاه داده باید در بخش "result" ترمینال Data Connect Execution نمایش داده شود.
از طریق برنامه اندروید با آن تماس بگیرید
حالا که کوئری را در شبیهساز Data Connect آزمایش کردهاید، وقت آن رسیده که آن را به برنامه اضافه کنید.
در اندروید استودیو، فایل app/src/main/java/com/google/firebase/example/dataconnect/MoviesScreen.kt را باز کنید و کد زیر را برای نمایش لیست فیلمها به صورت شبکهای اضافه کنید:
import com.google.firebase.example.dataconnect.generated.ListMoviesQuery
import com.google.firebase.example.dataconnect.generated.MoviesConnector
import com.google.firebase.example.dataconnect.generated.execute
import com.google.firebase.example.dataconnect.generated.instance
@Composable
fun MoviesScreen(
onMovieClicked: (id: String) -> Unit
) {
var movies by remember { mutableStateOf(emptyList<ListMoviesQuery.Data.MoviesItem>()) }
LaunchedEffect(Unit) {
// Queries need to be executed in a coroutine context
try {
movies = MoviesConnector.instance.listMovies.execute().data.movies
} catch (e: Exception) {
// Will be done at a later step
}
}
LazyVerticalGrid(GridCells.Adaptive(150.dp)) {
items(movies) { movie ->
MovieCard(
movieId = movie.id.toString(),
movieTitle = movie.title,
movieImageUrl = movie.imageUrl,
movieGenre = movie.genre,
onMovieClicked = {
onMovieClicked(movie.id.toString())
}
)
}
}
}
برنامه را اجرا کنید
در اندروید استودیو، روی دکمهی اجرا کلیک کنید تا برنامه در شبیهساز اندروید اجرا شود.
پس از اجرای برنامه، باید صفحهای شبیه به این را ببینید:
۶. کوئری جزئیات فیلم را ایجاد کنید
حالا که برنامه میتواند فیلمها را فهرست کند، بیایید یک کوئری برای نمایش جزئیات هر فیلم ایجاد کنیم.
پرس و جو را تعریف کنید
در VS Code، فایل dataconnect/connector/queries.gql را باز کنید و کوئری GetMovieById را از حالت کامنت خارج کنید (یا اضافه کنید):
# Get movie by id
query GetMovieById($id: UUID!) @auth(level: PUBLIC) {
movie(id: $id) {
id
title
imageUrl
genre
metadata: movieMetadata_on_movie {
rating
releaseYear
description
}
reviews: reviews_on_movie {
id
reviewText
reviewDate
rating
user {
id
username
}
}
}
}
از طریق برنامه اندروید با آن تماس بگیرید
در اندروید استودیو، فایل app/src/main/java/com/google/firebase/example/dataconnect/MovieDetailScreen.kt را باز کنید و کد زیر را اضافه کنید:
importcom.google.firebase.example.dataconnect.generated.GetMovieByIdQuery
importcom.google.firebase.example.dataconnect.generated.MoviesConnector
importcom.google.firebase.example.dataconnect.generated.execute
importcom.google.firebase.example.dataconnect.generated.instance
@Composable
fun MovieDetailScreen(
movieId: String
) {
var movie by remember { mutableStateOf<GetMovieByIdQuery.Data.Movie?>(null) }
LaunchedEffect(Unit) {
movie = MoviesConnector.instance.getMovieById.execute(
UUID.fromString(movieId)
).data.movie
}
if (movie == null) {
LoadingScreen()
} else {
MovieDetails(
movieTitle = movie!!.title,
movieImageUrl = movie!!.imageUrl,
movieGenre = movie!!.genre,
movieRating = movie!!.metadata?.rating,
movieReleaseYear = movie!!.metadata?.releaseYear,
movieDescription = movie!!.metadata?.description,
)
}
}
برنامه را اجرا کنید
در اندروید استودیو، روی دکمهی اجرا کلیک کنید تا برنامه در شبیهساز اندروید اجرا شود.
۷. ایجاد یک جهش برای درج کاربران
حالا که برنامه قادر به نمایش دادهها است، وقت آن رسیده که دادههای جدید را از برنامه اضافه کنیم. برای انجام این کار به صورت ایمن، باید از احراز هویت Firebase استفاده کنید.
برای اهداف این آزمایشگاه کد، برنامه از احراز هویت ناشناس برای ورود کاربران استفاده میکند، اما برای یک برنامه امنتر، استفاده از یک روش احراز هویت متفاوت مانند احراز هویت ایمیل/رمز عبور یا یک ارائهدهنده هویت فدرال را در نظر بگیرید.
جهش را تعریف کنید
در VS Code، فایل dataconnect/connector/mutations.gql را باز کنید و کوئری UpsertUser را از حالت کامنت خارج (یا اضافه) کنید:
# Upsert (update or insert) a user's username based on their auth.uid
mutation UpsertUser($username: String!) @auth(level: USER) {
user_upsert(
data: {
id_expr: "auth.uid"
username: $username
}
)
}
از طریق برنامه اندروید با آن تماس بگیرید
در اندروید استودیو، فایل app/src/main/java/com/google/firebase/example/dataconnect/MainActivity.kt را باز کنید و جهش (mutation) را فراخوانی کنید:
import com.google.firebase.example.dataconnect.generated.execute
LaunchedEffect(Unit) {
// If there's no user signed in, sign in an anonymous user
if (firebaseAuth.currentUser == null) {
firebaseAuth.signInAnonymously().await()
val newUsername = getRandomUsername()
MoviesConnector.instance.upsertUser.execute(newUsername)
}
}
برنامه را اجرا کنید
در اندروید استودیو، روی دکمهی اجرا کلیک کنید تا برنامه در شبیهساز اندروید اجرا شود.
۸. تبریک
تبریک میگوییم، شما با موفقیت Firebase Data Connect را به یک برنامه اندروید اضافه کردید!
اکنون مراحل کلیدی مورد نیاز برای راهاندازی Data Connect، ایجاد کوئریها و جهشها و مدیریت احراز هویت کاربر را میدانید.
قدم بعدی چیست؟
- درباره قیمتگذاری بیشتر بدانید
- درباره ایمنسازی عملیات بیشتر بدانید
- استقرار در محیط عملیاتی (بخش بعدی)
- یاد بگیرید چگونه جستجوی شباهت برداری را انجام دهید
اختیاری: استقرار در محیط عملیاتی
تاکنون این برنامه فقط از شبیهسازهای Firebase استفاده کرده است. اگر میخواهید نحوهی استقرار این برنامه در یک پروژهی Firebase واقعی را بیاموزید، به مرحلهی بعدی بروید.
۹. (اختیاری) برنامه خود را مستقر کنید
تاکنون این برنامه کاملاً محلی بوده است، تمام دادهها در مجموعه شبیهساز Firebase موجود است. در این بخش یاد خواهید گرفت که چگونه پروژه Firebase خود را پیکربندی کنید تا این برنامه در محیط عملیاتی کار کند.
فعال کردن احراز هویت فایربیس
در کنسول Firebase، به بخش Authentication بروید و روی Get started کلیک کنید. به تب Sign-in method بروید و گزینه Anonymous Sign-in را از بین providerها انتخاب کنید.
روش ورود ناشناس را فعال کنید و روی ذخیره کلیک کنید.
طرحواره اتصال داده Firebase را مستقر کنید
مهم: اگر این اولین باری است که یک طرحواره را در پروژه خود مستقر میکنید، این فرآیند یک نمونه Cloud SQL PostgreSQL ایجاد میکند که میتواند حدود ۱۵ دقیقه طول بکشد. تا زمانی که نمونه Cloud SQL آماده و با Firebase Data Connect یکپارچه نشود، نمیتوانید آن را مستقر کنید.
- در رابط کاربری افزونهی Firebase Data Connect VS Code، روی Deploy to production کلیک کنید.
- ممکن است لازم باشد تغییرات طرحواره را بررسی کرده و اصلاحات بالقوه مخرب را تأیید کنید. از شما خواسته میشود:
- بررسی تغییرات طرحواره با استفاده از
firebase dataconnect:sql:diff - وقتی از تغییرات راضی بودید، آنها را با استفاده از جریان آغاز شده توسط
firebase dataconnect:sql:migrateاعمال کنید.
- بررسی تغییرات طرحواره با استفاده از
نمونه Cloud SQL برای PostgreSQL شما با طرحواره و دادههای نهایی پیادهسازی شده بهروزرسانی خواهد شد. میتوانید وضعیت را در کنسول Firebase رصد کنید.
اکنون میتوانید درست مانند کاری که با شبیهسازهای محلی انجام دادید، در پنل Firebase Data Connect روی Run (Production) کلیک کنید تا دادهها را به محیط تولید اضافه کنید.