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

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

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

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

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

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

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

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

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

بعد ذلك:

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

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

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

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

إعداد تطبيقك

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

initializeApp({...});

تثبيت حزمة JavaScript SDK التي تم إنشاؤها

استخدِم واجهة سطر الأوامر Firebase لإعداد حِزم تطوير البرامج (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 لإنشاء حِزم تطوير البرامج (SDK) الخاصة بـ SQL Connect في عمليات إنشاء 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';

استخدام طلبات البحث من حزمة تطوير البرامج (SDK) المستندة إلى 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!");
}

استخدام عمليات تغيير من حزمة تطوير البرامج (SDK) في 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. عند تفعيل هذه الميزة، ستخزّن حِزم تطوير البرامج (SDK) للعميل التي تم إنشاؤها ردود طلبات البحث مؤقتًا على الجهاز، ما قد يقلّل عدد طلبات قاعدة البيانات التي يرسلها تطبيقك ويتيح لأجزاء تطبيقك التي تعتمد على قاعدة البيانات العمل عند انقطاع الاتصال بالشبكة.

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

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

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

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

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

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

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

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

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

  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 للوقت الفعلي، ولكن مع بعض الصعوبة. ننصحك باستخدام عمليات الربط المستندة إلى TanStack أو ميزة التحديث في الوقت الفعلي المضمّنة في SQL Connect، ولكن ليس كليهما.

يُرجى العِلم أنّ التنفيذ في الوقت الفعلي الخاص بـ SQL Connect يتضمّن بعض المزايا مقارنةً بربطات 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

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

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

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

هناك أربع مجموعات من عمليات الاستيراد مطلوبة لإعداد رمز العميل في React أو Angular، وهي: عمليات الاستيراد العامة SQL 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 '@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 لإنشاء حِزم تطوير البرامج (SDK) الخاصة بـ SQL Connect في عمليات إنشاء CI/CD.

firebase dataconnect:sdk:generate