ใช้ 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 เพื่อสร้าง 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:34.19.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 ใน SDK SQL Connect

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

  SQL Connect ประเภท	Kotlin
  String	String
  Int	Int (จำนวนเต็มแบบ 32 บิต)
  Float	Double (ทศนิยมแบบ 64 บิต)
  Boolean	Boolean
  UUID	java.util.UUID
  Date	com.google.firebase.dataconnect.LocalDate (เดิมคือ java.util.Date จนถึงเวอร์ชัน 16.0.0-beta03)
  Timestamp	com.google.firebase.Timestamp
  Int64	Long
  Any	com.google.firebase.dataconnect.AnyValue