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

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

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

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

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

إعداد حزمة Admin 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 تبسيط عمليات سير العمل لأنّه يتجاهل المصادقة والتفويض لعمليات سير العمل المحلية.

تتصل حِزم تطوير البرامج (SDK) الخاصة بمسؤولي Firebase تلقائيًا بمحاكي Data Connect عند ضبط متغيّر البيئة DATA_CONNECT_EMULATOR_HOST:

export DATA_CONNECT_EMULATOR_HOST="127.0.0.1:9399"

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

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

يتم توفير Admin SDK لإجراء عمليات مميّزة على بياناتك المهمة.

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

  • واجهة عامة لمعظم عمليات القراءة والكتابة أو القراءة فقط، حيث ينفذ الرمز البرمجي طلبات البحث والطفرات ويمرّرها إلى طريقة القراءة والكتابة executeGraphql أو طريقة القراءة فقط executeGraphqlRead.
  • واجهة مخصّصة لعمليات البيانات المجمّعة، والتي تعرض طرقًا مخصّصة لعمليات التغيير بدلاً من methodsexecuteGraphql العامة: 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، ستظهر لك خطأ.

في الممارسة العملية، جرِّب للعثور على حجم الحزمة المناسب لحجم العمل.

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