استخدام حِزم تطوير البرامج (SDK) على الويب التي تم إنشاؤها

تتيح لك حِزم تطوير البرامج (SDK) للعميل Firebase SQL Connect استدعاء طلبات البحث والتعديلات من جهة الخادم مباشرةً من تطبيق Firebase. يمكنك إنشاء حزمة تطوير برامج (SDK) مخصّصة للعميل بالتوازي مع تصميم المخططات وطلبات البحث والتعديلات التي تنشرها في خدمة SQL Connect. بعد ذلك، يمكنك دمج الطرق من حزمة تطوير البرامج (SDK) هذه في منطق العميل.

كما ذكرنا في مكان آخر، من المهم الإشارة إلى أنّ SQL Connect طلبات البحث والتعديلات لا يرسلها رمز العميل، بل يتم تنفيذها على الخادم. بدلاً من ذلك، عند نشر عمليات SQL Connect، يتم تخزينها على الخادم مثل Cloud Functions. هذا يعني أنّه عليك نشر التغييرات المقابلة من جهة العميل لتجنُّب إيقاف عمل التطبيقات لدى المستخدمين الحاليين (مثلاً، على إصدارات التطبيقات القديمة).

لهذا السبب، يوفّر لك SQL Connect بيئة تطوير و أدوات تتيح لك إنشاء نماذج أولية للمخططات وطلبات البحث والتعديلات التي تنشرها على الخادم. كما أنّه ينشئ حِزم تطوير برامج (SDK) من جهة العميل تلقائيًا أثناء إنشاء النماذج الأولية.

بعد تكرار التعديلات على خدمتك وتطبيقات العميل، يصبح بإمكانك نشر التعديلات من جهة الخادم والعميل.

ما هي سير عمل تطوير العميل؟

إذا اتّبعت الخطوات الواردة في مقالة البدء، تعرّفت على سير عمل التطوير العام لـ SQL Connect. في هذا الدليل، ستجد معلومات أكثر تفصيلاً عن إنشاء حِزم تطوير برامج (SDK) على الويب من المخطط واستخدام طلبات البحث والتعديلات من جهة العميل.

باختصار، لاستخدام حِزم تطوير برامج (SDK) على الويب التي تم إنشاؤها في تطبيقات العميل، عليك اتّباع الخطوات الأساسية التالية:

1. أضِف Firebase إلى تطبيقك على الويب.

بعد ذلك:

1. طوِّر مخطط تطبيقك.
2. ابدأ رمز العميل باستخدام حزمة تطوير برامج JavaScript.
3. اضبط عملية إنشاء حزمة تطوير البرامج (SDK):
   • باستخدام الزر إضافة حزمة تطوير برامج (SDK) إلى التطبيق في إضافة SQL Connect لبرنامج VS Code.
   • من خلال تعديل ملف connector.yaml لحزمة تطوير برامج JavaScript.
4. استورِد المكتبات والرمز الذي تم إنشاؤه باستخدام حزمة تطوير برامج JavaScript.
5. نفِّذ عمليات استدعاء لطلبات البحث والتعديلات باستخدام حزمة تطوير برامج JavaScript.
6. اختبِر من خلال إعداد محاكي SQL Connect باستخدام حزمة تطوير برامج JavaScript.

تنفيذ رمز العميل باستخدام حزمة تطوير برامج Firebase JavaScript

يغطّي هذا القسم كيفية تنفيذ العملاء باستخدام حزمة تطوير برامج Firebase JavaScript.

إذا كنت تستخدم React أو Angular، اطّلِع على تعليمات الإعداد البديلة والروابط المؤدية إلى مستندات إضافية حول إنشاء SQL Connect حِزم تطوير برامج (SDK) من أجل الأُطر.

إعداد تطبيقك

ابدأ أولاً بإعداد تطبيقك باستخدام تسلسل Firebase العادي .

initializeApp({...});

تثبيت JavaScript SDK الذي تم إنشاؤه

استخدِم Firebase CLI لإعداد حِزم تطوير برامج (SDK) التي تم إنشاؤها في SQL Connect في تطبيقاتك. يجب أن يرصد الأمر init جميع التطبيقات في المجلد الحالي وأن يثبِّت حِزم تطوير البرامج (SDK) التي تم إنشاؤها تلقائيًا.

firebase init dataconnect:sdk

اربط تطبيقك بخدمة SQL 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) أثناء إنشاء النماذج الأولية

إذا كانت إضافة SQL Connect لبرنامج VS Code مثبّتة، ستحرص دائمًا على أن تكون حِزم تطوير البرامج (SDK) التي تم إنشاؤها حديثة.

إذا كنت لا تستخدم إضافة SQL Connect لبرنامج VS Code، يمكنك استخدام Firebase CLI للحفاظ على حِزم تطوير البرامج (SDK) التي تم إنشاؤها حديثة.

firebase dataconnect:sdk:generate --watch

إنشاء حِزم تطوير برامج (SDK) في مسارات الإصدار

يمكنك استخدام Firebase CLI لإنشاء SQL Connect حِزم تطوير برامج (SDK) في عمليات الإصدار CI/CD.

firebase dataconnect:sdk:generate

استيراد المكتبات

هناك مجموعتان من عمليات الاستيراد اللازمة لبدء رمز العميل: عمليات استيراد عامة SQL 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

سيأتي الرمز الذي تم إنشاؤه مع مراجع طلبات بحث محدّدة مسبقًا. كل ما عليك فعله هو استيرادها واستدعاء `execute` عليها.

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

الاشتراك في التغييرات

اطّلِع على مقالة تلقّي آخر المعلومات من SQL Connect.

التعامل مع التغييرات في حقول التعداد

يمكن أن يحتوي مخطط التطبيق على عمليات تعداد، يمكن الوصول إليها من خلال طلبات بحث GraphQL.

مع تغيُّر تصميم التطبيق، يمكنك إضافة قيم تعداد جديدة متوافقة. على سبيل المثال، لنفترض أنّك قرّرت لاحقًا في مراحل نشاط تطبيقك إضافة قيمة `FULLSCREEN` إلى تعداد AspectRatio.

في سير عمل SQL Connect، يمكنك استخدام أدوات التطوير المحلية لـ تعديل طلبات البحث وحِزم تطوير البرامج (SDK).

ومع ذلك، قبل إصدار إصدار معدّل من عملائك، قد يتوقف عمل العملاء الذين تم نشرهم سابقًا.

مثال على التنفيذ المرن

أضِف دائمًا فرع default إلى عبارة switch على قيم التعداد، أو فرع else إلى كتلة if/else if تقارن قيم التعداد. لا تفرض لغة JavaScript/TypeScript ذلك، ولكنّها الطريقة لجعل رمز العميل قويًا في حال إضافة قيم تعداد جديدة.

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

يمكن الوصول إلى التعديلات بالطريقة نفسها التي يمكن الوصول بها إلى طلبات البحث.

import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@dataconnect/generated';

const { data } = await executeMutation(createMovieRef({ movie: 'Empire Strikes Back' }));

الاتصال بمحاكي SQL Connect

يمكنك اختياريًا الاتصال بالمحاكي من خلال استدعاء connectDataConnectEmulator ثم تمرير مثيل SQL 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

للتبديل إلى موارد الإنتاج، علِّق على الأسطر الخاصة بالاتصال بالمحاكي.

تفعيل التخزين المؤقت من جهة العميل

يتضمّن SQL Connect ميزة اختيارية للتخزين المؤقت من جهة العميل، يمكنك تفعيلها من خلال تعديل ملف connector.yaml. عند تفعيل هذه الميزة، ستخزّن حِزم تطوير برامج العميل التي تم إنشاؤها مؤقتًا ردود طلبات البحث محليًا، ما يمكن أن يقلّل عدد طلبات قاعدة البيانات التي يقدّمها تطبيقك ويسمح للأجزاء المستندة إلى قاعدة البيانات في تطبيقك بالعمل عند انقطاع توفُّر الشبكة.

لتفعيل التخزين المؤقت من جهة العميل، أضِف إعدادات التخزين المؤقت من جهة العميل إلى إعدادات الموصّل:

generate:
  javascriptSdk:
    outputDir: ../web/
    package: "@dataconnect/generated"
    clientCache:
      maxAge: 5s
      storage: memory

يحتوي هذا الإعداد على مَعلمتَين، كلتاهما اختياريتان:

• maxAge: الحد الأقصى لعمر الردّ المخزّن مؤقتًا قبل أن تجلب حزمة تطوير برامج العميل قيمًا جديدة. أمثلة: "0" و"30s" و"1h30m".

  القيمة التلقائية لـ maxAge هي 0، ما يعني أنّه يتم تخزين الردود مؤقتًا، ولكن ستجلب حزمة تطوير برامج العميل دائمًا قيمًا جديدة. لن يتم استخدام القيم المخزّنة مؤقتًا إلا عند تحديد CACHE_ONLY لـ executeQuery() والنتيجة الأولية التي يتم عرضها من subscribe().

• storage: يمكن إعداد حزمة تطوير برامج العميل لتخزين الردود مؤقتًا إما في مساحة تخزين persistent أو في memory. ستبقى النتائج المخزّنة مؤقتًا في مساحة التخزين persistent بعد إعادة تشغيل التطبيق. في حِزم تطوير برامج الويب، لا تتوفّر إلا مساحة التخزين memory.

بعد تعديل إعدادات التخزين المؤقت للموصّل، أعِد إنشاء حِزم تطوير برامج العميل وأعِد إنشاء تطبيقك. بعد إجراء ذلك، سيخزّن executeQuery() وsubscribe() الردود مؤقتًا ويستخدِمان القيم المخزّنة مؤقتًا وفقًا للسياسة التي أعددتها. يحدث ذلك تلقائيًا بشكل عام، بدون أي خطوات إضافية من جانبك، ولكن يُرجى العِلم بما يلي:

• يكون السلوك التلقائي لـ executeQuery() كما هو موضّح أعلاه: إذا تم تخزين نتيجة مؤقتًا لطلب بحث ولم تكن القيمة المخزّنة مؤقتًا أقدم من maxAge، استخدِم القيمة المخزّنة مؤقتًا. يُطلق على هذا السلوك التلقائي سياسة PREFER_CACHE.

  يمكنك أيضًا تحديد عمليات استدعاء فردية لـ executeQuery() إما لعرض القيم المخزّنة مؤقتًا فقط (CACHE_ONLY) أو لجلب قيم جديدة من الخادم بشكل غير مشروط (SERVER_ONLY).

  await executeQuery(queryRef, QueryFetchPolicy.CACHE_ONLY);
  

  await executeQuery(queryRef, QueryFetchPolicy.SERVER_ONLY);
  

• عند استدعاء subscribe()، سيعرض دائمًا المحتوى المخزّن مؤقتًا على الفور إذا كان متوفرًا، بغض النظر عن إعداد maxAge. ستُعلم عمليات الاستدعاء اللاحقة لـ executeQuery() المستمعين وفقًا لـ maxAge الذي تم إعداده.

أنواع البيانات في حزمة تطوير البرامج (SDK)

يمثّل خادم SQL Connect أنواع بيانات GraphQL الشائعة. ويتم تمثيلها في حزمة تطوير البرامج (SDK) على النحو التالي.

إنشاء حِزم تطوير برامج (SDK) لـ React وAngular باستخدام TanStack

Firebase SQL Connect يوفّر حزمة تطوير برامج (SDK) تم إنشاؤها باستخدام خطافات لـ React و Angular باستخدام مكتبات متوفّرة من شركائنا في Invertase، TanStack Query Firebase.

توفّر هذه المكتبة مجموعة من الخطافات التي تسهّل إلى حد كبير التعامل مع المهام غير المتزامنة باستخدام Firebase في تطبيقاتك.

يأتي TanStack مع عملية التنفيذ الخاصة به للتخزين المؤقت من جهة العميل والاشتراكات في الوقت الفعلي، والتي يمكن أن تعمل جنبًا إلى جنب مع SQL Connect's ميزة الدعم في الوقت الفعلي المضمّنة، ولكن مع بعض الصعوبة فقط. ننصحك باستخدام عمليات الربط المستندة إلى TanStack أو SQL Connect's ميزة الدعم في الوقت الفعلي المضمّنة، ولكن ليس كلتيهما.

يُرجى العِلم أنّ عملية التنفيذ في الوقت الفعلي الخاصة بـ SQL Connect's تتضمّن بعض المزايا مقارنةً بعمليات الربط في TanStack:

• التخزين المؤقت العادي: SQL Connect ينفّذ التخزين المؤقت العادي، ما يحسّن اتساق البيانات وكفاءة الذاكرة والشبكة مقارنةً بالتخزين المؤقت على مستوى طلب البحث. باستخدام التخزين المؤقت العادي، إذا تم تعديل كيان في منطقة واحدة من تطبيقك، سيتم تعديله أيضًا في المناطق الأخرى التي تستخدم هذا الكيان.
• الإبطال عن بُعد: يمكن لـ SQL Connect إبطال الكيانات المخزّنة مؤقتًا عن بُعد على جميع الأجهزة المشترِكة.

إعداد تطبيقك

ابدأ أولاً، كما هو الحال مع أي تطبيق ويب من 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

كما هو الحال مع حزمة تطوير برامج الويب العادية، كما هو موضّح سابقًا، تتعامل أدوات Firebase مع عملية الإنشاء التلقائي لحِزم تطوير البرامج (SDK) استنادًا إلى المخطط والعمليات.

إذا أضفت للتو React أو Angular إلى مشروعك، أعِد تشغيل firebase init dataconnect:sdk لإعادة إعداد حِزم تطوير البرامج (SDK) التي تم إنشاؤها لتضمين عمليات الربط الإضافية لإطار العمل.

استيراد المكتبات

هناك أربع مجموعات من عمليات الاستيراد اللازمة لبدء رمز العميل في React أو Angular: عمليات استيراد SQL Connect العامة وعمليات استيراد TanStack العامة، وعمليات استيراد محدّدة لحِزم تطوير برامج 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) التي تم إنشاؤها.

في المقتطف التالي، يُرجى العِلم بالطريقة التي تبدأ بـ use useListAllMovies لـ React والطريقة التي تبدأ بـ inject injectListAllMovies لـ 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>
    }
}

الاتصال بمحاكي SQL Connect

يمكنك اختياريًا الاتصال بالمحاكي من خلال استدعاء connectDataConnectEmulator ثم تمرير SQL Connect المثيل إلى الخطاف الذي تم إنشاؤه، على النحو التالي:

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) أثناء إنشاء النماذج الأولية

إذا كانت إضافة SQL Connect لبرنامج VS Code مثبّتة، ستحرص دائمًا على أن تكون حِزم تطوير البرامج (SDK) التي تم إنشاؤها حديثة.

إذا كنت لا تستخدم إضافة SQL Connect لبرنامج VS Code، يمكنك استخدام Firebase CLI للحفاظ على حِزم تطوير البرامج (SDK) التي تم إنشاؤها حديثة.

firebase dataconnect:sdk:generate --watch

إنشاء حِزم تطوير برامج (SDK) في مسارات الإصدار

يمكنك استخدام Firebase CLI لإنشاء SQL Connect حِزم تطوير برامج (SDK) في عمليات الإصدار CI/CD.

firebase dataconnect:sdk:generate