تتيح لك حِزم تطوير البرامج (SDK) للعميل Firebase Data Connect استدعاء طلبات البحث وعمليات التعديل من جهة الخادم مباشرةً من تطبيق Firebase. يمكنك إنشاء حزمة تطوير برامج (SDK) مخصّصة للعميل بالتوازي مع تصميم المخططات وطلبات البحث وعمليات التعديل التي تنشرها في خدمة Data Connect. بعد ذلك، يمكنك دمج الطرق من حزمة تطوير البرامج (SDK) هذه في منطق العميل.
كما ذكرنا في مكان آخر، من المهم ملاحظة أنّه لا يتم إرسال Data Connect طلبات البحث وعمليات التعديل من خلال رمز العميل وتنفيذها على الـ خادم. بدلاً من ذلك، عند نشر عمليات Data Connect، يتم تخزينها على الخادم مثل Cloud Functions. وهذا يعني أنّه عليك نشر التغييرات المقابلة من جهة العميل لتجنُّب إيقاف التطبيق لدى المستخدمين الحاليين (على سبيل المثال، في إصدارات التطبيق القديمة).
لهذا السبب، يوفّر لك Data Connect بيئة تطوير و أدوات تتيح لك إنشاء نماذج أولية للمخططات وطلبات البحث وعمليات التعديل التي تنشرها على الخادم. كما أنّه ينشئ حِزم تطوير برامج (SDK) من جهة العميل تلقائيًا أثناء إنشاء النماذج الأولية.
عند تكرار التعديلات على خدمتك وتطبيقات العميل، يصبح بإمكانك نشر التعديلات من جهة الخادم والعميل.
ما هي آلية عمل تطوير العميل؟
إذا اتّبعت الخطوات الواردة في مقالة البدء، تعرّفت على آلية العمل العامة لتطوير Data Connect. في هذا الدليل، ستجد معلومات أكثر تفصيلاً عن إنشاء حِزم تطوير برامج (SDK) على الويب من المخطط واستخدام طلبات البحث وعمليات التعديل من جهة العميل.
باختصار، لاستخدام حِزم تطوير برامج (SDK) على الويب التي تم إنشاؤها في تطبيقات العميل، عليك اتّباع الخطوات الأساسية التالية:
- أضِف Firebase إلى تطبيقك على الويب.
بعد ذلك:
- طوِّر مخطط تطبيقك.
- ابدأ رمز العميل باستخدام حزمة تطوير البرامج (SDK) في JavaScript، أو مكتبتَي React أو Angular.
- بالنسبة إلى React وAngular، ثبِّت حِزم Tanstack Query
اضبط عملية إنشاء حزمة تطوير البرامج (SDK):
- باستخدام الزر إضافة حزمة تطوير برامج (SDK) إلى التطبيق في إضافة Data Connect لـ VS Code
- من خلال تعديل ملف
connector.yamlلحزمة تطوير البرامج (SDK) في JavaScript، أو React أو Angular.
استورِد المكتبات والرمز الذي تم إنشاؤه باستخدام حزمة تطوير البرامج (SDK) في JavaScript أو React أو Angular.
نفِّذ عمليات استدعاء لطلبات البحث وعمليات التعديل باستخدام حزمة تطوير البرامج (SDK) في JavaScript، أو React أو Angular.
اختبِر التطبيق من خلال إعداد محاكي Data Connect باستخدام حزمة تطوير البرامج (SDK) في JavaScript أو React أو Angular.
تنفيذ رمز العميل باستخدام حزمة Firebase JavaScript لتطوير البرامج (SDK)
يتناول هذا القسم كيفية تنفيذ العملاء باستخدام Firebase JavaScript SDK.
إذا كنت تستخدم React أو Angular، اطّلِع على تعليمات الإعداد البديلة والروابط المؤدية إلى مستندات إضافية حول إنشاء Data Connect حِزم تطوير برامج (SDK) للإطارات.
إعداد تطبيقك
ابدأ أولاً تطبيقك باستخدام تسلسل Firebase العادي.
initializeApp({...});
ثبّت حزمة تطوير البرامج (SDK) في JavaScript التي تم إنشاؤها
استخدِم Firebase CLI لإعداد حِزم تطوير برامج (SDK) التي تم إنشاؤها في Data Connect في تطبيقاتك.
يجب أن يرصد الأمر init جميع التطبيقات في المجلد الحالي وأن يثبِّت حِزم تطوير البرامج (SDK) التي تم إنشاؤها تلقائيًا.
firebase init dataconnect:sdk
اربط تطبيقك بخدمة Data 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) أثناء إنشاء النماذج الأولية
إذا كانت إضافة Data Connect لـ VS Code مثبَّتة، ستحرص على أن تكون حِزم تطوير البرامج (SDK) التي تم إنشاؤها محدّثة دائمًا.
إذا كنت لا تستخدم إضافة Data Connect لـ VS Code، يمكنك استخدام Firebase CLI لإبقاء حِزم تطوير البرامج (SDK) التي تم إنشاؤها محدّثة.
firebase dataconnect:sdk:generate --watchإنشاء حِزم تطوير برامج (SDK) في مسارات الإنشاء
يمكنك استخدام Firebase CLI لإنشاء Data Connect في عمليات الإنشاء المتواصلة والتسليم المتواصل (CI/CD).
firebase dataconnect:sdk:generateاستيراد المكتبات
هناك مجموعتان من عمليات الاستيراد اللازمة لبدء رمز العميل: عمليات استيراد عامة Data 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.
في آلية عمل Data 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' }));
الاتصال بمحاطي Data Connect
يمكنك اختياريًا الاتصال بالمحاكي من خلال استدعاء
connectDataConnectEmulator ثم تمرير مثيل Data 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 Data Connect توفّر حزمة تطوير برامج (SDK) تم إنشاؤها باستخدام خطافات لـ React و Angular باستخدام مكتبات متوفّرة من شركائنا في Invertase، TanStack Query Firebase.
توفّر هذه المكتبة مجموعة من الخطافات التي تسهّل إلى حد كبير التعامل مع المهام غير المتزامنة باستخدام Firebase في تطبيقاتك.
إعداد تطبيقك
ابدأ أولاً تطبيقك باستخدام تسلسل Firebase العادي، كما هو الحال مع أي تطبيق ويب على Firebase.
initializeApp({...});
تثبيت حِزم TanStack Query Firebase
ثبِّت حِزم TanStack Query في مشروعك.
React
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
Angular
ng add @angular/fire
إنشاء حزمة تطوير برامج (SDK) في React أو Angular
كما هو الحال مع حزمة تطوير البرامج (SDK) العادية على الويب، كما هو موضّح سابقًا، تتعامل أدوات Firebase مع الإنشاء التلقائي لحِزم تطوير البرامج (SDK) استنادًا إلى المخطط والعمليات.
إذا أضفت للتو React أو Angular إلى مشروعك، أعِد تشغيل firebase init dataconnect:sdk لإعادة ضبط حِزم تطوير البرامج (SDK) التي تم إنشاؤها لتضمين روابط الإطار الإضافية.
استيراد المكتبات
هناك أربع مجموعات من عمليات الاستيراد اللازمة لبدء رمز العميل في React أو Angular: عمليات استيراد Data Connect العامة وعمليات استيراد TanStack العامة، وعمليات استيراد محدّدة لحِزم تطوير البرامج (SDK) التي تم إنشاؤها في JavaScript وReact.
لاحظ نوع ConnectorConfig المُضمّن في عمليات الاستيراد العامة.
React
// 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";
Angular
// 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) التي تم إنشاؤها.
React
تستدعي جميع هذه العمليات في حزمة تطوير البرامج (SDK) التي تم إنشاؤها، سواء طلبات البحث أو عمليات التعديل، روابط TanStackQuery:
- تستدعي طلبات البحث وتعرض خطاف TanStack
useDataConnectQuery - تستدعي عمليات التعديل وتعرض خطاف TanStack
useDataConnectMutation
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>
}
Angular
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
يمكنك ضبط طلبات البحث لإعادة تحميلها تلقائيًا عند تغيُّر البيانات.
React
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 });
}
}
Angular
// 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>
}
}
الاتصال بمحاطي Data Connect
يمكنك اختياريًا الاتصال بالمحاكي من خلال استدعاء
connectDataConnectEmulator ثم تمرير مثيل Data Connect
إلى الخطاف الذي تم إنشاؤه، على النحو التالي:
React
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);
...
}
Angular
// 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;
}),
للتبديل إلى موارد الإنتاج، علِّق على الأسطر الخاصة بالاتصال بالمحاكي.
تفعيل التخزين المؤقت من جهة العميل
Data 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)
يمثّل خادم Data Connect أنواع بيانات GraphQL الشائعة. ويتم تمثيلها في حزمة تطوير البرامج (SDK) على النحو التالي.
| Data Connect نوع | TypeScript |
|---|---|
| الطابع الزمني | سلسلة |
| التاريخ | سلسلة |
| معرِّف فريد عالمي (UUID) | سلسلة |
| Int64 | سلسلة |
| مزدوج | الرقم |
| عائم | الرقم |
تعديل حِزم تطوير البرامج (SDK) أثناء إنشاء النماذج الأولية
إذا كانت إضافة Data Connect لـ VS Code مثبَّتة، ستحرص على أن تكون حِزم تطوير البرامج (SDK) التي تم إنشاؤها محدّثة دائمًا.
إذا كنت لا تستخدم إضافة Data Connect لـ VS Code، يمكنك استخدام Firebase CLI لإبقاء حِزم تطوير البرامج (SDK) التي تم إنشاؤها محدّثة.
firebase dataconnect:sdk:generate --watchإنشاء حِزم تطوير برامج (SDK) في مسارات الإنشاء
يمكنك استخدام Firebase CLI لإنشاء Data Connect في عمليات الإنشاء المتواصلة والتسليم المتواصل (CI/CD).
firebase dataconnect:sdk:generate