SQL Connect के साथ Admin SDK का इस्तेमाल करना

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

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

Admin SDK सेटअप करना

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

अपने स्क्रिप्ट में Admin SDK सेटअप करना

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

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

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

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

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

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

`DATA_CONNECT_EMULATOR_HOST` एनवायरमेंट वैरिएबल सेट होने पर, Firebase Admin SDK अपने-आप `SQL 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 को भरोसेमंद एनवायरमेंट से चलाने के लिए डिज़ाइन किया गया है. इसलिए, इनके पास आपके डेटाबेस का बिना पाबंदी वाला ऐक्सेस होता है.

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

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

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

`impersonate` विकल्प में `Firebase Authentication` टोकन का कुछ हिस्सा या पूरा टोकन पास करके, खास उपयोगकर्ताओं की ओर से भी कार्रवाइयां की जा सकती हैं. कम से कम, आपको सब दावे में उपयोगकर्ता का यूज़र आईडी तय करना होगा. (यह वही वैल्यू है जिसे auth.uid सर्वर वैल्यू आप SQL 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's verifyIdToken तरीके का इस्तेमाल करें. उदाहरण के लिए, मान लें कि आपका एंडपॉइंट, सामान्य एचटीटीपी फ़ंक्शन के तौर पर लागू किया गया है. साथ ही, आपने Firebase Authentication टोकन को authorization हेडर का इस्तेमाल करके अपने एंडपॉpoint पर पास किया है, जैसा कि आम तौर पर किया जाता है:

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 तरीके का इस्तेमाल किया जा सकता है.

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

पब्लिक कार्रवाइयों को Admin 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 SQL 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 एसक्यूएल स्टेटमेंट की लंबाई की सीमा पूरी होने पर, आपको गड़बड़ी दिखेगी.

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

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