डेटा कनेक्ट के साथ एडमिन 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 के साथ इस्तेमाल करने के लिए क्वेरी और म्यूटेशन डिज़ाइन करना Admin SDK

Admin SDK Data Connect की कार्रवाइयां करने के लिए काम का है. हालांकि, इसके लिए यहां बताई गई बातों का ध्यान रखना होगा.Data Connect

SDK टूल और @auth(level: NO_ACCESS) कार्रवाई के निर्देश को समझना

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

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

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

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

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

export DATA_CONNECT_EMULATOR_HOST="127.0.0.1:9399"

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

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

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

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

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

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

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

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

उपयोगकर्ता के तौर पर साइन इन करना

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

उपयोगकर्ता के तौर पर साइन इन करने पर, कार्रवाई सिर्फ़ तब सफल होगी, जब आपके दिए गए उपयोगकर्ता डेटा की पुष्टि, 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's verifyIdToken तरीके का इस्तेमाल करें. उदाहरण के लिए, मान लें कि आपका एंडपॉइंट, सामान्य एचटीटीपी फ़ंक्शन के तौर पर लागू किया गया है. साथ ही, आपने 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 } }
);

अनलिमिटेड ऐक्सेस के साथ काम करना

अगर ऐसी कार्रवाई की जा रही है जिसके लिए एडमिन लेवल की अनुमतियां ज़रूरी हैं, तो कॉल में उपयोगकर्ता के तौर पर साइन इन करने का पैरामीटर शामिल न करें:

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

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

अगर ऐसी कार्रवाई की जा रही है जिसके लिए एडमिन लेवल की अनुमतियां ज़रूरी हैं, तो कॉल में उपयोगकर्ता के तौर पर साइन इन करने का पैरामीटर शामिल न करें:

// 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 का इस्तेमाल करें.

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 पर एक राउंड ट्रिप होगी. इसलिए, बैचिंग करने पर थ्रूपुट ज़्यादा होगा.

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

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

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