जनरेट किए गए एडमिन एसडीके का इस्तेमाल करना

Firebase SQL Connect admin SDK टूल की मदद से, Cloud Functions, कस्टम बैकएंड या अपने वर्कस्टेशन जैसे भरोसेमंद एनवायरमेंट से क्वेरी और म्यूटेशन किए जा सकते हैं. जिस तरह क्लाइंट ऐप्लिकेशन के लिए SDK टूल जनरेट किए जाते हैं उसी तरह, स्कीमा, क्वेरी, और म्यूटेशन डिज़ाइन करते समय, कस्टम एडमिन SDK टूल जनरेट किया जा सकता है. इन्हें SQL Connect सेवा में डिप्लॉय किया जाता है. इसके बाद, इस एसडीके टूल के तरीकों को अपने बैकएंड लॉजिक या एडमिन स्क्रिप्ट में इंटिग्रेट करें.

जैसा कि हमने यहां बताया है, यह ध्यान रखना ज़रूरी है कि अनुरोध के समय, क्लाइंट SQL Connect क्वेरी और म्यूटेशन सबमिट नहीं करते हैं. इसके बजाय, डिप्लॉय किए जाने पर SQL Connect कार्रवाइयों को सर्वर पर सेव किया जाता है. जैसे, Cloud Functions. इसका मतलब है कि जब भी अपनी क्वेरी और म्यूटेशन में बदलाव किए जाते हैं, तब आपको एडमिन SDK टूल को फिर से जनरेट करना होगा. साथ ही, उन सभी सेवाओं को फिर से डिप्लॉय करना होगा जो इन पर निर्भर करती हैं.

शुरू करने से पहले

• SQL Connect स्कीमा, क्वेरी, और म्यूटेशन डिज़ाइन करने के बारे में जानें. सामान्य वर्कफ़्लो में, आपको इन्हें अपने ऐप्लिकेशन कोड के साथ-साथ डेवलप करना होगा. इसमें एडमिन एसडीके का इस्तेमाल करने वाली कोई भी सेवा शामिल है.

• Firebase सीएलआई इंस्टॉल करें.

• जहां भी आपको जनरेट किए गए Admin SDK टूल को कॉल करना है वहां डिपेंडेंसी के तौर पर, Admin SDK for Node.js को शामिल करें.

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

SQL Connect स्कीमा, क्वेरी, और म्यूटेशन बनाने के बाद, उनसे जुड़ा एडमिन SDK जनरेट किया जा सकता है:

1. कोई connector.yaml फ़ाइल खोलें या नई फ़ाइल बनाएं. इसके बाद, adminNodeSdk डेफ़िनिशन जोड़ें:

   connectorId: default
   generate:
     adminNodeSdk:
       outputDir: ../../dataconnect-generated/admin-generated
       package: "@dataconnect/admin-generated"
       packageJsonDir: ../..
   

   connector.yaml फ़ाइल आम तौर पर उसी डायरेक्ट्री में मिलती है जिसमें GraphQL (.gql) फ़ाइलें होती हैं. इन फ़ाइलों में आपकी क्वेरी और म्यूटेशन की परिभाषाएं होती हैं. अगर आपने पहले ही क्लाइंट एसडीके जनरेट कर लिए हैं, तो यह फ़ाइल पहले ही बन गई होगी.

2. एसडीके जनरेट करें.

   अगर आपने SQL Connect VS Code एक्सटेंशन इंस्टॉल किया है, तो यह जनरेट किए गए एसडीके को हमेशा अप-टू-डेट रखेगा.

   इसके अलावा, Firebase CLI का इस्तेमाल करें:

   firebase dataconnect:sdk:generate

   इसके अलावा, gql फ़ाइलों को अपडेट करने पर, एसडीके अपने-आप फिर से जनरेट हो जाएं, इसके लिए:

   firebase dataconnect:sdk:generate --watch

एडमिन SDK टूल से कार्रवाइयां करना

जनरेट किए गए एडमिन एसडीके में ऐसे इंटरफ़ेस और फ़ंक्शन होते हैं जो आपकी 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 टूल को भरोसेमंद एनवायरमेंट से चलाने के लिए डिज़ाइन किया गया है. इसलिए, इनके पास आपके डेटाबेस का पूरा ऐक्सेस होता है.

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