استخدام 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 لإجراء عمليات مميّزة على بياناتك المهمة.

تتألف واجهة برمجة التطبيقات لخدمة Data Connect من واجهة executeGraphql للقراءة والكتابة وواجهة executeGraphqlRead للقراءة فقط.

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

وتشمل حالات الاستخدام الشائعة لـ 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" } } }

إدارة البيانات المتاحة للجميع

يمكنك العمل مع البيانات المتاحة للجميع باستخدام حزمة تطوير البرامج (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);

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