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

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

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

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

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

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

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

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

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

לאחר מכן:

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

4. מגדירים יצירת SDK:

   • באמצעות הלחצן Add SDK to app בתוסף 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.

הטמעת קוד לקוח באמצעות ה-SDK של Firebase JavaScript

בקטע הזה נסביר איך מטמיעים לקוחות באמצעות ה-SDK של Firebase JavaScript.

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

איך מפעילים את האפליקציה

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

initializeApp({...});

יצירת ה-SDK ל-JavaScript

כמו ברוב הפרויקטים ב-Firebase, העבודה על קוד הלקוח של Firebase Data Connect מתבצעת בספריית פרויקט מקומית. גם התוסף של Data Connect ל-VS Code וגם ה-CLI של Firebase הם כלים מקומיים חשובים ליצירה ולניהול של קוד לקוח.

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

אתחול היצירה של SDK

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

outputDir מציין את המיקום שבו צריך ליצור את הפלט של ה-SDK שנוצר.

package מציין את שם החבילה.

packageJsonDir מציין איפה להתקין את החבילה.

במקרה כזה, צריך להתקין את firebase@latest כדי לוודא שהתלות הזו בצד השני מתקיימת.

אתחול ה-JavaScript SDK

מאתחלים את המכונה של Data Connect באמצעות המידע ששימש להגדרת Data Connect (הכול זמין בכרטיסייה Data Connect במסוף Firebase).

האובייקט ConnectorConfig

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

האובייקט הזה נוצר באופן אוטומטי מ-serviceId ו-location ב-dataconnect.yaml, ומ-connectorId ב-connector.yaml.

ייבוא ספריות

יש שתי קבוצות של ייבוא שנדרשות כדי להפעיל את קוד הלקוח: ייבוא 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.

הספרייה הזו מספקת קבוצה של וו 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 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: "../../"

ייבוא ספריות

יש ארבע קבוצות של ייבוא שנדרשות כדי להפעיל את קוד הלקוח של 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 שנוצר.

בקטע הקוד הבא, שימו לב לשיטה useListAllMovies עם הקידומת use ל-React ולשיטה injectListAllMovies עם הקידומת inject ל-Angular, שניהם מ-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 ל-hook שנוצר, כך:

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_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, אפשר להפעיל את ה-CLI של Firebase כדי לבצע עדכון באצווה.

במקרים כאלה, צריך להשתמש ב-firebase dataconnect:sdk:generate.