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

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

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

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

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

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

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

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

  1. เพิ่ม Firebase ไปยังแอป iOS

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

    ในแถบนำทางด้านบนของ Xcode ให้เลือก File > Add Package Dependencies > Add Local แล้วเลือกโฟลเดอร์ ที่มี Package.swift ที่สร้างขึ้น

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

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

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

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

  4. ใช้การเรียกไปยังการค้นหาและการกลายพันธุ์

  5. ตั้งค่าและใช้Data Connectโปรแกรมจำลอง แล้ว ทำซ้ำ

สร้าง Swift SDK

ใช้ Firebase CLI เพื่อตั้งค่า Data Connect SDK ที่สร้างขึ้นในแอป คำสั่ง init ควรตรวจหาแอปทั้งหมดในโฟลเดอร์ปัจจุบันและติดตั้ง SDK ที่สร้างขึ้นโดยอัตโนมัติ

firebase init dataconnect:sdk

อัปเดต SDK ขณะสร้างต้นแบบ

หากคุณติดตั้งส่วนขยาย Data Connect VS Code ไว้ ระบบจะอัปเดต SDK ที่สร้างขึ้นให้เป็นเวอร์ชันล่าสุดอยู่เสมอ

หากไม่ได้ใช้ส่วนขยาย Data Connect VS Code คุณสามารถใช้ Firebase CLI เพื่อให้ SDK ที่สร้างขึ้นเป็นเวอร์ชันล่าสุดอยู่เสมอ

firebase dataconnect:sdk:generate --watch

สร้าง SDK ในไปป์ไลน์การสร้าง

คุณใช้ Firebase CLI เพื่อสร้าง Data Connect SDK ในกระบวนการบิลด์ CI/CD ได้

firebase dataconnect:sdk:generate

เริ่มต้น Data Connect iOS SDK

เริ่มต้นอินสแตนซ์ Data Connect โดยใช้ข้อมูลที่คุณใช้ตั้งค่า Data Connect (ทั้งหมดอยู่ในแท็บ Firebase คอนโซล Data Connect)

การรับอินสแตนซ์ของเครื่องมือเชื่อมต่อ

โปรแกรมจำลอง Data 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")

จัดการการเปลี่ยนแปลงฟิลด์การแจงนับ

สคีมาของแอปมีรายการแจงนับได้ ซึ่งการค้นหา GraphQL จะเข้าถึงได้

เมื่อการออกแบบแอปมีการเปลี่ยนแปลง คุณอาจเพิ่มค่าใหม่ที่รองรับ enum ตัวอย่างเช่น สมมติว่าในภายหลังในวงจรแอปพลิเคชัน คุณตัดสินใจที่จะเพิ่มค่า FULLSCREEN ลงใน AspectRatio enum

ในเวิร์กโฟลว์ Data 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
}

เปิดใช้การแคชฝั่งไคลเอ็นต์

Data 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

    กำหนดค่าไคลเอ็นต์ให้ใช้โปรแกรมจำลองในเครื่อง

    คุณสามารถใช้Data Connectโปรแกรมจำลองได้ ไม่ว่าจะจากส่วนขยาย Data 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

    ประเภทข้อมูลใน Data Connect SDK

    Data Connect เซิร์ฟเวอร์แสดงประเภทข้อมูล GraphQL ทั่วไปและที่กำหนดเอง ซึ่งแสดงใน SDK ดังนี้

    Data Connect ประเภท Swift
    สตริง สตริง
    Int Int
    ทศนิยม เตียงคู่
    บูลีน Bool
    UUID UUID
    วันที่ FirebaseDataConnect.LocalDate
    การประทับเวลา FirebaseCore.Timestamp
    Int64 Int64
    เวลาใดก็ได้ FirebaseDataConnect.AnyValue