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

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

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

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

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

کد مشتری را با Firebase JavaScript SDK پیاده سازی کنید

این بخش نحوه پیاده سازی کلاینت ها با استفاده از Firebase JavaScript SDK را پوشش می دهد.

اگر از React استفاده می‌کنید، دستورالعمل‌های راه‌اندازی جایگزین و پیوندهایی به اسناد اضافی درباره ایجاد React SDK برای Data Connect را ببینید.

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

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

initializeApp({...});

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

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

گزینه‌های تولید SDK برای چندین ورودی در فایل dataconnect.yaml که هنگام راه‌اندازی پروژه خود ایجاد می‌شوند، کلید می‌شوند.

تولید SDK را راه اندازی کنید

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 پیاده سازی کنید

Firebase Data Connect با استفاده از کتابخانه ای که از شرکای ما در Invertase، TanStack Query Firebase در دسترس است، یک SDK تولید شده با قلاب هایی برای React ارائه می دهد.

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

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

همانند وب SDK استاندارد، همانطور که قبلا توضیح داده شد، ابزار Firebase تولید خودکار SDK ها را بر اساس طرح و عملیات شما انجام می دهد.

برای ایجاد یک React SDK برای پروژه خود، یک کلید react را به فایل پیکربندی connector.yaml خود اضافه کنید.

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

واردات کتابخانه ها

چهار مجموعه واردات برای مقداردهی اولیه کد کلاینت React شما مورد نیاز است: واردات کلی 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";

از کوئری ها و جهش ها در کلاینت React خود استفاده کنید

با تکمیل راه‌اندازی، می‌توانید روش‌هایی را از React SDK ایجاد شده ترکیب کنید.

در قطعه زیر به روش use -prefixed useListAllMovies از React SDK تولید شده توجه کنید. همه این عملیات use در SDK تولید شده، پرس و جو و جهش، اتصالات TanStack Query را فراخوانی می کنند:

• کوئری ها قلاب TanStack useDataConnectQuery فراخوانی کرده و برمی گرداند
• جهش ها قلاب 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>
}

به شبیه ساز 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);

function App() {
  ...
  const { isLoading, data, error } = useListAllMovies(dc);
  ...
}

برای تغییر به منابع تولید، خطوطی را برای اتصال به شبیه ساز بیان کنید.

انواع داده در SDK

سرور Data Connect نشان دهنده انواع داده های رایج GraphQL است. این موارد در SDK به شرح زیر نشان داده شده است.

ملاحظات ویژه برای تولید 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 را که طرح‌واره‌ها، پرسش‌ها و جهش‌ها را تعریف می‌کنند، تغییر می‌دهید. این می تواند یک ویژگی مفید در بارگذاری مجدد جریان های کاری داغ باشد.

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

firebase dataconnect:sdk:generate --watch

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

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

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

سایر ملاحظات چارچوب

زاویه ای

هنگام تولید کد، Angular CLI به دلیل کد بهینه‌سازی وابستگی، تغییرات جدید را دریافت نمی‌کند. برای رفع این مشکل، باید angular.json خود را تغییر دهید.

  "projects": {
    "myproject": {
      "architect": {
        "serve:": {
          "prebundle": {
            "exclude": ["@movie-app/movies"]
          }
        }
      }
    }
  }