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

Firebase SQL Connect Client SDK ช่วยให้คุณเรียกใช้การค้นหาและ การเปลี่ยนแปลงฝั่งเซิร์ฟเวอร์ได้โดยตรงจากแอป Firebase คุณสร้าง Client SDK ที่กำหนดเองแบบ ขนานไปกับการออกแบบสคีมา การค้นหา และการเปลี่ยนแปลงที่คุณทำให้บริการ SQL Connect ใช้งานได้ จากนั้นผสานรวมเมธอดจาก SDK นี้เข้ากับตรรกะของไคลเอ็นต์

ดังที่เราได้กล่าวไว้ในส่วนอื่นๆ สิ่งสำคัญที่ควรทราบคือ SQL Connect โค้ดไคลเอ็นต์ไม่ได้ส่งการค้นหาและการเปลี่ยนแปลงและไม่ได้ดำเนินการบน เซิร์ฟเวอร์ แต่เมื่อทำให้ใช้งานได้ ระบบจะจัดเก็บการดำเนินการ SQL Connect ไว้ใน เซิร์ฟเวอร์เหมือนกับ Cloud Functions ซึ่งหมายความว่าคุณต้องทำให้การเปลี่ยนแปลงฝั่งไคลเอ็นต์ที่เกี่ยวข้องใช้งานได้เพื่อหลีกเลี่ยงไม่ให้ผู้ใช้เดิมได้รับผลกระทบ (เช่น ในแอปเวอร์ชันเก่า)

ด้วยเหตุนี้ SQL Connect จึงมีสภาพแวดล้อมและ เครื่องมือสำหรับนักพัฒนาแอปที่ช่วยให้คุณสร้างต้นแบบสคีมา การค้นหา และการเปลี่ยนแปลงที่ทำให้ใช้งานได้บนเซิร์ฟเวอร์ นอกจากนี้ยังสร้าง SDK ฝั่งไคลเอ็นต์โดยอัตโนมัติขณะที่คุณสร้างต้นแบบ

เมื่อคุณทำการอัปเดตบริการและแอปไคลเอ็นต์ซ้ำๆ การอัปเดตทั้งฝั่งเซิร์ฟเวอร์และฝั่งไคลเอ็นต์ก็จะพร้อมใช้งาน

เวิร์กโฟลว์การพัฒนาไคลเอ็นต์คืออะไร

หากคุณทำตามคู่มือเริ่มต้นใช้งาน คุณจะได้เห็นภาพรวมของขั้นตอนการพัฒนาสำหรับ SQL Connect ในคู่มือนี้ คุณจะได้ดูข้อมูลโดยละเอียดเพิ่มเติมเกี่ยวกับการสร้าง Swift SDK จากสคีมา และการทำงานกับการค้นหาและการเปลี่ยนแปลงของไคลเอ็นต์

สรุปได้ว่าหากต้องการใช้ Swift SDK ที่สร้างขึ้นในแอปไคลเอ็นต์ คุณจะต้องทำตามขั้นตอนเบื้องต้นต่อไปนี้

1. เพิ่ม Firebase ลงในแอป iOS

2. หากต้องการใช้ SDK ที่สร้างขึ้น ให้กำหนดค่า SDK เป็นทรัพยากร Dependency ใน Xcode

   ในแถบการนำทางด้านบนของ Xcode ให้เลือกไฟล์ > เพิ่มการขึ้นต่อกันของแพ็กเกจ > เพิ่มในเครื่อง แล้วเลือกโฟลเดอร์ที่มี Package.swift ที่สร้างขึ้น

จากนั้นให้ทำดังนี้

1. พัฒนาสคีมาของแอป

2. ตั้งค่าการสร้าง SDK โดยทำดังนี้

   • ใช้ปุ่มเพิ่ม SDK ลงในแอป ในส่วนขยาย SQL Connect VS Code
   • โดยการอัปเดตconnector.yaml

3. เริ่มต้นโค้ดไคลเอ็นต์และนำเข้าไลบรารี

4. ใช้การเรียกการค้นหาและการเปลี่ยนแปลง

5. ตั้งค่าและใช้โปรแกรมจำลอง 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 ที่สร้างขึ้นบังคับให้จัดการค่าที่ไม่รู้จัก เนื่องจาก Enum ที่สร้างขึ้นมีค่า _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: อายุสูงสุดที่การตอบสนองที่แคชไว้จะมีได้ก่อนที่ Client SDK จะดึงค่าใหม่ ตัวอย่าง: "0", "30s", "1h30m"

  ค่าเริ่มต้นของ maxAge คือ 0 ซึ่งหมายความว่าระบบจะแคชการตอบสนอง แต่ Client SDK จะดึงค่าใหม่เสมอ ระบบจะใช้ค่าที่แคชไว้ก็ต่อเมื่อระบุ CACHE_ONLY เป็น execute()

• storage: คุณกำหนดค่า Client SDK ให้แคชการตอบสนองในพื้นที่เก็บข้อมูล persistent หรือใน memory ได้ ผลลัพธ์ที่แคชไว้ในพื้นที่เก็บข้อมูล persistent จะยังคงอยู่แม้จะรีสตาร์ทแอป ใน iOS SDK ค่าเริ่มต้นคือ persistent

หลังจากอัปเดตการกำหนดค่าการแคชของเครื่องมือเชื่อมต่อแล้ว ให้สร้าง Client 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