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

SDK ไคลเอ็นต์ Firebase SQL Connect ช่วยให้คุณเรียกใช้คําขอและ มิวเทชันฝั่งเซิร์ฟเวอร์ได้โดยตรงจากแอป 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.17.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