डेटा कनेक्ट के साथ एडमिन SDK टूल का इस्तेमाल करना

Firebase Admin SDK, सर्वर लाइब्रेरी का एक सेट है. इसकी मदद से, खास अधिकारों वाले एनवायरमेंट से Firebase के साथ इंटरैक्ट किया जा सकता है. जैसे, Firebase Data Connect सेवा पर क्वेरी और म्यूटेशन करना, बड़े पैमाने पर डेटा मैनेज करना, और खास अधिकारों और नकली क्रेडेंशियल के साथ अन्य कार्रवाइयां करना.

Admin SDK आपको एक एपीआई उपलब्ध कराता है. इसकी मदद से, रीड/राइट और रीड-ओनली, दोनों मोड में कार्रवाइयां की जा सकती हैं. सिर्फ़ पढ़ने की अनुमति वाली कार्रवाइयों से, आपको एडमिन फ़ंक्शन लागू करने में आसानी होती है. इससे आपके डेटाबेस में मौजूद डेटा में बदलाव नहीं किया जा सकता.

Admin SDK सेटअप करना

अपने सर्वर पर Firebase Data Connect का इस्तेमाल शुरू करने के लिए, आपको सबसे पहले Node.js के लिए Admin SDK को इंस्टॉल और सेट अप करना होगा.

अपनी स्क्रिप्ट में 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 का इस्तेमाल किया जा सकता है. हालांकि, इसके लिए इन बातों का ध्यान रखना ज़रूरी है.

एसडीके और @auth(level: NO_ACCESS) ऑपरेशन डायरेक्टिव को समझना

Admin SDK के पास खास अधिकार होते हैं. इसलिए, यह आपकी किसी भी क्वेरी और म्यूटेशन को लागू कर सकता है. भले ही, @auth डायरेक्टिव का इस्तेमाल करके ऐक्सेस लेवल सेट किए गए हों. इसमें NO_ACCESS लेवल भी शामिल है.

अगर क्लाइंट के ऑपरेशनों के साथ-साथ, एडमिन से जुड़ी क्वेरी और म्यूटेशन को .gql सोर्स फ़ाइलों में व्यवस्थित किया जाता है, ताकि उन्हें एडमिन स्क्रिप्ट में इंपोर्ट किया जा सके, तो Firebase का सुझाव है कि एडमिन से जुड़े ऑपरेशनों को बिना किसी अनुमति के ऐक्सेस लेवल के तौर पर मार्क करें. इसके अलावा, उन्हें NO_ACCESS के तौर पर सेट किया जा सकता है. इन दोनों ही तरीकों से, इस तरह के ऑपरेशन को क्लाइंट या अन्य गैर-ज़रूरी कॉन्टेक्स्ट से लागू होने से रोका जाता है.

Data Connect एम्युलेटर के साथ एसडीके टूल का इस्तेमाल करना

प्रोटोटाइप और टेस्ट एनवायरमेंट में, लोकल डेटा पर डेटा सीडिंग और अन्य कार्रवाइयां करना फ़ायदेमंद हो सकता है. Admin SDK की मदद से, अपने वर्कफ़्लो को आसान बनाया जा सकता है. ऐसा इसलिए, क्योंकि यह लोकल फ़्लो के लिए पुष्टि करने और अनुमति देने की प्रोसेस को अनदेखा कर सकता है. (आपके पास, उपयोगकर्ता की पहचान चुराकर किए जाने वाले ऑपरेशनों के लिए, पुष्टि करने और अनुमति देने से जुड़े कॉन्फ़िगरेशन का पालन करने के लिए, साफ़ तौर पर ऑप्ट इन करने का विकल्प भी होता है.)

Firebase Admin SDK टूल, Data Connect एनवायरमेंट वैरिएबल सेट होने पर, Data Connect एम्युलेटर से अपने-आप कनेक्ट हो जाता है:DATA_CONNECT_EMULATOR_HOST

export DATA_CONNECT_EMULATOR_HOST="127.0.0.1:9399"

ज़्यादा जानकारी के लिए, ये देखें:

एडमिन से जुड़ी कार्रवाइयां करना

Admin SDK, आपके अहम डेटा पर खास कार्रवाइयां करने के लिए उपलब्ध कराया जाता है.

एडमिन एसडीके, तीन तरह के एपीआई उपलब्ध कराता है:

  • जनरेट किए गए एडमिन SDK टूल. ये टाइप-सेफ़ SDK टूल होते हैं. इन्हें आपकी gqlडेफ़िनिशन से जनरेट किया जाता है. इन्हें उसी तरह जनरेट किया जाता है जिस तरह क्लाइंट SDK टूल जनरेट किए जाते हैं.
  • यह GraphQL ऑपरेशन चलाने के लिए एक सामान्य इंटरफ़ेस है. इसमें आपका कोड, क्वेरी और म्यूटेशन लागू करता है और उन्हें read-write executeGraphql तरीके या read-only executeGraphqlRead तरीके से पास करता है.
  • बल्क डेटा ऑपरेशन के लिए खास इंटरफ़ेस. यह सामान्य executeGraphql तरीकों के बजाय, म्यूटेशन ऑपरेशन के लिए खास तरीके दिखाता है: insert, insertMany, upsert, और upsertMany.

जनरेट किए गए एसडीके की मदद से डेटा मैनेज करना

क्लाइंट एसडीके जनरेट करने के तरीके से ही, gql की परिभाषाओं से एडमिन एसडीके जनरेट किए जाते हैं.

जनरेट किए गए एडमिन एसडीके में ऐसे इंटरफ़ेस और फ़ंक्शन होते हैं जो आपकी gql परिभाषाओं से मेल खाते हैं. इनका इस्तेमाल करके, अपने डेटाबेस पर कार्रवाइयां की जा सकती हैं. उदाहरण के लिए, मान लें कि आपने गानों के डेटाबेस के लिए एक एसडीके जनरेट किया है. साथ ही, आपने एक क्वेरी भी जनरेट की है, 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 } }
);

बिना पुष्टि किए गए उपयोगकर्ता के तौर पर काम करना

Admin SDK को भरोसेमंद एनवायरमेंट से चलाने के लिए डिज़ाइन किया गया है. इसलिए, इनके पास आपके डेटाबेस का पूरा ऐक्सेस होता है.

एडमिन SDK की मदद से सार्वजनिक कार्रवाइयां करते समय, आपको एडमिन के सभी अधिकारों के साथ कार्रवाई नहीं करनी चाहिए. इसके लिए, कम से कम ज़रूरी अधिकारों के सिद्धांत का पालन करें. इसके बजाय, आपको इस ऑपरेशन को किसी ऐसे उपयोगकर्ता के तौर पर चलाना चाहिए जिसकी पहचान की पुष्टि नहीं हुई है. इसके अलावा, किसी ऐसे उपयोगकर्ता के तौर पर भी चलाया जा सकता है जिसकी पहचान की पुष्टि हो चुकी है. इसके बारे में अगले सेक्शन में बताया गया है. पुष्टि न किए गए उपयोगकर्ता, सिर्फ़ PUBLIC के तौर पर मार्क किए गए ऑपरेशन चला सकते हैं.

ऊपर दिए गए उदाहरण में, getSongs क्वेरी को बिना पुष्टि किए उपयोगकर्ता के तौर पर एक्ज़ीक्यूट किया गया है.

किसी उपयोगकर्ता के नाम पर काम करना

Firebase Authentication विकल्प में Firebase Authentication टोकन का कुछ हिस्सा या पूरा टोकन पास करके, चुनिंदा उपयोगकर्ताओं की ओर से भी कार्रवाइयां की जा सकती हैं. कम से कम, आपको सब-क्लेम में उपयोगकर्ता का यूज़र आईडी देना होगा.impersonate (यह वही वैल्यू है जो Data Connect GraphQL ऑपरेशंस में, auth.uid सर्वर वैल्यू के तौर पर इस्तेमाल की जा सकती है.)

किसी उपयोगकर्ता के तौर पर काम करने पर, ऑपरेशन सिर्फ़ तब पूरा होगा, जब आपके दिए गए उपयोगकर्ता डेटा की पुष्टि हो जाए. इसके लिए, 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 तरीके का इस्तेमाल करें. उदाहरण के लिए, मान लें कि आपका एंडपॉइंट, सामान्य एचटीटीपी फ़ंक्शन के तौर पर लागू किया गया है और आपने Firebase Authentication हेडर का इस्तेमाल करके, अपने एंडपॉइंट को Firebase Authentication टोकन पास किया है. यह एक स्टैंडर्ड तरीका है:authorization

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

किसी उपयोगकर्ता के नाम पर काम करना

ऐसे भी इस्तेमाल के उदाहरण हैं जहां आपको किसी खास उपयोगकर्ता की ओर से, सीमित क्रेडेंशियल के आधार पर उपयोगकर्ता के डेटा में बदलाव करने के लिए अपनी स्क्रिप्ट का इस्तेमाल करना होता है. इस तरीके में, कम से कम अधिकारों के सिद्धांत का पालन किया जाता है.

इस इंटरफ़ेस का इस्तेमाल करने के लिए, ज़रूरत के मुताबिक बनाए गए 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" } } }

एडमिन क्रेडेंशियल का इस्तेमाल करना

अगर आपको ऐसा ऑपरेशन करना है जिसके लिए एडमिन लेवल की अनुमतियों की ज़रूरत होती है, तो कॉल से 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) डायरेक्टिव के साथ तय करना होगा. ऐसा करने से, यह पक्का किया जा सकता है कि सिर्फ़ एडमिन-लेवल के कॉलर ही इन कार्रवाइयों को पूरा कर सकें.

एक साथ कई डेटा ऑपरेशन करना

Firebase का सुझाव है कि प्रोडक्शन डेटाबेस पर डेटा से जुड़ी कई कार्रवाइयां करने के लिए, 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);

एक साथ कई कार्रवाइयां करने के लिए परफ़ॉर्मेंस से जुड़ी ज़रूरी बातें

बैकएंड को किए गए हर अनुरोध के लिए, Cloud SQL को एक राउंड ट्रिप करनी होगी. इसलिए, बैच में किए गए अनुरोधों की संख्या जितनी ज़्यादा होगी, थ्रूपुट उतना ही ज़्यादा होगा.

हालांकि, बैच का साइज़ जितना बड़ा होगा, जनरेट किया गया SQL स्टेटमेंट उतना ही लंबा होगा. जब PostgreSQL SQL स्टेटमेंट की लंबाई की सीमा पूरी हो जाएगी, तब आपको एक गड़बड़ी दिखेगी.

अपने वर्कलोड के लिए सही बैच साइज़ का पता लगाने के लिए, एक्सपेरिमेंट करें.

आगे क्या करना है?