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

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

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

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

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

• Firebase CLI इंस्टॉल करें.

  ध्यान दें: आप Firebase CLI के कमांड Cloud Shell में भी चला सकते हैं. Cloud Shell ब्राउज़र पर आधारित, पहले से पुष्टि किया गया कमांड-लाइन एनवायरमेंट है. इसे Firebase console से ऐक्सेस किया जा सकता है. इसमें Firebase CLI पहले से इंस्टॉल होता है. अगर आपने अपने प्रोजेक्ट की फ़ाइलें Cloud Shell एनवायरमेंट में जोड़ी हैं, तो यह जल्दी शुरू करने का एक आसान विकल्प है.

• जनरेट किए गए एडमिन एसडीके को कॉल करने के लिए, Node.js के लिए एडमिन एसडीके को डिपेंडेंसी के तौर पर शामिल करें.

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

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

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

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

जनरेट किए गए एडमिन एसडीके में, इंटरफ़ेस और फ़ंक्शन शामिल होते हैं. ये इंटरफ़ेस और फ़ंक्शन, आपकी 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 } }
);

ध्यान दें: जनरेट किए गए JavaScript क्लाइंट एसडीके, इंटरफ़ेस और कार्रवाइयों के लिए वही नाम इस्तेमाल करते हैं जो Node.js के एडमिन एसडीके इस्तेमाल करते हैं. अपने प्लैटफ़ॉर्म के लिए सही लाइब्रेरी इंपोर्ट करना न भूलें. अगर आपको एक ही फ़ाइल में दोनों लाइब्रेरी का इस्तेमाल करना है, तो किसी एक या दोनों लाइब्रेरी के लिए इंपोर्ट एलियास या नेमस्पेस इंपोर्ट का इस्तेमाल करें.

import { listMovies as adminListMovies } from '@dataconnect/admin-generated';
Or:
import * as Admin from '@dataconnect/admin-generated';

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

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

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

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

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

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

किसी उपयोगकर्ता के तौर पर साइन इन करने पर, कार्रवाई सिर्फ़ तब पूरी होगी, जब आपके दिए गए उपयोगकर्ता डेटा की पुष्टि, GraphQL की परिभाषा में तय की गई पुष्टि की जांच के मुताबिक हो.

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

कॉल किए जा सकने वाले 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 } }
);

बिना पाबंदी वाले ऐक्सेस के साथ कार्रवाई करना

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

await upsertSong(adminDc, {
  title: songTitle_one,
  instrumentsUsed: [Instrument.VOCAL],
});

इस तरह से कॉल की गई कार्रवाई के पास, डेटाबेस का पूरा ऐक्सेस होता है. अगर आपके पास ऐसी क्वेरी या म्यूटेशन हैं जिनका इस्तेमाल सिर्फ़ एडमिन के मकसद से किया जाना है, तो उन्हें @auth(level: NO_ACCESS) डायरेक्टिव के साथ तय करें. ऐसा करने से, सिर्फ़ एडमिन-लेवल के कॉलर ही इन कार्रवाइयों को कर पाएंगे.