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

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

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

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

إعداد تطبيقك

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

initializeApp({...});

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

استخدِم واجهة سطر الأوامر (CLI) في 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';

استخدام طلبات البحث من JavaScript SDK

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

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

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" أو "30s" أو "1h30m".

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

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

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

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