Firebase SQL Connect SDK ไคลเอ็นต์ช่วยให้คุณเรียกใช้การค้นหาและ การเปลี่ยนแปลงฝั่งเซิร์ฟเวอร์ได้โดยตรงจากแอป Firebase คุณสร้าง SDK ไคลเอ็นต์ที่กำหนดเองแบบ ขนานไปกับการออกแบบสคีมา การค้นหา และการเปลี่ยนแปลงที่คุณทำให้ SQL Connect ใช้งานได้ จากนั้นผสานรวมเมธอดจาก SDK นี้เข้ากับตรรกะไคลเอ็นต์
ดังที่เราได้กล่าวไว้ในส่วนอื่นๆ สิ่งสำคัญที่ควรทราบคือSQL Connect โค้ดไคลเอ็นต์ไม่ได้ส่งการค้นหาและการเปลี่ยนแปลง และไม่ได้ดำเนินการบน เซิร์ฟเวอร์ แต่เมื่อทำให้ใช้งานได้ ระบบจะจัดเก็บการดำเนินการ SQL Connect ไว้ใน เซิร์ฟเวอร์เหมือนกับ Cloud Functions ซึ่งหมายความว่าคุณต้องทำให้การเปลี่ยนแปลงฝั่งไคลเอ็นต์ที่เกี่ยวข้องใช้งานได้เพื่อหลีกเลี่ยงไม่ให้ผู้ใช้เดิมได้รับผลกระทบ (เช่น ในแอปเวอร์ชันเก่า)
ด้วยเหตุนี้ SQL Connect จึงมีสภาพแวดล้อมและ เครื่องมือสำหรับนักพัฒนาแอปที่ช่วยให้คุณสร้างต้นแบบสคีมา การค้นหา และการเปลี่ยนแปลงที่ทำให้ใช้งานได้บนเซิร์ฟเวอร์ นอกจากนี้ยังสร้าง SDK ฝั่งไคลเอ็นต์โดยอัตโนมัติขณะที่คุณสร้างต้นแบบ
เมื่อคุณทำการอัปเดตบริการและแอปไคลเอ็นต์ซ้ำๆ การอัปเดตทั้งฝั่งเซิร์ฟเวอร์และฝั่งไคลเอ็นต์ก็จะพร้อมใช้งาน
เวิร์กโฟลว์การพัฒนาไคลเอ็นต์คืออะไร
หากคุณทำตามคู่มือเริ่มต้นใช้งาน คุณจะได้ทำความคุ้นเคย กับขั้นตอนการพัฒนาโดยรวมสำหรับ SQL Connect ในคู่มือนี้ คุณจะได้ดูข้อมูลโดยละเอียดเพิ่มเติมเกี่ยวกับการสร้าง Flutter SDK จากสคีมาและการทำงานกับการค้นหาและการเปลี่ยนแปลงของไคลเอ็นต์
สรุปได้ว่าหากต้องการใช้ Flutter SDK ที่สร้างขึ้นในแอปไคลเอ็นต์ คุณจะต้องทำตามขั้นตอนเบื้องต้นต่อไปนี้
- เพิ่ม Firebase ลงในแอป Flutter
- ติดตั้ง flutterfire CLI
dart pub global activate flutterfire_cli - วิ่ง
flutterfire configure
จากนั้นทำดังนี้
- พัฒนาสคีมาของแอป
ตั้งค่าการสร้าง SDK โดยทำดังนี้
- ใช้ปุ่มเพิ่ม SDK ลงในแอป ในส่วนขยาย SQL Connect VS Code
- โดย อัปเดต
connector.yaml
ตั้งค่าและใช้โปรแกรมจำลอง SQL Connect และ ทำซ้ำ
สร้าง Flutter 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
ขั้นแรก ให้เริ่มต้นแอปโดยใช้ วิธีการตั้งค่า Firebase มาตรฐาน
จากนั้นติดตั้งปลั๊กอิน SQL Connect โดยทำดังนี้
flutter pub add firebase_data_connectเริ่มต้น SQL Connect Flutter SDK
เริ่มต้นอินสแตนซ์ SQL Connect โดยใช้ข้อมูลที่คุณ ใช้ตั้งค่า SQL Connect ดูข้อมูลนี้ได้ในหน้า ฐานข้อมูลและพื้นที่เก็บข้อมูล > SQL Connect ของคอนโซลFirebase
นำเข้าไลบรารี
คุณต้องนำเข้าไลบรารี 2 ชุดเพื่อเริ่มต้นโค้ดไคลเอ็นต์ ได้แก่ การนำเข้าทั่วไป SQL 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();
สมัครรับข้อมูลการเปลี่ยนแปลง
ดูรับข้อมูลอัปเดตแบบเรียลไทม์จาก SQL Connect
จัดการการเปลี่ยนแปลงในช่องการแจงนับ
สคีมาของแอปอาจมีการแจงนับ ซึ่งการค้นหา GraphQL สามารถเข้าถึงได้
เมื่อการออกแบบแอปมีการเปลี่ยนแปลง คุณอาจเพิ่มค่าที่รองรับใหม่ของการแจงนับ ตัวอย่างเช่น ลองนึกภาพว่าในภายหลังของวงจรชีวิตของแอปพลิเคชัน คุณตัดสินใจที่จะเพิ่มค่า FULLSCREEN ลงในการแจงนับ AspectRatio
ในเวิร์กโฟลว์ SQL 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}');
}
}
เปิดใช้การแคชฝั่งไคลเอ็นต์
SQL 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()ในภายหลังจะแจ้งให้ผู้ฟังทราบตามmaxAgeที่กำหนดค่าไว้
ใช้การเปลี่ยนแปลงในฝั่งไคลเอ็นต์
คุณเข้าถึงการเปลี่ยนแปลงได้ในลักษณะเดียวกับการค้นหา
await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();
สร้างต้นแบบและทดสอบแอป Flutter
วัดคุมไคลเอ็นต์ให้ใช้โปรแกรมจำลองภายในเครื่อง
คุณสามารถใช้โปรแกรมจำลอง SQL Connect ได้จาก ส่วนขยาย SQL 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
เซิร์ฟเวอร์ SQL Connect แสดงประเภทข้อมูล GraphQL ทั่วไป ซึ่งแสดงใน SDK ดังนี้
| SQL Connect ประเภท | Dart |
|---|---|
| การประทับเวลา | firebase_data_connect.Timestamp |
| Int (32 บิต) | int |
| วันที่ | DateTime |
| UUID | สตริง |
| Int64 | int |
| ลอยขึ้นมา | double |
| บูลีน | bool |
| เวลาใดก็ได้ | firebase_data_connect.AnyValue |