ใช้ Android SDK ที่สร้างขึ้น

SDK ของไคลเอ็นต์ Firebase SQL Connect ช่วยให้คุณเรียกใช้การค้นหาและการเปลี่ยนแปลงฝั่งเซิร์ฟเวอร์ได้โดยตรงจากแอป Firebase คุณสร้าง SDK ของไคลเอ็นต์ที่กำหนดเองควบคู่ไปกับการออกแบบสคีมา การค้นหา และการเปลี่ยนแปลงที่ติดตั้งใช้งานในบริการ SQL Connect จากนั้นคุณจะผสานรวมเมธอดจาก SDK นี้เข้ากับตรรกะไคลเอ็นต์

ดังที่เราได้กล่าวไว้ในที่อื่น สิ่งสำคัญที่ควรทราบคือSQL Connect โค้ดฝั่งไคลเอ็นต์ไม่ได้ส่งการค้นหาและการเปลี่ยนแปลง และไม่ได้ดำเนินการบนเซิร์ฟเวอร์ แต่เมื่อติดตั้งใช้งาน ระบบจะจัดเก็บการดำเนินการ SQL Connect ไว้ในเซิร์ฟเวอร์ เช่น Cloud Functions ซึ่งหมายความว่าคุณต้องติดตั้งใช้งานการเปลี่ยนแปลงฝั่งไคลเอ็นต์ที่เกี่ยวข้องเพื่อหลีกเลี่ยงไม่ให้ผู้ใช้เดิมได้รับผลกระทบ (เช่น ในแอปเวอร์ชันเก่า)

ด้วยเหตุนี้ SQL Connect จึงมีสภาพแวดล้อมในการพัฒนาซอฟต์แวร์และเครื่องมือที่ช่วยให้คุณสร้างต้นแบบสคีมา คำค้นหา และการเปลี่ยนแปลงที่ติดตั้งใช้งานบนเซิร์ฟเวอร์ได้ นอกจากนี้ยังสร้าง SDK ฝั่งไคลเอ็นต์โดยอัตโนมัติขณะที่คุณสร้างต้นแบบ

เมื่อคุณอัปเดตบริการและแอปไคลเอ็นต์ซ้ำแล้ว การอัปเดตทั้งฝั่งเซิร์ฟเวอร์และฝั่งไคลเอ็นต์ก็พร้อมที่จะทำให้ใช้งานได้

เวิร์กโฟลว์การพัฒนาไคลเอ็นต์คืออะไร

หากทำตามขั้นตอนในเริ่มต้นใช้งาน คุณจะเห็นขั้นตอนการพัฒนาโดยรวมสำหรับ SQL Connect ในคู่มือนี้ คุณจะพบข้อมูลโดยละเอียดเพิ่มเติมเกี่ยวกับการสร้าง Android SDK จากสคีมาและการทำงานกับการค้นหาและการเปลี่ยนแปลงของไคลเอ็นต์

โดยสรุปแล้ว หากต้องการใช้ Android SDK ที่สร้างขึ้นในแอปไคลเอ็นต์ คุณจะต้องทำตามขั้นตอนที่จำเป็นต่อไปนี้

  1. เพิ่ม Firebase ลงในแอป Android
  2. กำหนดค่า SQL Connect เป็นทรัพยากร Dependency ใน Gradle
  3. เพิ่มปลั๊กอิน Kotlin Serialization Gradle และทรัพยากร Dependency ของ Gradle

จากนั้นให้ทำดังนี้

  1. พัฒนาสคีมาแอป

  2. ตั้งค่าการสร้าง SDK โดยทำดังนี้

  3. เริ่มต้นโค้ดไคลเอ็นต์และนำเข้าไลบรารี

  4. ใช้การเรียกใช้การค้นหาและการเปลี่ยนแปลง

  5. ตั้งค่าและใช้โปรแกรมจำลอง SQL Connect และทำซ้ำ

สร้าง Kotlin SDK

ใช้ Firebase CLI เพื่อตั้งค่า 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 ไว้ในโค้ดฝั่งไคลเอ็นต์

หากต้องการตั้งค่าโค้ดไคลเอ็นต์เพื่อใช้ SQL Connect และ SDK ที่สร้างขึ้น ให้ทำตามวิธีการตั้งค่า Firebase มาตรฐานก่อน

จากนั้นเพิ่มโค้ดต่อไปนี้ลงในส่วน plugins ใน app/build.gradle.kts

// The Firebase team tests with version 1.8.22; however, other 1.8 versions,
// and all newer versions are expected work too.
kotlin("plugin.serialization") version "1.8.22" // MUST match the version of the Kotlin compiler

จากนั้นเพิ่มโค้ดต่อไปนี้ลงในส่วน dependencies ใน app/build.gradle.kts

implementation(platform("com.google.firebase:firebase-bom:35.0.1"))
implementation("com.google.firebase:firebase-dataconnect")
implementation("com.google.firebase:firebase-auth") // Optional
implementation("com.google.firebase:firebase-appcheck") // Optional
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3") // Newer versions should work too
implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1") // Newer versions should work too

เริ่มต้นใช้งาน Android SDK ของ SQL Connect

เริ่มต้นอินสแตนซ์ SQL Connect โดยใช้ข้อมูลที่คุณใช้ตั้งค่า SQL Connect ดูข้อมูลนี้ได้ในหน้าฐานข้อมูลและพื้นที่เก็บข้อมูล > SQL Connect ของคอนโซล Firebase

ออบเจ็กต์ ConnectorConfig

SDK ต้องใช้ออบเจ็กต์การกำหนดค่าเครื่องมือเชื่อมต่อ

ออบเจ็กต์นี้สร้างขึ้นโดยอัตโนมัติจาก serviceId และ location ใน dataconnect.yaml และ connectorId ใน connector.yaml

การรับอินสแตนซ์เครื่องมือเชื่อมต่อ

เมื่อตั้งค่าออบเจ็กต์การกำหนดค่าแล้ว ให้รับอินสแตนซ์เครื่องมือเชื่อมต่อ SQL Connect โค้ดสำหรับเครื่องมือเชื่อมต่อจะสร้างขึ้นโดยโปรแกรมจำลอง SQL Connect หากชื่อเครื่องมือเชื่อมต่อของคุณคือ movies และแพ็กเกจ Kotlin คือ com.myapplication ตามที่ระบุไว้ใน connector.yaml ให้ดึงข้อมูลออบเจ็กต์เครื่องมือเชื่อมต่อโดยเรียกใช้คำสั่งต่อไปนี้

val connector = com.myapplication.MoviesConnector.instance

ใช้การค้นหาและการเปลี่ยนแปลงจาก Android SDK

ออบเจ็กต์เครื่องมือเชื่อมต่อช่วยให้คุณเรียกใช้การค้นหาและการเปลี่ยนแปลงตามที่กำหนดไว้ในซอร์สโค้ด 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
  }
}

คุณจะสร้างและเรียกดูภาพยนตร์ได้ดังนี้

val connector = MoviesConnector.instance

val addMovieResult1 = connector.createMovie.execute(
  title = "Empire Strikes Back",
  releaseYear = 1980,
  genre = "Sci-Fi",
  rating = 5
)

val movie1 = connector.getMovieByKey.execute(addMovieResult1.data.key)

println("Empire Strikes Back: ${movie1.data.movie}")

นอกจากนี้ คุณยังดึงข้อมูลภาพยนตร์หลายเรื่องได้ด้วย โดยทำดังนี้

val connector = MoviesConnector.instance

val addMovieResult2 = connector.createMovie.execute(
  title="Attack of the Clones",
  releaseYear = 2002,
  genre = "Sci-Fi",
  rating = 5
)

val listMoviesResult = connector.listMoviesByGenre.execute(genre = "Sci-Fi")

println(listMoviesResult.data.movies)

นอกจากนี้ คุณยังรวบรวม Flow ที่จะสร้างผลลัพธ์เมื่อมีการดึงข้อมูลผลการค้นหาใหม่โดยใช้การเรียกเมธอด execute() ของการค้นหาได้ด้วย

val connector = MoviesConnector.instance

connector.listMoviesByGenre.flow(genre = "Sci-Fi").collect { data ->
  println(data.movies)
}

connector.createMovie.execute(
  title="A New Hope",
  releaseYear = 1977,
  genre = "Sci-Fi",
  rating = 5
)

connector.listMoviesByGenre.execute(genre = "Sci-Fi") // will cause the Flow to get notified

สมัครรับข้อมูลการเปลี่ยนแปลงแบบเรียลไทม์

ดูรับข้อมูลอัปเดตแบบเรียลไทม์จาก SQL Connect

จัดการการเปลี่ยนแปลงในช่องการแจงนับ

สคีมาของแอปสามารถมีการแจงนับ ซึ่งเข้าถึงได้โดยการค้นหา GraphQL

เมื่อการออกแบบของแอปเปลี่ยนไป คุณอาจเพิ่มค่าที่รองรับ enum ใหม่ ตัวอย่างเช่น สมมติว่าในวงจรของแอปพลิเคชันในภายหลัง คุณตัดสินใจเพิ่มค่า FULLSCREEN ลงใน enum AspectRatio

ในเวิร์กโฟลว์ SQL Connect คุณสามารถใช้เครื่องมือสำหรับนักพัฒนาซอฟต์แวร์ในเครื่องเพื่ออัปเดตการค้นหาและ SDK

อย่างไรก็ตาม ก่อนที่คุณจะเผยแพร่ไคลเอ็นต์เวอร์ชันอัปเดต ไคลเอ็นต์เวอร์ชันเก่าที่ติดตั้งใช้งานอาจใช้งานไม่ได้

ตัวอย่างการใช้งานที่ยืดหยุ่น

SDK ที่สร้างขึ้นจะบังคับให้จัดการค่าที่ไม่รู้จัก เนื่องจากโค้ดของลูกค้าต้องแยกออบเจ็กต์ EnumValue ซึ่งเป็น EnumValue.Known สำหรับค่า enum ที่รู้จัก หรือ EnumValue.Unknown สำหรับค่าที่ไม่รู้จัก

val result = connector.listMoviesByAspectRatio.execute(AspectRatio.WIDESCREEN)
val encounteredAspectRatios = mutableSetOf<String>()

result.data.movies
  .mapNotNull { it.otherAspectRatios }
  .forEach { otherAspectRatios ->
    otherAspectRatios
      .filterNot { it.value == AspectRatio.WIDESCREEN }
      .forEach {
        when (it) {
          is EnumValue.Known -> encounteredAspectRatios.add(it.value.name)
          is EnumValue.Unknown ->
            encounteredAspectRatios.add("[unknown ratio: ${it.stringValue}]")
        }
      }
  }

println(
  "Widescreen movies also include additional aspect ratios: " +
    encounteredAspectRatios.sorted().joinToString()
)

เปิดใช้การแคชฝั่งไคลเอ็นต์

SQL Connect มีฟีเจอร์การแคชฝั่งไคลเอ็นต์ที่ไม่บังคับ ซึ่งคุณเปิดใช้ได้โดยแก้ไขไฟล์ connector.yaml เมื่อเปิดใช้ฟีเจอร์นี้ SDK ไคลเอ็นต์ที่สร้างขึ้นจะแคชการตอบกลับการค้นหาไว้ในเครื่อง ซึ่งจะช่วยลดจำนวนคำขอฐานข้อมูลที่แอปสร้างขึ้น และช่วยให้ส่วนที่ขึ้นอยู่กับฐานข้อมูลของแอปทำงานได้เมื่อความพร้อมใช้งานของเครือข่ายถูกขัดจังหวะ

หากต้องการเปิดใช้การแคชฝั่งไคลเอ็นต์ ให้เพิ่มการกำหนดค่าการแคชฝั่งไคลเอ็นต์ลงในการกำหนดค่าเครื่องมือเชื่อมต่อ โดยทำดังนี้

generate:
  kotlinSdk:
    outputDir: "../android"
    package: "com.google.firebase.dataconnect.generated"
    clientCache:
      maxAge: 5s
      storage: persistent

การกำหนดค่านี้มีพารามิเตอร์ 2 รายการ ซึ่งไม่บังคับทั้งคู่ ได้แก่

  • maxAge: อายุสูงสุดที่การตอบกลับที่แคชไว้สามารถมีได้ก่อนที่ SDK ของไคลเอ็นต์จะดึงค่าใหม่ ตัวอย่างเช่น "0", "30s", "1h30m"

    ค่าเริ่มต้นสำหรับ maxAge คือ 0 ซึ่งหมายความว่าระบบจะแคชการตอบกลับ แต่ SDK ของไคลเอ็นต์จะดึงข้อมูลค่าใหม่เสมอ ระบบจะใช้ค่าที่แคชไว้เมื่อระบุ CACHE_ONLY เป็น execute() เท่านั้น

  • storage: คุณสามารถกำหนดค่า SDK ของไคลเอ็นต์ให้แคชการตอบกลับในพื้นที่เก็บข้อมูล persistent หรือใน memory ได้ ผลลัพธ์ที่แคชไว้ในพื้นที่เก็บข้อมูล persistent จะยังคงอยู่แม้จะรีสตาร์ทแอป ใน Android SDK ค่าเริ่มต้นคือ persistent

หลังจากอัปเดตการกำหนดค่าการแคชของเครื่องมือเชื่อมต่อแล้ว ให้สร้าง SDK ของไคลเอ็นต์ใหม่และสร้างแอปอีกครั้ง เมื่อดำเนินการเสร็จแล้ว execute() จะแคชการตอบกลับและใช้ค่าที่แคชไว้ตามนโยบายที่คุณกำหนดค่าไว้ โดยทั่วไปแล้ว การดำเนินการนี้จะเกิดขึ้นโดยอัตโนมัติโดยที่คุณไม่ต้องดำเนินการใดๆ เพิ่มเติม แต่โปรดทราบข้อมูลต่อไปนี้

  • ลักษณะการทำงานเริ่มต้นของ execute() เป็นไปตามที่อธิบายไว้ข้างต้น กล่าวคือ หากมีการแคชผลลัพธ์สำหรับคำค้นหาและค่าที่แคชไว้ไม่เก่ากว่า maxAge ระบบจะใช้ค่าที่แคชไว้ ลักษณะการทำงานเริ่มต้นนี้เรียกว่านโยบาย PREFER_CACHE

    นอกจากนี้ คุณยังระบุการเรียกใช้ execute() แต่ละครั้งให้แสดงเฉพาะค่าที่แคชไว้ (CACHE_ONLY) หรือดึงข้อมูลค่าใหม่จากเซิร์ฟเวอร์โดยไม่มีเงื่อนไข (SERVER_ONLY) ได้ด้วย

    val queryResult = queryRef.execute(QueryRef.FetchPolicy.CACHE_ONLY)

    val queryResult = queryRef.execute(QueryRef.FetchPolicy.SERVER_ONLY)

    สร้างต้นแบบและทดสอบแอปพลิเคชัน Android

    เครื่องมือไคลเอ็นต์เพื่อใช้โปรแกรมจำลองในเครื่อง

    คุณสามารถใช้โปรแกรมจำลอง SQL Connect ไม่ว่าจะจากส่วนขยาย SQL Connect VS Code หรือจาก CLI

    การใช้เครื่องมือในแอปเพื่อเชื่อมต่อกับโปรแกรมจำลองจะเหมือนกันสำหรับทั้ง 2 สถานการณ์

    val connector = MoviesConnector.instance

// Connect to the emulator on "10.0.2.2:9399"
connector.dataConnect.useEmulator()

// (alternatively) if you're running your emulator on non-default port:
connector.dataConnect.useEmulator(port = 9999)

// Make calls from your app

    หากต้องการเปลี่ยนไปใช้ทรัพยากรเวอร์ชันที่ใช้งานจริง ให้ทำเครื่องหมายบรรทัดสำหรับการเชื่อมต่อกับโปรแกรมจำลองเป็นความคิดเห็น

    ประเภท SQL ใน SDK ของ SQL Connect

    SQL Connect เซิร์ฟเวอร์แสดงประเภทข้อมูล GraphQL ทั่วไปและแบบกำหนดเอง ซึ่งจะแสดงใน SDK ดังนี้

    ประเภท SQL Connect Kotlin
    สตริง สตริง
    Int Int (จำนวนเต็ม 32 บิต)
    ทศนิยม Double (64-bit float)
    บูลีน บูลีน
    UUID java.util.UUID
    วันที่ com.google.firebase.dataconnect.LocalDate (เดิมคือ java.util.Date จนถึง 16.0.0-beta03)
    การประทับเวลา com.google.firebase.Timestamp
    Int64 ยาว
    เวลาใดก็ได้ com.google.firebase.dataconnect.AnyValue