Firebase SQL Connect SDK ไคลเอ็นต์ช่วยให้คุณเรียกใช้การค้นหาและ การเปลี่ยนแปลงฝั่งเซิร์ฟเวอร์ได้โดยตรงจากแอป Firebase คุณสร้าง SDK ไคลเอ็นต์ที่กำหนดเองแบบ ขนานไปกับการออกแบบสคีมา การค้นหา และการเปลี่ยนแปลงที่คุณทำให้ SQL Connect ใช้งานได้ จากนั้นผสานรวมเมธอดจาก SDK นี้เข้ากับตรรกะไคลเอ็นต์
ดังที่เราได้กล่าวไว้ในส่วนอื่นๆ สิ่งสำคัญที่ควรทราบคือSQL Connect โค้ดไคลเอ็นต์ไม่ได้ส่งการค้นหาและการเปลี่ยนแปลง และไม่ได้ดำเนินการบน เซิร์ฟเวอร์ แต่เมื่อทำให้ใช้งานได้ ระบบจะจัดเก็บการดำเนินการ SQL Connect ไว้ใน เซิร์ฟเวอร์เหมือนกับ Cloud Functions ซึ่งหมายความว่าคุณต้องทำให้การเปลี่ยนแปลงฝั่งไคลเอ็นต์ที่เกี่ยวข้องใช้งานได้เพื่อหลีกเลี่ยงไม่ให้ผู้ใช้เดิมได้รับผลกระทบ (เช่น ในแอปเวอร์ชันเก่า)
ด้วยเหตุนี้ SQL Connect จึงมีสภาพแวดล้อมและ เครื่องมือสำหรับนักพัฒนาแอปที่ช่วยให้คุณสร้างต้นแบบสคีมา การค้นหา และการเปลี่ยนแปลงที่ทำให้ใช้งานได้ในเซิร์ฟเวอร์ นอกจากนี้ยังสร้าง SDK ฝั่งไคลเอ็นต์โดยอัตโนมัติขณะที่คุณสร้างต้นแบบ
เมื่อคุณอัปเดตบริการและแอปไคลเอ็นต์ซ้ำๆ การอัปเดตทั้งฝั่งเซิร์ฟเวอร์และฝั่งไคลเอ็นต์ก็จะพร้อมใช้งาน
เวิร์กโฟลว์การพัฒนาไคลเอ็นต์คืออะไร
หากคุณทำตามคู่มือเริ่มต้นใช้งาน คุณจะได้เห็นภาพรวมของขั้นตอนการพัฒนาสำหรับ SQL Connect ในคู่มือนี้ คุณจะได้ดูข้อมูลโดยละเอียดเพิ่มเติมเกี่ยวกับการสร้าง Swift SDK จากสคีมา และการทำงานกับการค้นหาและการเปลี่ยนแปลงฝั่งไคลเอ็นต์
สรุปได้ว่าหากต้องการใช้ Swift SDK ที่สร้างขึ้นในแอปไคลเอ็นต์ คุณจะต้องทำตามขั้นตอนเบื้องต้นต่อไปนี้
- เพิ่ม Firebase ลงในแอป iOS
หากต้องการใช้ SDK ที่สร้างขึ้น ให้กำหนดค่า SDK เป็นทรัพยากร Dependency ใน Xcode
ในแถบการนำทางด้านบนของ Xcode ให้เลือกไฟล์ > เพิ่มการขึ้นต่อกันของแพ็กเกจ > เพิ่มภายในเครื่อง แล้วเลือกโฟลเดอร์ที่มี
Package.swiftที่สร้างขึ้น
จากนั้นทำดังนี้
- พัฒนาสคีมาของแอป
ตั้งค่าการสร้าง SDK โดยทำดังนี้
- ใช้ปุ่มเพิ่ม SDK ลงในแอป ในส่วนขยาย SQL Connect VS Code
- โดย การอัปเดต
connector.yaml
ตั้งค่าและใช้โปรแกรมจำลอง SQL Connect และ ทำซ้ำ
สร้าง Swift SDK
ใช้ 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 iOS SDK
เริ่มต้นอินสแตนซ์ SQL Connect โดยใช้ข้อมูลที่คุณ ใช้ตั้งค่า SQL Connect ดูข้อมูลนี้ได้ในหน้า ฐานข้อมูลและพื้นที่เก็บข้อมูล > SQL Connect ของคอนโซลFirebase
การรับอินสแตนซ์เครื่องมือเชื่อมต่อ
โปรแกรมจำลองจะสร้างโค้ดสำหรับเครื่องมือเชื่อมต่อ
SQL Connect หากเครื่องมือเชื่อมต่อชื่อ movies และแพ็กเกจชื่อ movies ตามที่ระบุไว้ใน connector.yaml ให้เรียกออบเจ็กต์เครื่องมือเชื่อมต่อโดยเรียกใช้โค้ดต่อไปนี้
let connector = DataConnect.moviesConnector
ใช้การค้นหาและการเปลี่ยนแปลง
ด้วยออบเจ็กต์เครื่องมือเชื่อมต่อ คุณสามารถเรียกใช้การค้นหาและการเปลี่ยนแปลงตามที่กำหนดไว้ในซอร์สโค้ด 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
}
}
จากนั้นคุณจะสร้างภาพยนตร์ได้ดังนี้
let mutationResult = try await connector.createMovieMutation.execute(
title: "Empire Strikes Back",
releaseYear: 1980,
genre: "Sci-Fi",
rating: 5)
print("Movie ID: \(mutationResult.data.movie_insert.id)")
หากต้องการดึงข้อมูลภาพยนตร์ คุณจะต้องใช้การอ้างอิงการค้นหา การอ้างอิงการค้นหาทั้งหมดเป็นผู้เผยแพร่ Observable โดยจะรองรับมาโคร @Observable (iOS 17 ขึ้นไป) หรือใช้โปรโตคอล
ObservableObject ทั้งนี้ขึ้นอยู่กับผู้เผยแพร่ที่กำหนดค่าไว้ (ดู connector.yaml),
ค่าเริ่มต้นหากไม่ได้ระบุคือมาโคร @Observable ที่รองรับใน iOS 17 ขึ้นไป
ในมุมมอง SwiftUI คุณสามารถผูกผลการค้นหาโดยใช้ตัวแปร data ที่เผยแพร่ของการอ้างอิงการค้นหา และเรียกใช้เมธอด execute() ของการค้นหาเพื่ออัปเดตข้อมูล ตัวแปร data จะมีรูปร่างตรงกับข้อมูลที่กำหนดไว้ในการกำหนดการค้นหา GQL
ผลลัพธ์ที่ดึงมาทั้งหมดเป็นไปตามโปรโตคอล Decodable หากคุณรวมคีย์หลักของออบเจ็กต์ไว้ในการดึงข้อมูล GQL ออบเจ็กต์จะเป็น Identifiable ด้วย ซึ่งช่วยให้คุณใช้ออบเจ็กต์ในตัววนซ้ำได้
struct ListMovieView: View {
@StateObject private var queryRef = connector.listMoviesByGenreQuery.ref(genre: "Sci-Fi")
var body: some View {
VStack {
Button {
Task {
do {
try await refresh()
} catch {
print("Failed to refresh: \(error)")
}
}
} label: {
Text("Refresh")
}
// use the query results in a view
ForEach(queryRef.data?.movies ?? [], id: \.self.id) { movie in
Text(movie.title)
}
}
}
@MainActor
func refresh() async throws {
_ = try await queryRef.execute()
}
}
การค้นหายังรองรับการดำเนินการแบบครั้งเดียวด้วย
let resultData = try await DataConnect.moviesConnector.listMoviesByGenreQuery.execute(genre: "Sci-Fi")
สมัครรับข้อมูลการเปลี่ยนแปลง
ดูรับข้อมูลอัปเดตแบบเรียลไทม์จาก SQL Connect
จัดการการเปลี่ยนแปลงในช่องการแจกแจง
สคีมาของแอปอาจมีการแจกแจง, ซึ่งการค้นหา GraphQL สามารถเข้าถึงได้
เมื่อการออกแบบแอปมีการเปลี่ยนแปลง คุณอาจเพิ่มค่าที่รองรับการแจกแจงใหม่ ตัวอย่างเช่น ลองนึกภาพว่าในภายหลังของวงจรชีวิตของแอปพลิเคชัน คุณตัดสินใจเพิ่มค่า FULLSCREEN ลงในการแจกแจง AspectRatio
ในเวิร์กโฟลว์ SQL Connect คุณสามารถใช้เครื่องมือการพัฒนาภายในเครื่องเพื่อ อัปเดตการค้นหาและ SDK
อย่างไรก็ตาม ก่อนที่จะเผยแพร่ไคลเอ็นต์เวอร์ชันที่อัปเดตแล้ว ไคลเอ็นต์ที่ทำให้ใช้งานได้ก่อนหน้านี้อาจใช้งานไม่ได้
ตัวอย่างการใช้งานที่ยืดหยุ่น
SDK ที่สร้างขึ้นบังคับให้จัดการค่าที่ไม่รู้จัก เนื่องจากค่าแจกแจงที่สร้างขึ้นมีค่า _UNKNOWN และ Swift บังคับใช้คำสั่ง switch ที่ครอบคลุม
do {
let result = try await DataConnect.moviesConnector.listMovies.execute()
if let data = result.data {
for movie in data.movies {
switch movie.aspectratio {
case .ACADEMY: print("academy")
case .WIDESCREEN: print("widescreen")
case .ANAMORPHIC: print("anamorphic")
case ._UNKNOWN(let unknownAspect): print(unknownAspect)
}
}
}
} catch {
// handle error
}
เปิดใช้การแคชฝั่งไคลเอ็นต์
SQL Connect มีฟีเจอร์การแคชฝั่งไคลเอ็นต์ที่ไม่บังคับ ซึ่งคุณ
เปิดใช้ได้โดยแก้ไขไฟล์ connector.yaml เมื่อเปิดใช้ฟีเจอร์นี้ SDK ไคลเอ็นต์ที่สร้างขึ้นจะแคชการตอบสนองการค้นหาในเครื่อง ซึ่งจะช่วยลดจำนวนคำขอฐานข้อมูลที่แอปส่ง และช่วยให้ส่วนต่างๆ ของแอปที่ขึ้นอยู่กับฐานข้อมูลทำงานได้เมื่อเครือข่ายไม่พร้อมใช้งาน
หากต้องการเปิดใช้การแคชฝั่งไคลเอ็นต์ ให้เพิ่มการกำหนดค่าการแคชไคลเอ็นต์ลงในการกำหนดค่าเครื่องมือเชื่อมต่อโดยทำดังนี้
generate:
swiftSdk:
outputDir: "../ios"
package: "FirebaseDataConnectGenerated"
clientCache:
maxAge: 5s
storage: persistent
การกำหนดค่านี้มี 2 พารามิเตอร์ ซึ่งทั้ง 2 พารามิเตอร์จะใส่หรือไม่ใส่ก็ได้
maxAge: อายุสูงสุดที่การตอบสนองที่แคชไว้จะมีได้ก่อนที่ SDK ไคลเอ็นต์จะดึงค่าใหม่ ตัวอย่าง: "0", "30s", "1h30m"ค่าเริ่มต้นของ
maxAgeคือ0ซึ่งหมายความว่าระบบจะแคชการตอบสนอง แต่ SDK ไคลเอ็นต์จะดึงค่าใหม่เสมอ ระบบจะใช้ค่าที่แคชไว้ก็ต่อเมื่อระบุCACHE_ONLYเป็นexecute()storage: คุณกำหนดค่า SDK ไคลเอ็นต์ให้แคชการตอบสนองในพื้นที่เก็บข้อมูลpersistentหรือในmemoryก็ได้ ผลลัพธ์ที่แคชไว้ในพื้นที่เก็บข้อมูลpersistentจะยังคงอยู่แม้จะรีสตาร์ทแอป ใน iOS SDK ค่าเริ่มต้นคือpersistent
หลังจากอัปเดตการกำหนดค่าการแคชของเครื่องมือเชื่อมต่อแล้ว ให้สร้าง SDK ไคลเอ็นต์
ขึ้นใหม่และสร้างแอปขึ้นใหม่ เมื่อทำเช่นนั้นแล้ว execute()
จะแคช
การตอบสนองและใช้ค่าที่แคชไว้ตามนโยบายที่คุณกำหนดค่าไว้ โดยทั่วไปแล้วกระบวนการนี้จะเกิดขึ้นโดยอัตโนมัติโดยที่คุณไม่ต้องดำเนินการใดๆ เพิ่มเติม แต่โปรดทราบสิ่งต่อไปนี้
ลักษณะการทำงานเริ่มต้นของ
execute()เป็นไปตามที่อธิบายไว้ข้างต้น นั่นคือ หากระบบแคชผลลัพธ์ของการค้นหาและค่าที่แคชไว้มีอายุไม่เกินmaxAgeระบบจะใช้ค่าที่แคชไว้ ลักษณะการทำงานเริ่มต้นนี้เรียกว่านโยบายPREFER_CACHEนอกจากนี้ คุณยังระบุการเรียกใช้
execute()แต่ละครั้งให้แสดงเฉพาะค่าที่แคชไว้ (CACHE_ONLY) หรือดึงค่าใหม่จากเซิร์ฟเวอร์แบบไม่มีเงื่อนไข (SERVER_ONLY) ก็ได้try await execute(fetchPolicy: .cacheOnly)try await execute(fetchPolicy: .serverOnly)สร้างต้นแบบและทดสอบแอปพลิเคชัน iOS
วัดคุมไคลเอ็นต์ให้ใช้โปรแกรมจำลองภายในเครื่อง
คุณสามารถใช้โปรแกรมจำลอง SQL Connect ได้จาก ส่วนขยาย SQL Connect VS Code หรือจาก CLI
การกำหนดให้แอปเชื่อมต่อกับโปรแกรมจำลองจะเหมือนกันในทั้ง 2 สถานการณ์
let connector = DataConnect.moviesConnector // Connect to the emulator on "127.0.0.1:9399" connector.useEmulator() // (alternatively) if you're running your emulator on non-default port: connector.useEmulator(port: 9999) // Make calls from your appประเภทข้อมูลใน SQL Connect SDK
เซิร์ฟเวอร์ SQL Connect แสดงประเภทข้อมูล GraphQL แบบทั่วไปและแบบกำหนดเอง ซึ่งแสดงใน SDK ดังนี้
SQL Connect ประเภท Swift สตริง สตริง Int Int ลอยขึ้นมา เตียงคู่ บูลีน Bool UUID UUID วันที่ FirebaseDataConnect.LocalDate การประทับเวลา FirebaseCore.Timestamp Int64 Int64 เวลาใดก็ได้ FirebaseDataConnect.AnyValue