از Admin SDK با Data Connect استفاده کنید، از Admin SDK با Data Connect استفاده کنید

کیت توسعه نرم‌افزاری مدیریت فایربیس Firebase Admin SDK مجموعه‌ای از کتابخانه‌های سرور است که به شما امکان می‌دهد از محیط‌های دارای امتیاز بالا با فایربیس تعامل داشته باشید تا اقداماتی مانند انجام کوئری‌ها و جهش‌ها را در سرویس Firebase Data Connect برای مدیریت داده‌های انبوه و سایر عملیات با امتیازات بالا و اعتبارنامه‌های جعل هویت انجام دهید.

Admin SDK یک API برای فراخوانی عملیات در هر دو حالت خواندن/نوشتن و فقط خواندنی در اختیار شما قرار می‌دهد. با عملیات فقط خواندنی، خیالتان از بابت پیاده‌سازی توابع مدیریتی که نمی‌توانند داده‌ها را در پایگاه‌های داده شما تغییر دهند، راحت است.

تنظیمات 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 به شما امکان می‌دهد گردش‌های کاری خود را ساده کنید زیرا احراز هویت و مجوز را برای جریان‌های محلی نادیده می‌گیرد.

SDK های Firebase Admin به طور خودکار با تنظیم متغیر محیطی 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);

انجام عملیات داده انبوه

فایربیس توصیه می‌کند برای عملیات داده‌های حجیم در پایگاه‌های داده عملیاتی 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);

یادداشت‌های عملکرد برای عملیات انبوه

هر درخواست به backend یک سفر رفت و برگشت به Cloud SQL را متحمل می‌شود، بنابراین هرچه تعداد درخواست‌ها بیشتر باشد، توان عملیاتی بالاتر می‌رود.

با این حال، هرچه اندازه دسته بزرگتر باشد، دستور SQL تولید شده طولانی‌تر است. هنگامی که به محدودیت طول دستور SQL در PostgreSQL برسید، با خطا مواجه خواهید شد.

در عمل، برای یافتن اندازه دسته مناسب برای حجم کار خود، آزمایش کنید.

بعدش چی؟