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

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

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

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

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

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

كما هو الحال مع معظم مشاريع Firebase، يتم تنفيذ العمل على Firebase Data Connect العميل الرمز في دليل مشروع على الجهاز. تُعد كل من إضافة Data Connect VS Code وواجهة سطر الأوامر Firebase أداتَين محليتَين مهمتَين لإنشاء رمز العميل وإدارته.

تعتمد خيارات إنشاء حزمة تطوير البرامج (SDK) على عدة إدخالات في ملف dataconnect.yaml الذي تم إنشاؤه عند إعداد مشروعك.

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

في connector.yaml، أضِف outputDir وpackage و (بالنسبة إلى حزمة تطوير البرامج (SDK) على الويب) packageJsonDir. 
generate:
  javascriptSdk:
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

outputDir لتحديد المكان الذي يجب أن يتم فيه إنشاء حزمة SDK.

package لتحديد اسم الحزمة

packageJsonDir لتحديد مكان تثبيت الحزمة

في هذه الحالة، يجب تثبيت firebase@latest لضمان استيفاء هذا الشرط.

ضبط المسارات بالنسبة إلى node_modules

بالنسبة إلى حزمة تطوير البرامج (SDK) للويب، بما أنّ Data Connect يستخدم npm link لتثبيت حزمة SDK، يجب إخراج حزمة SDK التي تم إنشاؤها في دليل على المستوى نفسه لمسار node_modules أو في دليل فرعي يمكنه الوصول إلى node_modules.

بعبارة أخرى، يجب أن تتمكن حزمة SDK التي تم إنشاؤها من الوصول إلى firebase وحدة node لكي تعمل بشكل صحيح.

على سبيل المثال، إذا كان لديك node_modules في my-app/، يجب أن يكون دليل الإخراج my-app/js-email-generated حتى يكون بإمكان js-email-generated الاستيراد من مجلد node_modules الرئيسي.

my-app/
  dataconnect/
    connector/
        connector.yaml
  node_modules/
    firebase/
  js-email-generated/

// connector.yaml
connectorId: "my-connector"
generate:
  javascriptSdk:
    outputDir: "../../js-email-generated"
    package: "@myapp/my-connector"

أو إذا كان لديك مستودع متعدّد الوحدات يتم فيه استضافة الوحدات في الجذر، يمكنك وضع دليل الإخراج في أي مجلد في مستودعك المتعدّد الوحدات.

my-monorepo/
  dataconnect/
    connector/
        connector.yaml
  node_modules/
    firebase/
  my-app/
    js-email-generated/
  package.json

// connector.yaml
connectorId: "my-connector"
generate:
  javascriptSdk:
    outputDir: "../../my-app/js-email-generated" # You can also output to ../../js-email-generated

تعديل حِزم تطوير البرامج (SDK) أثناء إنشاء النماذج الأولية

إذا كنت تنشئ نماذج أولية بشكل تفاعلي باستخدام إضافة Data Connect VS Code ومحاكي Data Connect الخاص بها، سيتم إنشاء ملفات SDK المصدر وتعديلها تلقائيًا أثناء تعديل ملفات .gql التي تحدّد المخططات وطلبات البحث والطفرات. يمكن أن تكون هذه ميزة مفيدة في سير عمل (إعادة) التحميل السريع.

في سيناريوهات أخرى، إذا كنت تستخدم محاكي Data Connect من سطر أوامر Firebase، يمكنك ضبط ميزة "مراقبة" على تحديثات .gql وتعديل مصادر SDK تلقائيًا.

بدلاً من ذلك، يمكنك استخدام سطر الأوامر لإعادة إنشاء حِزم تطوير البرامج (SDK) عند تغيير ملفات ‎.gql:

firebase dataconnect:sdk:generate --watch

إنشاء حِزم SDK للدمج والإصدارات العلنية

في بعض السيناريوهات، مثل إعداد مصادر المشاريع لإرسالها إلى اختبارات التكامل المستمر، يمكنك استدعاء Firebase CLI لإجراء تحديث مجمّع.

وفي هذه الحالات، استخدِم السمة firebase dataconnect:sdk:generate.

إعداد رمز العميل

بدء تطبيق Data Connect

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

initializeApp({...});

إعداد حزمة تطوير البرامج (SDK) Data Connect للويب

ابدأ تشغيل مثيل Data Connect باستخدام المعلومات التي استخدَمتها لإعداد Data Connect (كلّها متوفّرة في Firebase console علامة التبويب Data Connect).

عنصر ConnectorConfig

تتطلّب حزمة تطوير البرامج (SDK) كائن إعدادات الموصّل.

يتم إنشاء هذا العنصر تلقائيًا من serviceId وlocation في dataconnect.yaml وconnectorId في connector.yaml.

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

هناك مجموعتان من عمليات الاستيراد اللازمة لبدء رمز العميل، وهما عمليات استيراد عامة Data Connect وعمليات استيراد محدّدة تم إنشاؤها لحِزم تطوير البرامج (SDK).

// 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 '@myorg/myconnector';

إنشاء نماذج أولية لعملاء الويب واختبارهم

إعداد التطبيقات لاستخدام محاكي محلي

يمكنك استخدام محاكي Data Connect، سواء من إضافة Data Connect في VS Code أو من سطر الأوامر.

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

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@myorg/myconnector'; // Replace with your package name
const dataConnect = getDataConnect(connectorConfig);

connectDataConnectEmulator(dataConnect, 'localhost', 9399);`

// Make calls from your app

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

الحصول على مثيل

لا يُشترط الاتصال بـ getDataConnect إلا إذا أردت الاتصال بمحاكي Data Connect. بخلاف ذلك، ستنشئ حزمة تطوير البرامج (SDK) التي تم إنشاؤها مثيلًا لعنصر DataConnect تلقائيًا.

استخدام طلبات البحث من جهة العميل

سيتضمّن الرمز الذي تم إنشاؤه مراجع طلبات بحث محدّدة مسبقًا. ما عليك سوى استيرادها واستدعاء execute عليها.

import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@movie-app/movies';

const ref = listMoviesRef();
const { data } = await executeQuery(ref);
console.log(data.movies);

طرق طلب البحث في حزمة تطوير البرامج (SDK) للاتصال

في ما يلي مثال على استخدام دوال اختصارات الإجراءات هذه:

import { listMovies } from '@movie-app/movies';
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`

استخدام التغييرات من جانب العميل

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

import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@movie-app/movies';

const { data } = await executeMutation(createMovieRef({ movie: 'Empire Strikes Back' }));

أنواع البيانات في حزمة SDK على الويب

يمثل خادم Data Connect أنواع بيانات GraphQL الشائعة. يتم تمثيل هذه العناصر في حزمة SDK على النحو التالي.

نوع ربط البيانات TypeScript
الطابع الزمني السلسلة
التاريخ السلسلة
معرِّف فريد عالمي (UUID) السلسلة
Int64 السلسلة
مزدوج الرقم
عائم الرقم

اعتبارات حول الأطر

Angular

عند إنشاء الرمز، لن يرصد Angular CLIالتغييرات الجديدة بسبب رمز تحسين التبعيات. لحلّ هذه المشكلة، عليك تعديل angular.json.

  "projects": {
      "myproject": {
         "architect": {
                 "serve:": {
                            "prebundle": {
                                         "exclude": ["@movie-app/movies"]
                              }
                   }
            }
     }
  }