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

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

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

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

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

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

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

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

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

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

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

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

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