שימוש בערכות 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 שנוצר

משתמשים ב-CLI‏ Firebase כדי להגדיר ערכות 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 בפרויקט.

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

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

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

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

ייבוא ספריות

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

// generated React hooks from SDK
import { useListAllMovies, useCreateMovie } from "@dataconnect/generated/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 '@dataconnect/generated';

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

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

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

בקטע הקוד הבא אפשר לראות את השיטה עם הקידומת useuseListAllMovies ל-React ואת השיטה עם הקידומת injectinjectListAllMovies ל-Angular, שתיהן מתוך ה-SDK שנוצר.

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

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

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

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

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

// 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 במהלך יצירת אב טיפוס

אם התקנתם את התוסף 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