שימוש בערכות SDK שנוצרו לאינטרנט

ערכות ה-SDK ללקוח של Firebase Data Connect מאפשרות לכם לקרוא לשאילתות ולשינויים בצד השרת ישירות מאפליקציית Firebase. אתם יוצרים ערכת SDK מותאמת אישית ללקוח במקביל לעיצוב הסכימות, השאילתות והשינויים שאתם פורסים בשירות Firebase Data Connect.Data Connect לאחר מכן, משלבים שיטות מ-SDK זה בלוגיקה של הלקוח.

כמו שציינו במקומות אחרים, חשוב לזכור שData Connect שאילתות ומוטציות לא נשלחות על ידי קוד לקוח ומופעלות בשרת. במקום זאת, כשפורסים את הפונקציה, פעולות Data Connect מאוחסנות בשרת כמו ב-Cloud Functions. כלומר, צריך להטמיע שינויים תואמים בצד הלקוח כדי למנוע שיבוש של משתמשים קיימים (לדוגמה, בגרסאות ישנות יותר של האפליקציה).

לכן Data Connect מספקת סביבת פיתוח וכלים שמאפשרים לכם ליצור אב טיפוס של סכימות, שאילתות ומוטציות שמוצבות בשרת. בנוסף, המערכת יוצרת באופן אוטומטי ערכות SDK בצד הלקוח בזמן שאתם יוצרים אב טיפוס.

אחרי שחוזרים על תהליך העדכון של השירות ושל אפליקציות הלקוח, העדכונים בצד השרת ובצד הלקוח מוכנים לפריסה.

מהו תהליך העבודה לפיתוח לקוחות?

אם פעלתם לפי השלבים במאמר תחילת העבודה, קיבלתם הסבר על תהליך הפיתוח הכולל של Data Connect. במדריך הזה תמצאו מידע מפורט יותר על יצירת ערכות SDK לאינטרנט מהסכימה שלכם ועל עבודה עם שאילתות ומוטציות של לקוחות.

לסיכום, כדי להשתמש ב-Web SDK שנוצר באפליקציות הלקוח, צריך לבצע את השלבים המקדימים הבאים:

  1. מוסיפים את Firebase לאפליקציית האינטרנט.

לאחר מכן:

  1. מפתחים את סכימת האפליקציה.
  2. מאתחלים את קוד הלקוח באמצעות JavaScript SDK, או באמצעות הספריות React או Angular.
  3. ב-React וב-Angular, מתקינים חבילות של Tanstack Query

  4. הגדרת יצירת SDK:

    • באמצעות הלחצן Add SDK to app (הוספת 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, תוכלו לעיין בהוראות ההגדרה החלופיות ובקישורים למסמכי תיעוד נוספים בנושא יצירת ערכות SDK של Data Connect למסגרות.

הפעלת האפליקציה

קודם צריך לאתחל את האפליקציה באמצעות רצף הפעולות הרגיל של Firebase.

initializeApp({...});

התקנה של JavaScript SDK שנוצר

משתמשים ב-Firebase CLI כדי להגדיר ערכות SDK שנוצרו על ידי Data Connect באפליקציות שלכם. הפקודה init אמורה לזהות את כל האפליקציות בתיקייה הנוכחית ולהתקין באופן אוטומטי את ה-SDK שנוצר.

firebase init dataconnect:sdk

מקשרים את האפליקציה לשירות Data Connect.

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';

const dataConnect = getDataConnect(connectorConfig);
// [Optionally] Configure the SDK to use Data Connect local emulator.
connectDataConnectEmulator(dataConnect, 'localhost', 9399);

עדכון של ערכות SDK במהלך יצירת אב טיפוס

אם התקנתם את התוסף Data Connect VS Code, הוא תמיד ידאג לעדכן את ערכות ה-SDK שנוצרו.

אם אתם לא משתמשים בתוסף Data Connect ל-VS Code, אתם יכולים להשתמש ב-Firebase CLI כדי לעדכן את ה-SDK שנוצר.

firebase dataconnect:sdk:generate --watch

יצירת ערכות SDK בצינורות עיבוד נתונים

אתם יכולים להשתמש ב-Firebase CLI כדי ליצור ערכות SDK של Data Connect בתהליכי בנייה של CI/CD.

firebase dataconnect:sdk:generate

ייבוא ספריות

יש שני סוגים של ייבוא שצריך לבצע כדי לאתחל את קוד הלקוח: ייבוא כללי של 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 '@dataconnect/generated';

שימוש בשאילתות מ-JavaScript SDK

הקוד שנוצר כבר יכלול הפניות לשאילתות שהוגדרו מראש. כל מה שצריך לעשות הוא לייבא אותם ולהפעיל אותם.

import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@dataconnect/generated';

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

הפעלת שיטות שאילתה של SDK

הנה דוגמה לשימוש בפונקציות של קיצורי דרך לפעולות:

import { listMovies } from '@dataconnect/generated';
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`

טיפול בשינויים בשדות של ספירה

סכימה של אפליקציה יכולה להכיל ספירות, שאפשר לגשת אליהן באמצעות שאילתות GraphQL.

יכול להיות שתוסיפו ערכים חדשים של enum נתמכים ככל שהעיצוב של האפליקציה ישתנה. לדוגמה, נניח שבהמשך מחזור החיים של האפליקציה תחליטו להוסיף ערך FULLSCREEN לאנום AspectRatio.

בתהליך העבודה של Data Connect, אפשר להשתמש בכלים לפיתוח מקומי כדי לעדכן את השאילתות ואת ערכות ה-SDK.

עם זאת, לפני שאתם משיקים גרסה מעודכנת של הלקוחות, יכול להיות שגרסאות ישנות יותר של לקוחות שכבר נפרסו יפסיקו לפעול.

דוגמה להטמעה עמידה

תמיד מוסיפים ענף default להצהרת switch מעל ערכי ה-enum, או ענף else לבלוק if/else if שמשווה לערכי ה-enum. השפה JavaScript/TypeScript לא מחייבת את זה, אבל זו הדרך להפוך את קוד הלקוח לחזק במקרה של הוספת ערכים חדשים של enum.

const queryResult = await getOldestMovie();

if (queryResult.data) {
  // we can use a switch statement's "default" case to check for unexpected values
  const oldestMovieAspectRatio = queryResult.data.originalAspectRatio;
  switch (oldestMovieAspectRatio) {
      case AspectRatio.ACADEMY:
      case AspectRatio.WIDESCREEN:
      case AspectRatio.ANAMORPHIC:
        console.log('This movie was filmed in Academy, widescreen or anamorphic aspect ratio!');
        break;
      default:
        // the default case will catch FULLSCREEN, UNAVAILABLE or _UNKNOWN
        // it will also catch unexpected values the SDK isn't aware of, such as CINEMASCOPE
        console.log('This movie was was NOT filmed in Academy, widescreen or anamorphic.');
        break;
  }

  // alternatively, we can check to see if the returned enum value is a known value
  if (!Object.values(AspectRatio).includes(oldestMovieAspectRatio)) {
    console.log(`Unrecognized aspect ratio: ${oldestAspectRatio}`);
  }
} else {
  console.log("no movies found!");
}

שימוש במוטציות מ-JavaScript SDK

אפשר לגשת למוטציות באותו אופן שבו ניגשים לשאילתות.

import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@dataconnect/generated';

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

התחברות לאמולטור Data Connect

אפשר גם להתחבר לאמולטור באמצעות קריאה ל-connectDataConnectEmulator ואז העברת המופע Data Connect, באופן הבא:

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';

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

// Make calls from your app

כדי לעבור למשאבי ייצור, מוסיפים הערות לשורות שמתחברות לאמולטור.

הטמעה של קוד לקוח ב-React וב-Angular

‫Firebase Data Connect מספק SDK שנוצר עם hooks ל-React ול-Angular באמצעות ספריות שזמינות מהשותפים שלנו ב-Invertase,‏ TanStack Query Firebase.

הספרייה הזו מספקת קבוצה של hooks שמקלים מאוד על הטיפול במשימות אסינכרוניות ב-Firebase באפליקציות שלכם.

הפעלת האפליקציה

קודם כל, כמו בכל אפליקציית אינטרנט של Firebase, צריך לאתחל את האפליקציה באמצעות הרצף הרגיל של Firebase.

initializeApp({...});

התקנת חבילות TanStack Query Firebase

מתקינים חבילות ל-TanStack Query בפרויקט.

React

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

Angular

ng add @angular/fire

יצירת SDK של React או Angular

בדומה ל-SDK הרגיל לאינטרנט, כפי שמתואר קודם, כלי Firebase מטפלים ביצירה אוטומטית של ערכות SDK על סמך הסכימה והפעולות שלכם.

אם הרגע הוספתם React או Angular לפרויקט, צריך להריץ מחדש את הפקודה firebase init dataconnect:sdk כדי להגדיר מחדש את ערכות ה-SDK שנוצרו כך שיכללו את ההתאמות הנוספות של המסגרת.

ייבוא ספריות

יש ארבע קבוצות של ייבוא שנדרשות כדי לאתחל את קוד הלקוח של React או Angular: ייבוא כללי של Data Connect, ייבוא כללי של TanStack וייבוא ספציפי של ערכות ה-SDK שנוצרו ב-JS וב-React.

שימו לב לסוג ConnectorConfig שכלול בייבוא הכללי.

React

// 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 '@dataconnect/generated';

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

Angular

// 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 '@dataconnect/generated';

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

שימוש בשאילתות ובמוטציות בלקוח React או Angular

אחרי שתסיימו את ההגדרה, תוכלו לשלב שיטות מתוך ה-SDK שנוצר.

בקטע הקוד הבא, שימו לב לשיטה עם הקידומת use-useListAllMovies עבור React ולשיטה עם הקידומת inject-injectListAllMovies עבור Angular, שניהם מתוך ה-SDK שנוצר.

React

כל הפעולות האלה ב-SDK שנוצר, גם שאילתות וגם מוטציות, קוראות לקישורי TanStackQuery:

import { useListAllMovies } from '@dataconnect/generated/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>
}

Angular

import { injectAllMovies, connectorConfig } from '@dataconnect/generated/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

אפשר להגדיר את השאילתות כך שהן ייטענו מחדש באופן אוטומטי כשהנתונים משתנים.

React

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 });
  }
}

Angular

// 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 ל-hook שנוצר, באופן הבא:

React 

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

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

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

Angular 

// 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 באופן הבא.

סוג Data Connect TypeScript
חותמת זמן מחרוזת
תאריך מחרוזת
מזהה ייחודי אוניברסלי (UUID) מחרוזת
Int64 מחרוזת
זוגית מספר
Float מספר

עדכון של ערכות SDK במהלך יצירת אב טיפוס

אם התקנתם את התוסף Data Connect VS Code, הוא תמיד ידאג לעדכן את ערכות ה-SDK שנוצרו.

אם אתם לא משתמשים בתוסף Data Connect ל-VS Code, אתם יכולים להשתמש ב-Firebase CLI כדי לעדכן את ה-SDK שנוצר.

firebase dataconnect:sdk:generate --watch

יצירת ערכות SDK בצינורות עיבוד נתונים

אתם יכולים להשתמש ב-Firebase CLI כדי ליצור ערכות SDK של Data Connect בתהליכי בנייה של CI/CD.

firebase dataconnect:sdk:generate