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

تنفيذ رمز العميل باستخدام Firebase JavaScript SDK

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

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

إعداد تطبيقك

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

initializeApp({...});

تثبيت حزمة تطوير البرامج (SDK) في JavaScript التي تم إنشاؤها

استخدِم 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 لإنشاء حِزم تطوير البرامج (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" و"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) على النحو التالي.

إنشاء حِزم تطوير البرامج (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

كما هو الحال مع حزمة تطوير البرامج (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