ใช้ 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.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

ใช้คําขอและมิวเทชันจาก 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

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

สคีมาของแอปอาจมีการแจกแจง ซึ่งคําขอ 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
  สตริง	สตริง
  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