ডাটা কানেক্টের সাথে অ্যাডমিন SDK ব্যবহার করুন, ডাটা কানেক্টের সাথে অ্যাডমিন SDK ব্যবহার করুন

Firebase Admin SDK হলো সার্ভার লাইব্রেরির একটি সেট যা আপনাকে বিশেষাধিকারপ্রাপ্ত পরিবেশ থেকে ফায়ারবেসের সাথে যোগাযোগ করতে দেয়। এর মাধ্যমে আপনি বাল্ক ডেটা ম্যানেজমেন্টের জন্য Firebase Data Connect সার্ভিসে কোয়েরি ও মিউটেশন চালানোর মতো কাজ এবং উচ্চতর বিশেষাধিকার ও ছদ্মবেশী ক্রেডেনশিয়াল ব্যবহার করে অন্যান্য অপারেশন সম্পাদন করতে পারেন।

Admin SDK আপনাকে রিড/রাইট এবং রিড-অনলি উভয় মোডে অপারেশন কল করার জন্য একটি এপিআই প্রদান করে। রিড-অনলি অপারেশনের মাধ্যমে, আপনি এমন প্রশাসনিক ফাংশনগুলো নিশ্চিন্তে প্রয়োগ করতে পারেন যা আপনার ডেটাবেসের ডেটা পরিবর্তন করতে পারে না।

অ্যাডমিন এসডিকে সেটআপ

আপনার সার্ভারে Firebase Data Connect ব্যবহার শুরু করতে, আপনাকে প্রথমে 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 সাথে ব্যবহারের জন্য কোয়েরি এবং মিউটেশন ডিজাইন করুন

নিম্নলিখিত বিষয়গুলো বিবেচনায় রাখলে, Data Connect অপারেশনগুলো চালানোর জন্য Admin SDK উপযোগী।

SDK এবং @auth(level: NO_ACCESS) অপারেশন নির্দেশিকাটি বুঝুন।

যেহেতু Admin SDK বিশেষাধিকার নিয়ে কাজ করে, তাই এটি @auth নির্দেশিকা ব্যবহার করে সেট করা অ্যাক্সেস লেভেল, এমনকি NO_ACCESS লেভেল নির্বিশেষে, আপনার যেকোনো কোয়েরি এবং মিউটেশন সম্পাদন করতে পারে।

যদি আপনার ক্লায়েন্ট অপারেশনের পাশাপাশি, আপনি অ্যাডমিনিস্ট্রেটিভ স্ক্রিপ্টে ইম্পোর্ট করার জন্য আপনার অ্যাডমিনিস্ট্রেটিভ কোয়েরি এবং মিউটেশনগুলিকে .gql সোর্স ফাইলে সাজিয়ে রাখেন, তাহলে Firebase পরামর্শ দেয় যে আপনি অ্যাডমিনিস্ট্রেটিভ অপারেশনগুলিকে কোনো অথরাইজেশন অ্যাক্সেস লেভেল ছাড়াই চিহ্নিত করুন, অথবা আরও সুস্পষ্টভাবে সেগুলিকে NO_ACCESS হিসাবে সেট করুন। উভয় ক্ষেত্রেই, এটি ক্লায়েন্ট থেকে বা অন্যান্য নন-প্রিভিলেজড প্রেক্ষাপটে এই ধরনের অপারেশনগুলি চালানো থেকে বিরত রাখে।

Data Connect এমুলেটরের সাথে SDK ব্যবহার করুন

প্রোটোটাইপ এবং টেস্ট এনভায়রনমেন্টে, লোকাল ডেটার উপর ডেটা সিডিং এবং অন্যান্য অপারেশন সম্পাদন করা উপযোগী হতে পারে। Admin SDK আপনার ওয়ার্কফ্লোকে সহজ করে তোলে, কারণ এটি লোকাল ফ্লো-এর জন্য অথেনটিকেশন এবং অথরাইজেশন উপেক্ষা করতে পারে। (আপনি ইউজার ইমপার্সোনেশনের মাধ্যমে আপনার অপারেশনের অথেনটিকেশন এবং অথরাইজেশন কনফিগারেশন মেনে চলার জন্য স্পষ্টভাবে অপ্ট-ইনও করতে পারেন।)

যখন DATA_CONNECT_EMULATOR_HOST এনভায়রনমেন্ট ভেরিয়েবলটি সেট করা থাকে, তখন Firebase Admin SDK-গুলো স্বয়ংক্রিয়ভাবে Data Connect এমুলেটরের সাথে সংযুক্ত হয়।

export DATA_CONNECT_EMULATOR_HOST="127.0.0.1:9399"

আরও তথ্যের জন্য দেখুন:

অ্যাডমিন অপারেশন চালান

আপনার গুরুত্বপূর্ণ ডেটার উপর বিশেষাধিকারপ্রাপ্ত কার্যক্রম পরিচালনার জন্য Admin SDK প্রদান করা হয়।

অ্যাডমিন এসডিকে তিন সেট এপিআই প্রদান করে:

  • জেনারেটেড অ্যাডমিন SDK-গুলো হলো টাইপ-সেফ SDK, যা আপনার gql ডেফিনিশন থেকে ঠিক সেইভাবেই জেনারেট করা হয়, যেভাবে আপনি ক্লায়েন্ট SDK জেনারেট করেন।
  • যেকোনো GraphQL অপারেশন চালানোর জন্য একটি সাধারণ ইন্টারফেস, যেখানে আপনার কোড কোয়েরি ও মিউটেশন ইমপ্লিমেন্ট করে এবং সেগুলোকে রিড-রাইট executeGraphql মেথড অথবা রিড-অনলি executeGraphqlRead মেথডে পাস করে।
  • বাল্ক ডেটা অপারেশনের জন্য একটি বিশেষায়িত ইন্টারফেস, যা সাধারণ executeGraphql মেথডের পরিবর্তে মিউটেশন অপারেশনের জন্য ডেডিকেটেড মেথড প্রদান করে: insert , insertMany , upsert , এবং upsertMany ।

জেনারেট করা SDK ব্যবহার করে ডেটা পরিচালনা করুন

যেভাবে ক্লায়েন্ট SDK তৈরি করেন, ঠিক সেইভাবেই আপনার gql ডেফিনিশনগুলো থেকে অ্যাডমিন SDK তৈরি করতে পারেন।

তৈরি করা অ্যাডমিন SDK-টিতে আপনার gql ডেফিনিশনের সাথে সামঞ্জস্যপূর্ণ ইন্টারফেস এবং ফাংশন রয়েছে, যা আপনি আপনার ডেটাবেসে বিভিন্ন অপারেশন সম্পাদন করতে ব্যবহার করতে পারেন। উদাহরণস্বরূপ, ধরুন আপনি গানের একটি ডেটাবেসের জন্য একটি SDK তৈরি করেছেন, সাথে ` getSongs নামের একটি কোয়েরিও দিয়েছেন:

import { initializeApp } from "firebase-admin/app";
import { getSongs } from "@dataconnect/admin-generated";

const adminApp = initializeApp();

const songs = await getSongs(
  { limit: 4 },
  { impersonate: { unauthenticated: true } }
);

অথবা, একটি সংযোগকারী কনফিগারেশন নির্দিষ্ট করতে:

import { initializeApp } from "firebase-admin/app";
import { getDataConnect } from "firebase-admin/data-connect";
import {
  connectorConfig,
  getSongs,
} from "@dataconnect/admin-generated";

const adminApp = initializeApp();
const adminDc = getDataConnect(connectorConfig);

const songs = await getSongs(
  adminDc,
  { limit: 4 },
  { impersonate: { unauthenticated: true } }
);

অপ্রমাণিত ব্যবহারকারীর ছদ্মবেশ ধারণ করা

অ্যাডমিন এসডিকে-গুলো বিশ্বস্ত পরিবেশ থেকে চালানোর জন্য তৈরি করা হয়েছে, এবং সেই কারণে আপনার ডেটাবেসগুলোতে এগুলোর অবাধ অ্যাক্সেস রয়েছে।

অ্যাডমিন SDK ব্যবহার করে পাবলিক অপারেশন চালানোর সময়, আপনার সম্পূর্ণ অ্যাডমিনিস্ট্রেটর প্রিভিলেজ দিয়ে অপারেশনটি চালানো এড়িয়ে চলা উচিত (লিস্ট প্রিভিলেজের নীতি অনুসরণ করে)। এর পরিবর্তে, আপনার অপারেশনটি হয় একজন ইমপারসোনেটেড ইউজার হিসেবে (পরবর্তী বিভাগ দেখুন), অথবা একজন ইমপারসোনেটেড আনঅথেনটিকেটেড ইউজার হিসেবে চালানো উচিত। আনঅথেনটিকেটেড ইউজাররা শুধুমাত্র PUBLIC হিসেবে চিহ্নিত অপারেশনগুলোই চালাতে পারে।

উপরের উদাহরণে, getSongs কোয়েরিটি একজন প্রমাণীকরণবিহীন ব্যবহারকারী হিসেবে চালানো হয়েছে।

একজন ব্যবহারকারীর ছদ্মবেশ ধারণ করা

আপনি impersonate অপশনে একটি Firebase Authentication টোকেনের অংশবিশেষ বা সম্পূর্ণটি পাস করে নির্দিষ্ট ব্যবহারকারীদের পক্ষ থেকেও অপারেশন সম্পাদন করতে পারেন; ন্যূনতমপক্ষে, আপনাকে sub claim-এ ব্যবহারকারীর ইউজার আইডি অবশ্যই উল্লেখ করতে হবে। (এই মানটি auth.uid সার্ভার ভ্যালুর মতোই, যা আপনি Data Connect GraphQL অপারেশনগুলিতে রেফারেন্স হিসেবে ব্যবহার করতে পারেন।)

যখন আপনি কোনো ব্যবহারকারীর ছদ্মবেশ ধারণ করেন, তখন অপারেশনটি তখনই সফল হবে, যদি আপনার দেওয়া ব্যবহারকারীর ডেটা আপনার GraphQL সংজ্ঞায় নির্দিষ্ট করা প্রমাণীকরণ যাচাইগুলো উত্তীর্ণ হয়।

আপনি যদি কোনো সর্বজনীনভাবে প্রবেশযোগ্য এন্ডপয়েন্ট থেকে তৈরি করা SDK-টি কল করেন, তবে এটি অত্যন্ত গুরুত্বপূর্ণ যে এন্ডপয়েন্টটিতে প্রমাণীকরণের প্রয়োজন হয় এবং কোনো ব্যবহারকারীর ছদ্মবেশ ধারণ করতে ব্যবহার করার আগে আপনি প্রমাণীকরণ টোকেনটির অখণ্ডতা যাচাই করে নেন।

কলযোগ্য Cloud Functions ব্যবহার করার সময়, অথেনটিকেশন টোকেনটি স্বয়ংক্রিয়ভাবে যাচাই করা হয় এবং আপনি এটি নিম্নলিখিত উদাহরণের মতো ব্যবহার করতে পারেন:

import { HttpsError, onCall } from "firebase-functions/https";

export const callableExample = onCall(async (req) => {
    const authClaims = req.auth?.token;
    if (!authClaims) {
        throw new HttpsError("unauthenticated", "Unauthorized");
    }

    const favoriteSongs = await getMyFavoriteSongs(
        undefined,
        { impersonate: { authClaims } }
    );

    // ...
});

অন্যথায়, অথেনটিকেশন টোকেনটি যাচাই এবং ডিকোড করতে Admin SDK এর verifyIdToken মেথডটি ব্যবহার করুন। উদাহরণস্বরূপ, ধরুন আপনার এন্ডপয়েন্টটি একটি সাধারণ HTTP ফাংশন হিসাবে প্রয়োগ করা হয়েছে এবং আপনি প্রচলিত নিয়ম অনুযায়ী authorization হেডার ব্যবহার করে আপনার এন্ডপয়েন্টে Firebase Authentication টোকেনটি পাস করেছেন:

import { getAuth } from "firebase-admin/auth";
import { onRequest } from "firebase-functions/https";

const auth = getAuth();

export const httpExample = onRequest(async (req, res) => {
    const token = req.header("authorization")?.replace(/^bearer\s+/i, "");
    if (!token) {
        res.sendStatus(401);
        return;
    }
    let authClaims;
    try {
        authClaims = await auth.verifyIdToken(token);
    } catch {
        res.sendStatus(401);
        return;
    }

    const favoriteSongs = await getMyFavoriteSongs(
        undefined,
        { impersonate: { authClaims } }
    );

    // ...
});

শুধুমাত্র ডেটা মাইগ্রেশনের মতো প্রকৃত প্রশাসনিক কাজ একটি সুরক্ষিত ও অপ্রকাশ্য পরিবেশ থেকে করার সময়ই আপনার এমন একটি ইউজার আইডি উল্লেখ করা উচিত, যা কোনো যাচাইযোগ্য উৎস থেকে উদ্ভূত হয়নি।

// Never do this if end users can initiate execution of the code!
const favoriteSongs = await getMyFavoriteSongs(
  undefined,
  { impersonate: { authClaims } }
);

অবাধ অ্যাক্সেস সহ চলছে

আপনি যদি এমন কোনো অপারেশন সম্পাদন করেন যার জন্য অ্যাডমিন স্তরের অনুমতির প্রয়োজন, তাহলে কলটি থেকে impersonate প্যারামিটারটি বাদ দিন:

await upsertSong(adminDc, {
  title: songTitle_one,
  instrumentsUsed: [Instrument.VOCAL],
});

এইভাবে কল করা একটি অপারেশনের ডাটাবেসে সম্পূর্ণ অ্যাক্সেস থাকে। আপনার যদি এমন কোয়েরি বা মিউটেশন থাকে যা শুধুমাত্র প্রশাসনিক উদ্দেশ্যে ব্যবহার করার জন্য তৈরি, তবে আপনার সেগুলিকে @auth(level: NO_ACCESS) নির্দেশিকা দিয়ে সংজ্ঞায়িত করা উচিত। এটি নিশ্চিত করে যে শুধুমাত্র অ্যাডমিন-স্তরের কলাররাই এই অপারেশনগুলি সম্পাদন করতে পারবে।

executeGraphql মেথড ব্যবহার করে ডেটা পরিচালনা করুন

যদি আপনার এমন কোনো এককালীন অপারেশন সম্পাদন করার প্রয়োজন হয় যার জন্য আপনি gql মিউটেশন বা কোয়েরি সংজ্ঞায়িত করেননি, তাহলে আপনি executeGraphql মেথড অথবা রিড-অনলি executeGraphqlRead মেথড ব্যবহার করতে পারেন।

অপ্রমাণিত ব্যবহারকারীর ছদ্মবেশ ধারণ করা

অ্যাডমিন SDK ব্যবহার করে পাবলিক অপারেশন চালানোর সময়, আপনার সম্পূর্ণ অ্যাডমিনিস্ট্রেটর প্রিভিলেজ দিয়ে অপারেশনটি চালানো এড়িয়ে চলা উচিত (লিস্ট প্রিভিলেজের নীতি অনুসরণ করে)। এর পরিবর্তে, আপনার অপারেশনটি হয় একজন ইমপারসোনেটেড ইউজার হিসেবে ( পরবর্তী বিভাগ দেখুন), অথবা একজন ইমপারসোনেটেড আনঅথেনটিকেটেড ইউজার হিসেবে চালানো উচিত। আনঅথেনটিকেটেড ইউজাররা শুধুমাত্র PUBLIC হিসেবে চিহ্নিত অপারেশনগুলোই চালাতে পারে।

// 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);

একজন ব্যবহারকারীর ছদ্মবেশ ধারণ করা

এমন কিছু ব্যবহারের ক্ষেত্রও রয়েছে যেখানে আপনি চান আপনার স্ক্রিপ্টগুলো কোনো নির্দিষ্ট ব্যবহারকারীর পক্ষ থেকে, সীমিত পরিচয়পত্রের ভিত্তিতে ব্যবহারকারীর ডেটা পরিবর্তন করুক। এই পদ্ধতিটি ন্যূনতম বিশেষাধিকারের নীতিকে সম্মান করে।

এই ইন্টারফেসটি ব্যবহার করতে, Authentication টোকেন ফরম্যাট অনুসরণ করে এমন একটি কাস্টমাইজড JWT অথ টোকেন থেকে তথ্য সংগ্রহ করুন। কাস্টম টোকেন গাইডটিও দেখুন। 

// 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" } } }

প্রশাসনিক পরিচয়পত্র ব্যবহার করুন

আপনি যদি এমন কোনো অপারেশন সম্পাদন করেন যার জন্য অ্যাডমিন স্তরের অনুমতির প্রয়োজন, তাহলে কলটি থেকে impersonate প্যারামিটারটি বাদ দিন: 

// 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" } } }

এইভাবে কল করা একটি অপারেশনের ডাটাবেসে সম্পূর্ণ অ্যাক্সেস থাকে। আপনার যদি এমন কোয়েরি বা মিউটেশন থাকে যা শুধুমাত্র প্রশাসনিক উদ্দেশ্যে ব্যবহার করার জন্য তৈরি, তবে আপনার সেগুলিকে @auth(level: NO_ACCESS) নির্দেশিকা দিয়ে সংজ্ঞায়িত করা উচিত। এটি নিশ্চিত করে যে শুধুমাত্র অ্যাডমিন-স্তরের কলাররাই এই অপারেশনগুলি সম্পাদন করতে পারবে।

বাল্ক ডেটা অপারেশন সম্পাদন করুন

প্রোডাকশন ডেটাবেসে বাল্ক ডেটা অপারেশনের জন্য ফায়ারবেস Admin 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);

বাল্ক অপারেশনের জন্য পারফরম্যান্স নোট

ব্যাকএন্ডে প্রতিটি অনুরোধের জন্য ক্লাউড এসকিউএল-এ একবার যাওয়া-আসা করতে হয়, তাই আপনি যত বেশি ব্যাচ করবেন, থ্রুপুট তত বেশি হবে।

তবে, ব্যাচ সাইজ যত বড় হবে, তৈরি হওয়া SQL স্টেটমেন্টও তত দীর্ঘ হবে। যখন PostgreSQL-এর SQL স্টেটমেন্টের দৈর্ঘ্যের সীমায় পৌঁছানো যাবে, তখন আপনি একটি ত্রুটির সম্মুখীন হবেন।

বাস্তবে, আপনার কাজের চাপের জন্য উপযুক্ত ব্যাচ সাইজ খুঁজে বের করতে পরীক্ষা-নিরীক্ষা করুন।

এরপর কী?