ใช้ 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 โดยทำดังนี้

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

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

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

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

สร้าง Swift SDK

เช่นเดียวกับโปรเจ็กต์ Firebase ส่วนใหญ่ การทำงานกับFirebase Data Connectโค้ดฝั่งไคลเอ็นต์ จะเกิดขึ้นในไดเรกทอรีโปรเจ็กต์ในเครื่อง ทั้งส่วนขยาย Data Connect VS Code และ Firebase CLI เป็นเครื่องมือในเครื่องที่สำคัญสำหรับการสร้างและจัดการโค้ดฝั่งไคลเอ็นต์

ตัวเลือกการสร้าง SDK จะเชื่อมโยงกับรายการต่างๆ ในdataconnect.yaml ไฟล์ที่สร้างขึ้นเมื่อคุณเริ่มต้นโปรเจ็กต์

เริ่มต้นการสร้าง SDK

connectorId: "movies"
generate:
  swiftSdk:
    outputDir: "../movies-generated"
    package: "Movies"

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

package ระบุชื่อของแพ็กเกจที่จะสร้าง ตัวสร้าง จะสร้างโฟลเดอร์ที่มีชื่อแพ็กเกจ ซึ่งมี Package.swift และโค้ดที่สร้างขึ้น

observablePublisher (ไม่บังคับ) ระบุผู้เผยแพร่ Observable ที่จะใช้ใน การอ้างอิงการค้นหา ค่าที่เป็นไปได้คือ observableMacro (iOS 17 ขึ้นไป) และ observableObject (iOS ก่อนเวอร์ชัน 17) ค่าเริ่มต้น หากไม่ได้ระบุคือ observableMacro

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

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

หรือจะใช้ CLI เพื่อสร้าง SDK ใหม่ทุกครั้งที่มีการเปลี่ยนแปลงไฟล์ .gql ก็ได้

firebase dataconnect:sdk:generate --watch

สร้าง SDK สำหรับการผสานรวมและสำหรับรุ่นที่ใช้งานจริง

ในบางกรณี เช่น การเตรียมแหล่งที่มาของโปรเจ็กต์เพื่อส่งสำหรับการทดสอบ CI คุณ สามารถเรียกใช้ Firebase CLI เพื่ออัปเดตแบบเป็นกลุ่มได้

ในกรณีเหล่านี้ ให้ใช้ firebase dataconnect:sdk:generate

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

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

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

โปรแกรมจำลอง 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 จะเข้าถึงได้

เมื่อการออกแบบแอปมีการเปลี่ยนแปลง คุณอาจเพิ่มค่าใหม่ที่รองรับการแจงนับ ตัวอย่างเช่น สมมติว่าในภายหลังวงจรแอปพลิเคชัน คุณตัดสินใจที่จะเพิ่มค่า 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
}

สร้างต้นแบบและทดสอบแอปพลิเคชัน 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 ดังนี้