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

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

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

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

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

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

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

אפשר ללמוד על פיתוח לקוחות באמצעות מאגר אפליקציות להפעלה מהירה ולבנות אפליקציית Data Connect מלאה באמצעות ה-codelab שלנו לאינטרנט.

לסיכום, כדי להשתמש ב-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, העבודה על קוד הלקוח Firebase Data Connect מתבצעת בספריית פרויקט מקומית. גם התוסף Data Connect ל-VS Code וגם FirebaseCLI הם כלים מקומיים חשובים ליצירה ולניהול של קוד לקוח.

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

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

ב-connector.yaml, מוסיפים את outputDir, package ואת (עבור ה-SDK לאינטרנט) packageJsonDir.

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

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

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

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

הערה: כדי ליצור את "firebase": "^10.14.0", אנחנו מוסיפים אותו כ-peerDependency. יכול להיות שהתלויות האלה לא יותקנו באופן אוטומטי, בהתאם למנהל התלויות (למשל, pnpm).

במקרה כזה, צריך להתקין את 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

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

הערה: צריך להתקשר אל getDataConnect רק אם רוצים להתחבר לאמולטור Data Connect. אחרת, ה-SDK שנוצר ייצור באופן אוטומטי מופע של האובייקט DataConnect בשבילכם.

הטמעה של קוד לקוח ב-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 SDK לפרויקט, מוסיפים מפתח react לקובץ ההגדרות connector.yaml.

React

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

Angular

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

ייבוא ספריות

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

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

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

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

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

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

React

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

• השאילתות קוראות ל-hookTanStack useDataConnectQuery ומחזירות אותו
• המוטציות קוראות ומחזירות את ה-hook של TanStack useDataConnectMutation

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

Angular

הערה: ng add @angular/fire יעשה זאת בשבילכם באופן אוטומטי, אבל אם תבחרו להגדיר את זה באופן ידני, תוכלו לעשות זאת באמצעות הקוד הבא:

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

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

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

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

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

הערה: צריך להתקשר אל getDataConnect רק אם רוצים להתחבר לאמולטור Data Connect. אחרת, ה-SDK שנוצר ייצור באופן אוטומטי מופע של האובייקט DataConnect בשבילכם.

סוגי נתונים ב-SDK

השרת Data Connect מייצג סוגי נתונים נפוצים של GraphQL. אלה הנתונים שמוצגים ב-SDK:

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

שיקולים מיוחדים לגבי יצירת SDK

הגדרת נתיבים ביחס ל-node_modules

ב-JavaScript SDK, מכיוון ש-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"

לחלופין, אם יש לכם monorepo שבו המודולים מאוחסנים בספריית הבסיס, אתם יכולים למקם את ספריית הפלט בכל תיקייה ב-monorepo.

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 שמגדירים סכימות, שאילתות ומוטציות. התכונה הזו יכולה להיות שימושית בתהליכי עבודה של טעינה (מחדש) של מודולים בזמן שהאפליקציה פועלת.

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

לחלופין, אפשר להשתמש ב-CLI כדי ליצור מחדש ערכות SDK בכל פעם שמשנים קובצי ‎ .gql:

firebase dataconnect:sdk:generate --watch

יצירת ערכות SDK לשילוב ולגרסאות ייצור

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

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