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

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

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

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

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

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

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

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

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

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

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

  2. ตั้งค่าการสร้าง SDK

    • ด้วยปุ่มเพิ่ม SDK ลงในแอป ในส่วนขยาย SQL Connect VS Code
    • โดยการอัปเดตconnector.yaml

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

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

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

สร้าง SDK ของ Kotlin

ใช้ 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 เพื่อสร้าง SQL Connect SDK ในกระบวนการสร้าง 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:34.14.0"))
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

เริ่มต้น SQL Connect Android SDK

เริ่มต้นอินสแตนซ์ 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 สามารถเข้าถึงได้

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

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

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

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

SDK ที่สร้างขึ้นบังคับให้จัดการค่าที่ไม่รู้จัก เนื่องจากโค้ดของลูกค้าต้อง แกะออบเจ็กต์ EnumValue ซึ่งอาจเป็น EnumValue.Known สําหรับค่าการแจกแจงที่รู้จัก หรือ 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 พารามิเตอร์ ซึ่งทั้ง 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 ใน SQL Connect SDK

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

    SQL Connect ประเภท Kotlin
    สตริง สตริง
    Int Int (จำนวนเต็มแบบ 32 บิต)
    ลอยขึ้นมา Double (ทศนิยมแบบ 64 บิต)
    บูลีน บูลีน
    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