פיתוח באמצעות Firebase Data Connect (ל-Android)

1. סקירה כללית

ddc52cd46f923cf1.png

ב-codelab הזה תלמדו לשלב את Firebase Data Connect עם מסד נתונים של Cloud SQL כדי ליצור אפליקציה ל-Android עם ביקורות על סרטים. במהלך הקודלה תלמדו:

  • כתיבת סכימה של GraphQL ל-Firebase Data Connect
  • כתיבת שאילתות ומוטציות
  • הטמעת אימות משתמשים לאבטחת הנתונים

דרישות מוקדמות

  • הגרסה האחרונה של Android Studio
  • אמולטור Android עם רמת API ‏23 ואילך

מה תלמדו

  • איך מגדירים את Firebase Data Connect באמצעות אמולטורים מקומיים.
  • איך מעצבים סכימת נתונים באמצעות Data Connect ו-GraphQL.
  • איך לכתוב שאילתות ומוטציות לאפליקציה של ביקורות על סרטים.
  • איך יוצרים את Kotlin SDK ומשתמשים בו באפליקציית Android.
  • (אופציונלי) איך לפרוס שירות Data Connect בסביבת הייצור.

2. הגדרת פרויקט לדוגמה

יצירת פרויקט Firebase

  1. נכנסים למסוף Firebase באמצעות חשבון Google.
  2. במסוף Firebase, לוחצים על 'הוספת פרויקט'.
  3. נותנים שם לפרויקט ב-Firebase (לדוגמה, 'ביקורת סרטים') ולוחצים על 'המשך'.
  4. יכול להיות שתתבקשו להפעיל את Google Analytics. לצורכי הקודלאב הזה, הבחירה שלכם לא חשובה.
  5. אחרי דקה בערך, פרויקט Firebase יהיה מוכן. לחץ על 'המשך'.

מורידים את הקוד

מריצים את הפקודה הבאה כדי לשכפל את קוד הדוגמה של סדנת הקוד הזו. הפקודה הזו תיצור ספרייה בשם codelab-dataconnect-android במחשב:

git clone https://github.com/firebaseextended/codelab-dataconnect-android.git

אם אין לכם את git במחשב, אתם יכולים גם להוריד את הקוד ישירות מ-GitHub.

הוספת הגדרות של Firebase

  1. במסוף Firebase, בוחרים באפשרות 'סקירה כללית של הפרויקט' בתפריט הניווט הימני. לוחצים על הלחצן של Android כדי לבחור את הפלטפורמה. כשמוצגת בקשה להזין שם חבילה, מזינים com.google.firebase.example.dataconnect
  2. לוחצים על 'רישום אפליקציה' ופועלים לפי ההוראות כדי להוריד את הקובץ google-services.json ולהעביר אותו לתיקייה app/ של הקוד שהורדתם. לאחר מכן לוחצים על 'הבא'.

3. הגדרת Data Connect

התקנה

התקנה אוטומטית

מריצים את הפקודה הבאה בספרייה codelab-dataconnect-android:

curl -sL https://firebase.tools/dataconnect | bash

הסקריפט הזה מנסה להגדיר את סביבת הפיתוח ולהפעיל סביבת פיתוח משולבת (IDE) מבוססת-דפדפן. סביבת הפיתוח המשולבת הזו מספקת כלים, כולל תוסף מובנה מראש ל-VS Code, שיעזרו לכם לנהל את הסכימה ולהגדיר שאילתות ומוטציות לשימוש באפליקציה, וגם ליצור ערכות SDK עם סוגים מוגדרים.

אחרי הרצת הסקריפט, VS Code אמור להיפתח באופן אוטומטי.

הערה: אם כבר התקנתם את גרסת המחשב של VS Code, הסקריפט אמור לפתוח אותו באופן אוטומטי. אם הסקריפט נכשל, יש לפעול לפי השלבים להטמעה ידנית שמפורטים בהמשך.

התקנה ידנית

  1. התקנת Visual Studio Code
  2. התקנה של Node.js
  3. ב-VS Code, פותחים את הספרייה codelab-dataconnect-android.
  4. מתקינים את התוסף Firebase Data Connect מ-Visual Studio Code Marketplace.

איך מפעילים את Data Connect בפרויקט

בחלונית הימנית, לוחצים על סמל Firebase כדי לפתוח את ממשק המשתמש של התוסף Data Connect ל-VS Code:

  1. לוחצים על הלחצן כניסה באמצעות חשבון Google. ייפתח חלון דפדפן. פועלים לפי ההוראות כדי להיכנס לתוסף באמצעות חשבון Google. ef59f25a9e9cbfff.png
  2. לוחצים על הלחצן Connect a Firebase project (קישור פרויקט Firebase) ובוחרים את הפרויקט שיצרתם קודם במסוף. 951a836ba0682494.png

לוחצים על הלחצן 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.

93fb67962e96a7cb.png

האמולטור אמור להתחיל לפעול במסוף המשולב. אם הוא מתחיל כמו שצריך, הפלט אמור להיראות כך:

8504ae0080923823.png

הגדרת האפליקציה ל-Android לשימוש במהדורת האדמין המקומית

  1. פותחים את Android Studio.
  2. במסך הפתיחה של Android Studio, לוחצים על הלחצן Open (פתיחה) ובוחרים בספרייה codelab-dataconnect-android. ממתינים לסנכרון של Gradle.
  3. בסיום הסנכרון של 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)

  ...
}

4. הגדרת הסכימה ויישוב מראש של מסד הנתונים

בקטע הזה מגדירים את המבנה ואת היחסים בין ישויות המפתח באפליקציית הסרטים בסכימה. ישויות כמו Movie,‏ User ו-Review ממפות לטבלאות של מסדי נתונים, והיחסים נוצרים באמצעות Firebase Data Connect והוראות הסכימה של GraphQL.

ישויות ויחסים בסיסיים

הסוג Movie מכיל פרטים חשובים כמו כותרת, ז'אנר ותגים, שהאפליקציה משתמשת בהם בחיפושים ובפרופילים של סרטים. הסוג User עוקב אחרי אינטראקציות של משתמשים, כמו ביקורות ומועדפים. 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
}

טבלת סרטים

הסוג Movie מגדיר את המבנה הראשי של ישות סרט, כולל שדות כמו title,‏ genre,‏ releaseYear ו-rating.

ב-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

הסוג 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
}

טבלת הבדיקה

הסוג 'ביקורת' מייצג את הישות של הביקורת ומקשר בין הסוגים 'משתמש' ו'סרט' ביחסות 'הרבה לרבים' (משתמש אחד יכול להשאיר הרבה ביקורות, וכל סרט יכול לכלול הרבה ביקורות).

ב-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 כשיוצרים רשומה חדשה.

הוספת נתונים מדומים

אחרי שמגדירים את הסכימה, אפשר לאכלס מראש את מסד הנתונים בנתונים מדומים לצורך בדיקה.

  1. פותחים את dataconnect/moviedata_insert.gql ב-VS Code. מוודאים שהמעבדים הווירטואליים בתוסף Firebase Data Connect פועלים.
  2. בחלק העליון של הקובץ אמור להופיע הלחצן Run (local). לוחצים עליו כדי להוסיף את נתוני הסרט המדומה למסד הנתונים.

b070f025e573ab9b.png

  1. בודקים את מסוף הביצוע של Data Connect כדי לוודא שהנתונים נוספו בהצלחה.

e2058cb4db857058.png

אחרי שמוסיפים את הנתונים, עוברים לשלב הבא כדי ללמוד איך יוצרים שאילתות ב-Data Connect.

5. יצירת שאילתה להצגת רשימת סרטים

קודם כול יוצרים שאילתה להצגת רשימת סרטים. לכל סרט, תצטרכו לאחזר את המזהה, הכותרת, imageUrl והז'אנר.

הגדרת השאילתה

ב-VS Code, פותחים את הקובץ dataconnect/connector/queries.gql ומבטלים את ההערה (או מוסיפים אותה) לשאילתה ListMovies:

query ListMovies @auth(level: PUBLIC) {
  movies {
    id
    title
    imageUrl
    genre
  }
}

כדי לבדוק את השאילתה החדשה, לוחצים על הלחצן Run (local) (הפעלה (מקומית)) כדי להריץ את השאילתה במסד הנתונים המקומי. רשימת הסרטים מהמסד הנתונים אמורה להופיע בקטע 'result' (תוצאה) במסוף Data Connect Execution.

822bf32321df4716.png

איך מתקשרים אליו דרך אפליקציית Android

אחרי שבדקתם את השאילתה במהדמנת Data Connect, הגיע הזמן להוסיף אותה לאפליקציה.

ב-Android Studio, פותחים את הקובץ 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())
                }
            )
        }
    }
}

הפעלת האפליקציה

ב-Android Studio, לוחצים על הלחצן Run כדי להפעיל את האפליקציה במהדמנת Android.

אחרי שהאפליקציה תושק, אמור להופיע מסך שנראה כך:

ddc52cd46f923cf1.png

6. יצירת השאילתה של פרטי הסרט

עכשיו, כשהאפליקציה יכולה להציג רשימת סרטים, נוצרת שאילתה כדי להציג את הפרטים של כל סרט.

הגדרת השאילתה

ב-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
      }
    }
  }
}

איך מתקשרים אליו דרך אפליקציית Android

ב-Android Studio, פותחים את הקובץ 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,
        )
    }
}

הפעלת האפליקציה

ב-Android Studio, לוחצים על הלחצן Run כדי להפעיל את האפליקציה במהדמנת Android.

7. יצירת מוטציה להוספת משתמשים

עכשיו, כשהאפליקציה יכולה להציג נתונים, הגיע הזמן להוסיף נתונים חדשים מהאפליקציה. כדי לעשות זאת בצורה מאובטחת, צריך להשתמש באימות של 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
    }
  )
}

איך מתקשרים אליו דרך אפליקציית Android

ב-Android Studio, פותחים את הקובץ app/src/main/java/com/google/firebase/example/dataconnect/MainActivity.kt ומפעילים את המוטציה:

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)
  }
}

הפעלת האפליקציה

ב-Android Studio, לוחצים על הלחצן Run כדי להפעיל את האפליקציה במהדמנת Android.

8. מזל טוב

הוספת Firebase Data Connect לאפליקציה ל-Android הושלמה בהצלחה.

עכשיו אתם יודעים מהם השלבים העיקריים להגדרת Data Connect, ליצירת שאילתות ומוטציות ולטיפול באימות משתמשים.

המאמרים הבאים

אופציונלי: פריסה בסביבת הייצור

עד כה, האפליקציה הזו השתמשה רק במהדמנים של Firebase. כדי ללמוד איך לפרוס את האפליקציה הזו בפרויקט Firebase אמיתי, ממשיכים לשלב הבא.

9. (אופציונלי) פריסת האפליקציה

עד כה האפליקציה הזו הייתה מקומית לחלוטין, וכל הנתונים נכללים ב-Firebase Emulator Suite. בקטע הזה תלמדו איך להגדיר את פרויקט Firebase כך שהאפליקציה הזו תפעל בסביבת הייצור.

הפעלת אימות ב-Firebase

במסוף Firebase, עוברים לקטע Authentication ולוחצים על Get started. עוברים לכרטיסייה 'שיטת כניסה' ובוחרים באפשרות 'כניסה אנונימית' מהספקים.

מפעילים את שיטת הכניסה האנונימית ולוחצים על 'שמירה'.

פריסה של הסכימה של Firebase Data Connect

חשוב: אם זו הפעם הראשונה שאתם פורסים סכימה בפרויקט, התהליך הזה ייצור מכונה של PostgreSQL ב-Cloud SQL. התהליך עשוי להימשך כ-15 דקות. לא תוכלו לפרוס את הקוד עד שהמכונה של Cloud SQL תהיה מוכנה ותשולב עם Firebase Data Connect.

  1. בממשק המשתמש של התוסף של Firebase Data Connect ל-VS Code, לוחצים על פריסה בסביבת הייצור.
  2. יכול להיות שתצטרכו לבדוק שינויים בסכימה ולאשר שינויים שעלולים להיות הרסניים. תתבקשו:
    • בדיקת השינויים בסכימה באמצעות firebase dataconnect:sql:diff
    • כשמרוצים מהשינויים, מחילים אותם באמצעות התהליך שהתחיל ב-firebase dataconnect:sql:migrate

המכונה של Cloud SQL for PostgreSQL תתעדכן עם הסכימה והנתונים הסופיים שנפרסו. אפשר לעקוב אחרי הסטטוס במסוף Firebase.

עכשיו אפשר ללחוץ על 'הפעלה (ייצור)' בחלונית של Firebase Data Connect, בדיוק כמו שעשיתם עם המהדמנים המקומיים, כדי להוסיף נתונים לסביבת הייצור.