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

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

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

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

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

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

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

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

เพิ่ม Firebase ไปยังแอป Flutter
ติดตั้ง FlutterFire CLI dart pub global activate flutterfire_cli
วิ่ง flutterfire configure

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

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

สร้าง Flutter 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

ก่อนอื่น ให้เริ่มต้นแอปโดยใช้วิธีการตั้งค่า Firebase มาตรฐาน

จากนั้นติดตั้งปลั๊กอิน Data Connect โดยทำดังนี้

flutter pub add firebase_data_connect

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

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

นำเข้าไลบรารี

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

// general imports
import 'package:firebase_data_connect/firebase_data_connect.dart';

// generated queries and mutations from SDK
import 'generated/movies.dart';

ใช้การค้นหาฝั่งไคลเอ็นต์

โค้ดที่สร้างขึ้นจะมี Query Ref ที่กำหนดไว้ล่วงหน้าอยู่แล้ว สิ่งที่คุณต้องทำ คือการนำเข้าและเรียกใช้ execute ในฟังก์ชันเหล่านั้น

import 'generated/movies.dart';

await MoviesConnector.instance.listMovies().execute();

เรียกใช้เมธอดการค้นหา SDK

ตัวอย่างการใช้ฟังก์ชันแป้นพิมพ์ลัดการดำเนินการเหล่านี้มีดังนี้

import 'generated/movies.dart';

function onBtnClick() {
  // This will call the generated Dart from the CLI and then make an HTTP request to the server.
  MoviesConnector.instance.listMovies().execute().then(data => showInUI(data)); // == MoviesConnector.instance.listMovies().ref().execute();
}

ช่องที่ไม่บังคับ

การค้นหาบางรายการอาจมีช่องที่ไม่บังคับ ในกรณีเหล่านี้ Flutter SDK จะแสดงเมธอด Builder และจะต้องตั้งค่าแยกกัน

เช่น ฟิลด์ rating จะไม่บังคับเมื่อเรียกใช้ createMovie ดังนั้นคุณ ต้องระบุในฟังก์ชัน Builder

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi"}).rating(5).execute();

ติดตามการเปลี่ยนแปลง

คุณสามารถติดตามการเปลี่ยนแปลง (ซึ่งจะอัปเดตทุกครั้งที่คุณเรียกใช้คำค้นหา)

QueryRef<ListMoviesData, void> listRef = MoviesConnector.instance.listMovies().ref();

// subscribe will immediately invoke the query if no execute was called on it previously.
listRef.subscribe().listen((data) {
  updateUIWithMovies(data.movies);
});

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();
await listRef.execute(); // will update the subscription above`

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

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

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

ในเวิร์กโฟลว์ Data Connect คุณสามารถใช้เครื่องมือการพัฒนาในเครื่องเพื่อ อัปเดตการค้นหาและ SDK ได้

อย่างไรก็ตาม ก่อนที่จะเผยแพร่ไคลเอ็นต์เวอร์ชันที่อัปเดตแล้ว ไคลเอ็นต์เวอร์ชันเก่าที่ติดตั้งใช้งาน อาจใช้งานไม่ได้

ตัวอย่างการใช้งานที่ยืดหยุ่น

SDK ที่สร้างขึ้นจะบังคับให้จัดการค่าที่ไม่รู้จัก กล่าวคือ โค้ดไคลเอ็นต์ต้อง แกะออบเจ็กต์ EnumValue เป็น Known หรือ Unknown

final result = await MoviesConnector.instance.listMovies().execute();

if (result.data != null && result.data!.isNotEmpty) {
  handleEnumValue(result.data![0].aspectratio);
}

void handleEnumValue(EnumValue<AspectRatio> aspectValue) {
  if (aspectValue.value != null) {
    switch(aspectValue.value!) {
      case AspectRatio.ACADEMY:
        print("This movie is in Academy aspect");
        break;
      case AspectRatio.WIDESCREEN:
        print("This movie is in Widescreen aspect");
        break;
      case AspectRatio.ANAMORPHIC:
        print("This movie is in Anamorphic aspect");
        break;
      case AspectRatio.IMAX:
        print("This movie is in IMAX aspect");
    }
  } else {
    print("Unknown aspect ratio detected: ${aspectValue.stringValue}");
  }
}

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

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

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

generate:
  javascriptSdk:
    outputDir: ../dart/
    package: "dataconnect_generated"
    clientCache:
      maxAge: 5s
      storage: memory

การกำหนดค่านี้มีพารามิเตอร์ 2 รายการ ซึ่งทั้ง 2 รายการเป็นพารามิเตอร์ที่ไม่บังคับ

maxAge: อายุสูงสุดที่การตอบสนองที่แคชไว้สามารถมีได้ก่อนที่ SDK ของไคลเอ็นต์ จะดึงค่าใหม่ ตัวอย่างเช่น "0", "30s", "1h30m"

ค่าเริ่มต้นสำหรับ maxAge คือ 0 ซึ่งหมายความว่าระบบจะแคชคําตอบ แต่ SDK ของไคลเอ็นต์จะดึงค่าล่าสุดเสมอ ระบบจะใช้ค่าที่แคชไว้เมื่อระบุ CACHE_ONLY เป็น execute() และผลลัพธ์เริ่มต้นที่ได้จาก subscribe() เท่านั้น
storage: คุณกำหนดค่า SDK ของไคลเอ็นต์ให้แคชการตอบกลับได้ทั้งในที่เก็บข้อมูล persistent หรือใน memory ผลลัพธ์ที่แคชไว้ในpersistent จะยังคงอยู่เมื่อรีสตาร์ทแอป เมื่อกำหนดเป้าหมายเป็น Android หรือ iOS ค่าเริ่มต้นคือ persistent เมื่อกำหนดเป้าหมายเป็นเว็บเบราว์เซอร์ ระบบจะรองรับเฉพาะพื้นที่เก็บข้อมูล memory

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

ลักษณะการทำงานเริ่มต้นของ execute() เป็นไปตามที่อธิบายไว้ข้างต้น กล่าวคือ หากมีการแคชผลลัพธ์สำหรับการค้นหาและค่าที่แคชไม่เก่ากว่า maxAge ให้ใช้ค่าที่แคช ลักษณะการทำงานเริ่มต้นนี้เรียกว่านโยบาย PREFER_CACHE

นอกจากนี้ คุณยังระบุการเรียกใช้ execute() แต่ละครั้งให้ แสดงเฉพาะค่าที่แคชไว้ (CACHE_ONLY) หรือดึงค่าใหม่จากเซิร์ฟเวอร์โดยไม่มีเงื่อนไข (SERVER_ONLY) ได้ด้วย
```
await queryRef.execute(fetchPolicy: QueryFetchPolicy.cacheOnly);
```
```
await queryRef.execute(fetchPolicy: QueryFetchPolicy.serverOnly);
```
เมื่อคุณเรียกใช้ subscribe() ระบบจะแสดงเนื้อหาที่แคชไว้ทันทีเสมอหากมีอยู่ ไม่ว่าการตั้งค่า maxAge จะเป็นอย่างไรก็ตาม การเรียกใช้ execute() ครั้งต่อๆ ไปจะแจ้งเตือน Listener ตาม maxAge ที่กำหนดค่าไว้

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

คุณเข้าถึงการเปลี่ยนแปลงได้ในลักษณะเดียวกับการค้นหา

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();

สร้างต้นแบบและทดสอบแอป Flutter

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

คุณสามารถใช้Data Connectโปรแกรมจำลองได้ ไม่ว่าจะจากส่วนขยาย Data Connect VS Code หรือจาก CLI

การวัดประสิทธิภาพแอปเพื่อเชื่อมต่อกับโปรแกรมจำลองจะเหมือนกันสำหรับทั้ง 2 สถานการณ์

import 'package:firebase_data_connect/firebase_data_connect.dart';
import 'generated/movies.dart';

MoviesConnector.instance.dataConnect
          .useDataConnectEmulator('127.0.0.1', 9399);

// Make calls from your app
QueryRef<ListMoviesData, void> ref = MoviesConnector.instance.listMovies.ref();

หากต้องการเปลี่ยนไปใช้ทรัพยากรการใช้งานจริง ให้แสดงความคิดเห็นในบรรทัดสำหรับการเชื่อมต่อกับ โปรแกรมจำลอง

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

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

Data Connect ประเภท	Dart
การประทับเวลา	firebase_data_connect.Timestamp
Int (32 บิต)	int
วันที่	DateTime
UUID	สตริง
Int64	int
ทศนิยม	double
บูลีน	bool
เวลาใดก็ได้	firebase_data_connect.AnyValue