Firebase Admin SDK सर्वर लाइब्रेरी का एक सेट है. इसकी मदद से, खास अधिकारों वाले एनवायरमेंट से Firebase के साथ इंटरैक्ट किया जा सकता है. साथ ही, कई कार्रवाइयां की जा सकती हैं. जैसे, बल्क डेटा मैनेजमेंट के लिए, Firebase SQL Connect सेवा पर क्वेरी और बदलाव करना. इसके अलावा, खास अधिकारों और उपयोगकर्ता के तौर पर साइन इन करने की सुविधा वाले क्रेडेंशियल का इस्तेमाल करके अन्य कार्रवाइयां करना.
Admin SDK आपको रीड/राइट और रीड-ओनली, दोनों मोड में कार्रवाइयां करने के लिए एक एपीआई उपलब्ध कराता है. रीड-ओनली मोड में, एडमिन से जुड़ी कार्रवाइयां करने पर, आपको इस बात की चिंता करने की ज़रूरत नहीं होती कि आपके डेटाबेस में मौजूद डेटा में बदलाव हो सकता है.
Admin SDK सेटअप करना
अपने सर्वर पर, Firebase SQL Connect के साथ का इस्तेमाल शुरू करने के लिए, आपको सबसे पहले इंस्टॉल और सेट अप करना होगा Admin SDK के लिए Node.js.
अपने स्क्रिप्ट में 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 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"
ज़्यादा जानकारी के लिए, ये देखें:
- लोकल डेवलपमेंट में डेटा सीडिंग के लिए गाइड
- SQL Connect एम्युलेटर का दस्तावेज़.
एडमिन से जुड़ी कार्रवाइयां करना
Admin SDK आपके अहम डेटा पर खास अधिकारों वाली कार्रवाइयां करने के लिए उपलब्ध कराया जाता है.
Admin SDK, एपीआई के तीन सेट उपलब्ध कराता है:
- जनरेट किए गए एडमिन SDK. ये टाइप-सेफ़ SDK हैं, जो आपके
gqlडेफ़िनिशन से जनरेट किए जाते हैं. इन्हें उसी तरीके से जनरेट किया जाता है जिस तरह क्लाइंट SDK जनरेट किए जाते हैं. - किसी भी GraphQL कार्रवाई को करने के लिए एक सामान्य इंटरफ़ेस. इसमें आपका
कोड, क्वेरी और बदलाव लागू करता है. साथ ही, उन्हें रीड-राइट
executeGraphqlतरीके या रीड-ओनलीexecuteGraphqlReadतरीके से पास करता है. - बल्क डेटा की कार्रवाइयों के लिए एक खास इंटरफ़ेस. इसमें
सामान्य
executeGraphqlतरीकों के बजाय, बदलाव की कार्रवाइयों के लिए खास तरीके उपलब्ध होते हैं:insert,insertMany,upsert, औरupsertMany.
जनरेट किए गए 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 हेडर का इस्तेमाल करके, अपने एंडपॉइंट पर पास किया है, जैसा कि आम तौर पर किया जाता है:
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 पर एक राउंड ट्रिप होगी. इसलिए, बैचिंग करने पर थ्रूपुट ज़्यादा होगा.
हालांकि, बैच का साइज़ जितना बड़ा होगा, जनरेट किया गया SQL स्टेटमेंट उतना ही लंबा होगा. PostgreSQL SQL स्टेटमेंट की लंबाई की सीमा पूरी होने पर, आपको गड़बड़ी दिखेगी.
असल में, अपने वर्कलोड के लिए बैच का सही साइज़ ढूंढने के लिए, एक्सपेरिमेंट करें.
आगे क्या करना है?
- का इस्तेमाल करके, अपने डेटाबेस में डेटा सीड करने के बारे में जानेंAdmin SDK
- के लिए Admin SDK की समीक्षा करें.
- स्कीमा और कनेक्टर मैनेज करने, सेवाओं और डेटाबेस मैनेज करने जैसे प्रोजेक्ट मैनेजमेंट से जुड़ी अन्य कार्रवाइयों के लिए, Firebase CLI और Google Cloud console का इस्तेमाल करें.