استخدام SDK للمشرف مع Data Connect

Firebase Admin SDK هي مجموعة من مكتبات الخادم التي تتيح لك التفاعل مع Firebase من بيئات ذات امتيازات لتنفيذ إجراءات مثل تنفيذ طلبات البحث والتعديلات على خدمة Firebase Data Connect لإدارة البيانات المجمّعة وعمليات أخرى ذات امتيازات أعلى وبيانات اعتماد منتحلة.

توفّر لك Admin SDK واجهة برمجة تطبيقات لاستدعاء العمليات في وضعَي القراءة والكتابة والقراءة فقط. باستخدام عمليات القراءة فقط، يمكنك تنفيذ وظائف إدارية لا يمكنها تعديل البيانات في قواعد البيانات، ما يمنحك راحة البال.

إعداد حزمة SDK للمشرف

لبدء استخدام Firebase Data Connect على خادمك، عليك أولاً تثبيت Admin SDK وإعداده لـ Node.js.

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

لبدء استخدام حزمة SDK، استورِد إضافات Data Connect وحدِّد رقم تعريف خدمة مشروعك وموقعه الجغرافي.


import { initializeApp } from 'firebase-admin/app';
import { getDataConnect } from 'firebase-admin/data-connect';

// If you'd like to use OAuth2 flows and other credentials to log in,
// visit https://firebase.google.com/docs/admin/setup#initialize-sdk
// for alternative ways to initialize the SDK.

const app = initializeApp();

const dataConnect = getDataConnect({
    serviceId: 'serviceId',
    location: 'us-west2'
});

تصميم طلبات البحث وعمليات التعديل لاستخدامها مع Admin SDK

يكون Admin SDK مفيدًا لاختبار عمليات Data Connect، مع مراعاة ما يلي:

فهم حزمة تطوير البرامج (SDK) وتوجيه التشغيل @auth(level: NO_ACCESS)

بما أنّ Admin SDK يعمل بأذونات مميزة، يمكنه تنفيذ أي من طلبات البحث والتعديلات بغض النظر عن مستويات الوصول التي تم ضبطها باستخدام توجيهات @auth، بما في ذلك مستوى NO_ACCESS.

إذا كنت تنظّم طلبات البحث والتعديلات الإدارية في ملفات مصدر .gql لاستيرادها إلى البرامج النصية الإدارية، إلى جانب عمليات العميل، تنصحك Firebase بوضع علامة على العمليات الإدارية بدون أي مستوى وصول إلى التفويض، أو ربما أن تكون أكثر وضوحًا وتضبطها على NO_ACCESS. في كلتا الحالتين، يمنع ذلك تنفيذ هذه العمليات من العملاء أو في سياقات أخرى غير مميّزة.

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

في بيئات النماذج الأولية والاختبار، قد يكون من المفيد تنفيذ عمليات إعداد البيانات وعمليات أخرى على البيانات المحلية. تتيح لك السمة Admin SDK تبسيط سير العمل لأنّها تتجاهل المصادقة والتفويض في المسارات المحلية.

تربط حِزم Firebase Admin SDK تلقائيًا بالمحاكي عند ضبط متغيّر البيئة DATA_CONNECT_EMULATOR_HOST على النحو التالي:Data Connect

export DATA_CONNECT_EMULATOR_HOST="127.0.0.1:9399"

يمكنك الاطّلاع على ما يلي للحصول على مزيد من المعلومات:

تنفيذ حالات الاستخدام الشائعة

يتم توفير Admin SDK للعمليات ذات الامتيازات على بياناتك المهمة.

توفّر حزمة SDK للمشرف واجهتَين:

  • واجهة عامة لمعظم عمليات القراءة والكتابة أو القراءة فقط، حيث ينفّذ الرمز البرمجي طلبات البحث والتعديلات ويُمرّرها إلى طريقة القراءة والكتابة executeGraphql أو طريقة القراءة فقط executeGraphqlRead.
  • واجهة متخصّصة لعمليات البيانات المجمّعة، تعرض بدلاً من طرق executeGraphql العامة طرقًا مخصّصة لعمليات التعديل: insert وinsertMany وupsert وupsertMany.

إدارة بيانات المستخدمين باستخدام طرق executeGraphql

تتمثّل إحدى حالات الاستخدام النموذجية لـ Admin SDK في إدارة بيانات المستخدمين.

استخدام بيانات اعتماد إدارية

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

// User can be publicly accessible, or restricted to admins
const query = "query getProfile(id: AuthID) { user(id: $id) { id name } }";

interface UserData {
  user: {
    id: string;
    name: string;
  };
}

export interface UserVariables {
  id: string;
}

const options:GraphqlOptions<UserVariables> = { variables: { id: "QVBJcy5ndXJ1" } };

// executeGraphql
const gqlResponse = await dataConnect.executeGraphql<UserData, UserVariables>(query, options);

// executeGraphqlRead (similar to previous sample but only for read operations)
const gqlResponse = await dataConnect.executeGraphqlRead<UserData, UserVariables>(query, options);

// gqlResponse -> { "data": { "user": { "id": "QVBJcy5ndXJ1", "name": "Fred" } } }

انتحال بيانات اعتماد المستخدم

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

لاستخدام هذه الواجهة، يجب جمع المعلومات من رمز مميّز مخصّص للمصادقة باستخدام JWT يتّبع تنسيق الرمز المميّز Authentication. يمكنك أيضًا الاطّلاع على دليل الرموز المميّزة المخصّصة.

// Get the current user's data
const queryGetUserImpersonation = `
    query getUser @auth(level: USER) {
        user(key: {uid_expr: "auth.uid"}) {
            id,
            name
        }
    }`;

// Impersonate a user with the specified auth claims
const optionsAuthenticated: GraphqlOptions<undefined> = {
    impersonate: {
        authClaims: {
            sub: 'QVBJcy5ndXJ1'
        }
    }
};

// executeGraphql with impersonated authenticated user scope
const gqlResponse = await dataConnect.executeGraphql<UserData, undefined>(queryGetUserImpersonation, optionsAuthenticated);

// gqlResponse -> { "data": { "user": { "id": "QVBJcy5ndXJ1", "name": "Fred" } } }

إدارة البيانات العامة باستخدام طرق executeGraphql

يمكنك استخدام حزمة تطوير البرامج (SDK) للعمل مع البيانات المتاحة للجميع، وذلك من خلال انتحال هوية مستخدم غير مصادق عليه.

// Query to get posts, with authentication level PUBLIC
const queryGetPostsImpersonation = `
    query getPosts @auth(level: PUBLIC) {
        posts {
          description
        }
    }`;

// Attempt to access data as an unauthenticated user
const optionsUnauthenticated: GraphqlOptions<undefined> = {
    impersonate: {
        unauthenticated: true
    }
};

// executeGraphql with impersonated unauthenticated user scope
const gqlResponse = await dataConnect.executeGraphql<UserData, undefined>(queryGetPostsImpersonation, optionsUnauthenticated);

تنفيذ عمليات البيانات المجمّعة

تنصحك Firebase باستخدام Admin SDK لإجراء عمليات البيانات المجمّعة على قواعد البيانات المتاحة للاستخدام.

توفّر حزمة تطوير البرامج (SDK) الطرق التالية للتعامل مع البيانات المجمّعة. من الوسيطات المتوفّرة، تنشئ كل طريقة عملية تعديل في GraphQL وتنفّذها.


// Methods of the bulk operations API
// dc is a Data Connect admin instance from getDataConnect

const resp = await dc.insert("movie" /*table name*/, data[0]);
const resp = await dc.insertMany("movie" /*table name*/, data);
const resp = await dc.upsert("movie" /*table name*/, data[0]);
const resp = await dc.upsertMany("movie" /*table name*/, data);

ملاحظات حول الأداء في العمليات المجمّعة

سيؤدي كل طلب إلى الخلفية إلى إجراء رحلة واحدة إلى Cloud SQL، لذا كلما زاد عدد الطلبات المجمّعة، زادت سرعة المعالجة.

ومع ذلك، كلما زاد حجم الدفعة، طالت عبارة SQL التي تم إنشاؤها. وعند بلوغ الحد الأقصى لطول عبارة SQL في PostgreSQL، سيظهر لك خطأ.

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

ما هي الخطوات التالية؟