استخدام حِزم تطوير البرامج (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 أو مكتبات React أو Angular.
3. بالنسبة إلى React وAngular، ثبِّت حِزم Tanstack Query

4. إعداد إنشاء حزمة تطوير البرامج (SDK):

   • باستخدام الزر إضافة حزمة SDK إلى التطبيق في إضافة SQL Connect VS Code
   • من خلال تعديل connector.yaml لحزمة تطوير البرامج (SDK) المستندة إلى JavaScript أو React أو Angular

5. استيراد المكتبات والرموز البرمجية التي تم إنشاؤها باستخدام JavaScript SDK أو React أو Angular

6. تنفيذ طلبات البحث والتعديلات باستخدام JavaScript SDK أو React أو Angular

7. اختبِر ذلك من خلال إعداد المحاكي SQL Connect باستخدام حزمة تطوير البرامج (SDK) المستندة إلى JavaScript أو React أو Angular.

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

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

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

إعداد تطبيقك

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

initializeApp({...});

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

استخدِم واجهة سطر الأوامر 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 في Visual Studio Code، يمكنك استخدام واجهة سطر الأوامر (CLI) لمنصة Firebase لإبقاء حِزم 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);
}

الاشتراك لتلقّي إشعارات بالتغييرات

يمكنك الاشتراك في التغييرات (التي سيتم تعديلها في أي وقت تنفّذ فيه طلب بحث).

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`

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

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

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

تنفيذ رمز العميل لكل من React وAngular

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

توفّر هذه المكتبة مجموعة من خطافات الربط التي تسهّل بشكل كبير التعامل مع المهام غير المتزامنة باستخدام 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

ng add @angular/fire

إنشاء حزمة تطوير البرامج (SDK) لتطبيق React أو Angular

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

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

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

هناك أربع مجموعات من عمليات الاستيراد مطلوبة لإعداد رمز العميل React أو Angular: عمليات الاستيراد العامة SQL Connect وعمليات الاستيراد العامة من TanStack وعمليات الاستيراد المحددة لحِزم تطوير البرامج (SDK) التي تم إنشاؤها باستخدام JavaScript و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;
}),

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

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

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

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

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

firebase dataconnect:sdk:generate --watch

إنشاء حِزم SDK في مسارات الإنشاء

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

firebase dataconnect:sdk:generate