SDK ไคลเอ็นต์ Firebase SQL Connect ช่วยให้คุณเรียกใช้คําขอและ Mutation ฝั่งเซิร์ฟเวอร์ได้โดยตรงจากแอป Firebase คุณสร้าง SDK ไคลเอ็นต์ที่กําหนดเองแบบ ขนานไปกับการออกแบบสคีมา คําขอ และ Mutation ที่คุณทําให้ใช้งานได้ในบริการ SQL Connect จากนั้นผสานรวมเมธอดจาก SDK นี้เข้ากับตรรกะไคลเอ็นต์
ดังที่เราได้กล่าวไว้ในส่วนอื่นๆ สิ่งสําคัญที่ควรทราบคือSQL Connect โค้ดไคลเอ็นต์ไม่ได้ส่งคําขอและ Mutation และไม่ได้ดำเนินการบน เซิร์ฟเวอร์ แต่เมื่อทําให้ใช้งานได้ ระบบจะจัดเก็บการดําเนินการ SQL Connect ไว้ใน เซิร์ฟเวอร์เหมือนกับ Cloud Functions ซึ่งหมายความว่าคุณต้องทําให้การเปลี่ยนแปลงฝั่งไคลเอ็นต์ที่เกี่ยวข้องใช้งานได้เพื่อหลีกเลี่ยงไม่ให้ผู้ใช้เดิมได้รับผลกระทบ (เช่น ในแอปเวอร์ชันเก่า)
ด้วยเหตุนี้ SQL Connect จึงมีสภาพแวดล้อมและ เครื่องมือสําหรับนักพัฒนาแอปที่ช่วยให้คุณสร้างต้นแบบสคีมา คําขอ และ Mutation ที่ทําให้ใช้งานได้ในเซิร์ฟเวอร์ นอกจากนี้ยังสร้าง SDK ฝั่งไคลเอ็นต์โดยอัตโนมัติขณะที่คุณสร้างต้นแบบ
เมื่อคุณอัปเดตบริการและแอปไคลเอ็นต์ซ้ำๆ การอัปเดตทั้งฝั่งเซิร์ฟเวอร์และฝั่งไคลเอ็นต์ก็จะพร้อมใช้งาน
เวิร์กโฟลว์การพัฒนาไคลเอ็นต์คืออะไร
หากคุณทำตามคู่มือเริ่มต้นใช้งาน คุณจะได้เห็นภาพรวมของขั้นตอนการพัฒนาสำหรับ SQL Connect ในคู่มือนี้ คุณจะได้ดูข้อมูลโดยละเอียดเพิ่มเติมเกี่ยวกับการสร้าง SDK ของ Android จากสคีมา รวมถึงการใช้คําขอและ Mutation ของไคลเอ็นต์
สรุปได้ว่าหากต้องการใช้ SDK ของ Android ที่สร้างขึ้นในแอปไคลเอ็นต์ คุณจะต้องทำตามขั้นตอนเบื้องต้นต่อไปนี้
- เพิ่ม Firebase ลงในแอป Android
- กำหนดค่า SQL Connect เป็นทรัพยากร Dependency ใน Gradle
- เพิ่มปลั๊กอิน Kotlin Serialization Gradle และทรัพยากร Dependency ของ Gradle
จากนั้นทำดังนี้
- พัฒนาสคีมาของแอป
ตั้งค่าการสร้าง SDK โดยทำดังนี้
- ใช้ปุ่มเพิ่ม SDK ลงในแอป ในส่วนขยาย SQL Connect VS Code
- โดย การอัปเดต
connector.yaml
ตั้งค่าและใช้โปรแกรมจำลอง 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.13.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
ใช้คําขอและ Mutation จาก Android SDK
ออบเจ็กต์เครื่องมือเชื่อมต่อช่วยให้คุณเรียกใช้คําขอและ Mutation ได้ตามที่กําหนดไว้ในซอร์สโค้ด 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
จัดการการเปลี่ยนแปลงในช่องการแจกแจง
สคีมาของแอปอาจมีการแจกแจง ซึ่งคําขอ 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จะยังคงอยู่แม้จะรีสตาร์ทแอป ใน SDK ของ Android ค่าเริ่มต้นคือ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 บิต) บูลีน บูลีน 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