از وب SDK های تولید شده استفاده کنید

SDK های مشتری Firebase Data Connect به شما امکان می دهند پرس و جوها و جهش های سمت سرور خود را مستقیماً از یک برنامه Firebase فراخوانی کنید. همزمان با طراحی طرحواره ها، پرس و جوها و جهش هایی که در سرویس Data Connect خود مستقر می کنید، یک SDK مشتری سفارشی ایجاد می کنید. سپس، شما متدها را از این SDK در منطق کلاینت خود ادغام می کنید.

همانطور که در جاهای دیگر ذکر کردیم، توجه به این نکته مهم است که کوئری‌ها و جهش‌های Data Connect توسط کد مشتری ارسال نمی‌شوند و روی سرور اجرا نمی‌شوند. در عوض، هنگام استقرار، عملیات Data Connect مانند توابع ابری در سرور ذخیره می شود. این بدان معناست که شما باید تغییرات سمت کلاینت مربوطه را برای جلوگیری از شکستن کاربران موجود (مثلاً در نسخه‌های قدیمی‌تر برنامه) اعمال کنید.

به همین دلیل است که Data Connect یک محیط توسعه‌دهنده و ابزاری را در اختیار شما قرار می‌دهد که به شما امکان می‌دهد طرح‌واره‌ها، پرسش‌ها و جهش‌های مستقر در سرور خود را نمونه‌سازی کنید. همچنین در حالی که شما نمونه سازی می کنید، SDK های سمت سرویس گیرنده را به طور خودکار تولید می کند.

هنگامی که به‌روزرسانی‌های سرویس و برنامه‌های سرویس گیرنده خود را تکرار کردید، به‌روزرسانی‌های سمت سرور و سرویس گیرنده آماده اجرا هستند.

گردش کار توسعه مشتری چیست؟

اگر شروع به کار را دنبال کنید، با جریان کلی توسعه برای Data Connect آشنا شده اید. در این راهنما، اطلاعات دقیق تری در مورد تولید SDK های وب از طرحواره خود و کار با پرس و جوها و جهش های مشتری پیدا خواهید کرد.

به طور خلاصه، برای استفاده از وب SDK های تولید شده در برنامه های مشتری خود، این مراحل پیش نیاز را دنبال می کنید:

  1. Firebase را به برنامه وب خود اضافه کنید.

سپس:

  1. طرح برنامه خود را توسعه دهید.
  2. کد مشتری خود را با جاوا اسکریپت 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 Connect SDK برای چارچوب‌ها را ببینید.

برنامه خود را راه اندازی کنید

ابتدا، برنامه خود را با استفاده از دنباله استاندارد Firebase مقداردهی کنید.

initializeApp({...});

JavaScript SDK خود را ایجاد کنید

مانند بسیاری از پروژه های Firebase، کار بر روی کد مشتری Firebase Data Connect در یک فهرست پروژه محلی انجام می شود. هم افزونه Data Connect VS Code و هم Firebase CLI ابزارهای محلی مهمی برای تولید و مدیریت کد مشتری هستند.

گزینه‌های تولید 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@latest را نصب کنید تا اطمینان حاصل کنید که این وابستگی به همتایان برآورده شده است.

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';

از جستارهای جاوا اسکریپت SDK استفاده کنید

کد تولید شده از قبل با Query Refs از پیش تعریف شده همراه خواهد بود. تنها کاری که باید انجام دهید این است که آن ها را وارد کرده و اجرا کنید.

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 با استفاده از کتابخانه‌های موجود در شرکای ما در Invertase، TanStack Query Firebase ، یک SDK تولید شده با قلاب‌هایی برای React و Angular ارائه می‌کند.

این کتابخانه مجموعه‌ای از قلاب‌ها را فراهم می‌کند که مدیریت وظایف ناهمزمان با 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 خود را ایجاد کنید

همانند وب 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، و واردات خاص برای JS و React SDK های تولید شده شما.

به نوع 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 -prefixed useListAllMovies برای React و inject -prefixed متد injectListAllMovies برای Angular توجه کنید، هر دو از SDK تولید شده.

واکنش نشان دهیدزاویه ای

همه این عملیات در SDK تولید شده، پرس و جو و جهش، اتصالات TanStackQuery را فراخوانی می کنند:

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 به شرح زیر نشان داده شده است.

نوع اتصال داده TypeScript
مهر زمان رشته
تاریخ رشته
UUID رشته
Int64 رشته
دوبل شماره
شناور شماره

ملاحظات ویژه برای تولید SDK

مسیرها را نسبت به node_modules پیکربندی کنید

برای جاوا اسکریپت 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 از Firebase CLI استفاده می‌کنید، می‌توانید ساعتی را روی به‌روزرسانی‌های .gql تنظیم کنید و همچنین منابع SDK را به‌طور خودکار به‌روزرسانی کنید.

همچنین، می‌توانید هر زمان که فایل‌های .gql تغییر می‌کنند، از CLI برای بازسازی SDK‌ها استفاده کنید: 

firebase dataconnect:sdk:generate --watch

SDK ها را برای ادغام و برای انتشار تولید ایجاد کنید

در برخی از سناریوها، مانند آماده کردن منابع پروژه برای ارسال برای آزمایش‌های CI، می‌توانید برای به‌روزرسانی دسته‌ای با Firebase CLI تماس بگیرید.

در این موارد، از firebase dataconnect:sdk:generate استفاده کنید.