ใช้ SDK ของเว็บที่สร้างขึ้น

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

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

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

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

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

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

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

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

1. เพิ่ม Firebase ไปยังแอปเว็บ

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

1. พัฒนาสคีมาแอป
2. เริ่มต้นรหัสไคลเอ็นต์ด้วย JavaScript SDK หรือไลบรารี React หรือ Angular
3. สําหรับ React และ Angular ให้ติดตั้งแพ็กเกจ Tanstack Query

4. ตั้งค่าการสร้าง SDK

   • ด้วยปุ่มเพิ่ม SDK ลงในแอปในส่วนขยาย Data Connect ของ VS Code
   • โดยการอัปเดต connector.yaml สำหรับ JavaScript SDK หรือ React หรือ Angular

5. นําเข้าไลบรารีและโค้ดที่สร้างขึ้นด้วย JavaScript SDK หรือ React หรือ Angular

6. ใช้การเรียกคําค้นหาและการดัดแปลงด้วย JavaScript SDK หรือ React หรือ Angular

7. ทดสอบโดยตั้งค่าโปรแกรมจำลอง Data Connect ด้วย JavaScript SDK หรือ React หรือ Angular

ใช้โค้ดไคลเอ็นต์กับ Firebase JavaScript SDK

ส่วนนี้จะอธิบายวิธีติดตั้งใช้งานไคลเอ็นต์โดยใช้ Firebase JavaScript SDK

หากคุณใช้ React หรือ Angular โปรดดูวิธีการตั้งค่าอื่นและลิงก์ไปยังเอกสารประกอบเพิ่มเติมเกี่ยวกับการสร้าง Data ConnectSDK สําหรับเฟรมเวิร์ก

เริ่มต้นแอป

ก่อนอื่น ให้เริ่มต้นแอปโดยใช้ลําดับ Firebase มาตรฐาน

initializeApp({...});

สร้าง JavaScript SDK

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

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

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

generate:
  javascriptSdk:
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

outputDir ระบุตำแหน่งที่ SDK ที่สร้างขึ้นควรแสดงผล

package ระบุชื่อแพ็กเกจ

packageJsonDir ระบุตำแหน่งที่จะติดตั้งแพ็กเกจ

ในกรณีนี้ ให้ติดตั้ง firebase@latest เพื่อให้แน่ใจว่า��ีการพึ่งพา Peer นี้

เริ่มต้น JavaScript SDK

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

ออบเจ็กต์ ConnectorConfig

SDK ต้องใช้ออบเจ็กต์การกําหนดค่าของเครื่องมือเชื่อมต่อ

ออบเจ็กต์นี้สร้าง���ึ้น���ดย�����ตโนมัติจ���� serviceId และ location ใน dataconnect.yaml และ connectorId ใน connector.yaml

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

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

โปรดสังเกตออบเจ็กต์ ConnectorConfig ที่รวมอยู่ในการนําเข้าทั่วไป

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// generated queries and mutations from SDK
import { listMovies, ListMoviesResponse, createMovie, connectorConfig } from '@myorg/myconnector';

ใช้การค้นหาจาก JavaScript SDK

โค้ดที่สร้างขึ้นจะมีข้อมูลอ้างอิงการค้นหาที่กําหนดไว้ล่วงหน้าอยู่แล้ว คุณเพียงต้องนําเข้าและเรียกใช้

import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@movie-app/movies';

const ref = listMoviesRef();
const { data } = await executeQuery(ref);
console.log(data.movies);

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

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

import { listMovies } from '@movie-app/movies';
function onBtnClick() {
// This will call the generated JS from the CLI and then make an HTTP request out
// to the server.
  listMovies().then(data => showInUI(data)); // == executeQuery(listMoviesRef);
}

สมัครรับข้อมูลการเปลี่ยนแปลง

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

const listRef = listAllMoviesRef();

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

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

ใช้การกลายพันธุ์จาก JavaScript SDK

คุณสามารถเข้าถึงการกลายพันธุ์ได้เช่นเดียวกับการค้นหา

import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@movie-app/movies';

const { data } = await executeMutation(createMovieRef({ movie: 'Empire Strikes Back' }));

เชื่อมต่อกับโปรแกรมจำลอง Data Connect

คุณเลือกเชื่อมต่อกับโปรแกรมจำลองได้โดยเรียกใช้ connectDataConnectEmulator แล้วส่งอินสแตนซ์ Data Connect ดังนี้

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@myorg/myconnector'; // Replace with your package name

const dataConnect = getDataConnect(connectorConfig);
connectDataConnectEmulator(dataConnect, 'localhost', 9399);`

// Make calls from your app

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

ใช้โค้ดไคลเอ็นต์สําหรับ React และ Angular

Firebase Data Connect มี SDK ที่สร้างขึ้นพร้อมฮุกสําหรับ React และ Angular โดยใช้ไลบรารีจากพาร์ทเนอร์ของเราที่ Invertase ซึ่งก็คือ TanStack Query Firebase

ไลบรารีนี้มีชุดฮุกที่ช่วยให้จัดการงานที่ทำงานพร้อมกันโดยใช้ Firebase ในแอปพลิเคชันได้ง่ายขึ้นมาก

เริ่มต้นแอป

ก่อนอื่น ให้เริ่มต้นแอปโดยใช้ลําดับ Firebase มาตรฐาน เช่นเดียวกับเว็บแอป Firebase อื่นๆ

initializeApp({...});

ติดตั้งแพ็กเกจ TanStack Query Firebase

ติดตั้งแพ็กเกจสำหรับ TanStack Query ในโปรเจ็กต์

npm i --save @tanstack/react-query @tanstack-query-firebase/react
npm i --save firebase@latest # Note: React has a peer dependency on ^11.3.0

ng add @angular/fire

สร้าง React หรือ Angular SDK

เครื่องมือของ Firebase จะจัดการการสร้าง SDK โดยอัตโนมัติตามสคีมาและการดำเนินการของคุณ เช่นเดียวกับ SDK เว็บมาตรฐานตามที่อธิบายไว้ก่อนหน้านี้

หากต้องการสร้าง React SDK สําหรับโปรเจ็กต์ ให้เพิ่มคีย์ react ลงในไฟล์การกําหนดค่า connector.yaml

generate:
  javascriptSdk:
    react: true
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

generate:
  javascriptSdk:
    angular: true
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

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

การนําเข้าจําเป็นต้องใช้ 4 ชุดเพื่อเริ่มต้นใช้งานโค้ดไคลเอ็นต์ React หรือ Angular ได้แก่ ��ารนําเข้า Data Connect ทั่วไป การนําเข้า TanStack ทั่วไป และการนําเข้าที่เฉพาะเจาะจงสําหรับ SDK ที่ JS และ React สร้างขึ้น

โปรดสังเกตประเภท ConnectorConfig ที่รวมอยู่ในการนําเข้าทั่วไป

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// TanStack Query-related functions
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@myorg/myconnector';

// generated React hooks from SDK
import { useListAllMovies, useCreateMovie } from "@myorg/connector/react";

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// TanStack Query-related functions
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";

// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@myorg/myconnector';

// generated React hooks from SDK
import { injectListAllMovies, injectCreateMovie } from "@myorg/connector/angular";

ใช้การค้นหาและการดัดแปลงในไคลเอ็นต์ React หรือ Angular

เมื่อตั้งค่าเสร็จแล้ว คุณจะรวมวิธีการจาก SDK ที่สร้างขึ้นได้

ในข้อมูลโค้ดต่อไปนี้ ให้สังเกตเมธอดที่มี use อยู่ข้างหน้า useListAllMovies สำหรับ React และเมธอดที่มี inject อยู่ข้างหน้า injectListAllMovies สำหรับ Angular ซึ่งทั้ง 2 รายการมาจาก SDK ที่สร้างขึ้น

import { useListAllMovies } from '@movies-app/movies/react';

function MyComponent() {
  const { isLoading, data, error } = useListAllMovies();
  if(isLoading) {
    return <div>Loading...</div>
  }
  if(error) {
    return <div> An Error Occurred: {error} </div>
  }
}

// App.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import MyComponent from './my-component';

function App() {
  const queryClient = new QueryClient();
  return <QueryClientProvider client={queryClient}>
    <MyComponent />
  </QueryClientProvider>
}

import { injectAllMovies, connectorConfig } from '@movies-app/movies/angular';
import { provideDataConnect, getDataConnect } from '@angular/fire/data-connect';
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";
const queryClient = new QueryClient();
...
providers: [
  ...
  provideTanStackQuery(queryClient),
  provideDataConnect(() => {
    const dc = getDataConnect(connectorConfig);
    return dc;
  })
]

ใช้การค้นหาที่โหลดซ้ำอัตโนมัติด้วย React และ Angular

คุณสามารถกําหนดค่าการค้นหาให้โหลดซ้ำโดยอัตโนมัติเมื่อข้อมูลมีการเปลี่ยนแปลง

export class MovieListComponent {
  movies = useListAllMovies();
}

export class AddPostComponent {
  const mutation = useCreateMovie({ invalidate: [listAllMoviesRef()] });
  addMovie() {
    // The following will automatically cause Tanstack to reload its listAllMovies query
    mutation.mutate({ title: 'The Matrix });
  }
}

// class
export class MovieListComponent {
  movies = injectListAllMovies();
}

// template
@if (movies.isPending()) {
    Loading...
}
@if (movies.error()) {
    An error has occurred: {{  movies.error() }}
}
@if (movies.data(); as data) {
    @for (movie of data.movies; track movie.id) {
    <mat-card appearance="outlined">
        <mat-card-content>{{movie.description}}</mat-card-content>
    </mat-card>
    } @empty {
        <h2>No items!</h2>
    }
}

เชื่อมต่อกับโปรแกรมจำลอง Data Connect

คุณเลือกเชื่อมต่อกับโปรแกรมจําลองได้โดยเรียกใช้ connectDataConnectEmulator แล้วส่งอินสแตนซ์ Data Connect ไปยังฮุกที่สร้างขึ้น ดังนี้

import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@movies-app/movies';
import { useListAllMovies } from '@movies-app/movies/react';

const dc = getDataConnect(connectorConfig);
connectDataConnectEmulator(dc, 'localhost', 9399);

class AppComponent() {
  ...
  const { isLoading, data, error } = useListAllMovies(dc);
  ...
}

// app.config.ts
import { provideDataConnect } from '@angular/fire/data-connect';
import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
provideDataConnect(() => {
  const dc = getDataConnect(connectorConfig);
  connectDataConnectEmulator(dc, 'localhost', 9399);
  return dc;
}),

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

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

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

สิ่งที่ควรพิจารณาเป็นพิเศษในการสร้าง SDK

กำหนดค่าเส้นทางที่สัมพันธ์กับ node_modules

สำหรับ SDK ของ JavaScript เนื่องจาก Data Connect ใช้ npm link เพื่อติดตั้ง SDK ของคุณ คุณจึงต้องส่งออก SDK ที่สร้างขึ้นไปยังไดเรกทอรีที่ระดับเดียวกับเส้นทาง node_modules หรือในไดเรกทอรีย่อยที่เข้าถึง node_modules ได้

กล่าวคือ SDK ที่สร้างขึ้นต้องมีสิทธิ์เข้าถึงfirebase โมดูล node เพื่อให้ทำงานได้อย่างถูกต้อง

เช่น หากคุณมี node_modules ใน my-app/ ไดเรกทอรีเอาต์พุตควรเป็น my-app/js-email-generated เพื่อให้ js-email-generated นำเข้าจากโฟลเดอร์ node_modules หลักได้

my-app/
  dataconnect/
    connector/
        connector.yaml
  node_modules/
    firebase/
  js-email-generated/

// connector.yaml
connectorId: "my-connector"
generate:
  javascriptSdk:
    outputDir: "../../js-email-generated"
    package: "@myapp/my-connector"

หรือหากคุณมีโมโนรีโปที่โฮสต์โมดูลที่รูท คุณสามารถวางไดเรกทอรีเอาต์พุตในโฟลเดอร์ใดก็ได้ในโมโนรีโป

my-monorepo/
  dataconnect/
    connector/
        connector.yaml
  node_modules/
    firebase/
  my-app/
    js-email-generated/
  package.json

// connector.yaml
connectorId: "my-connector"
generate:
  javascriptSdk:
    outputDir: "../../my-app/js-email-generated" # You can also output to ../../js-email-generated

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

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

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

firebase dataconnect:sdk:generate --watch

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

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

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