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 का इस्तेमाल, SQL Connect कार्रवाइयां करने के लिए किया जाता है. इसके लिए, यहां दी गई बातों का ध्यान रखना ज़रूरी है.
एसडीके और @auth(level: NO_ACCESS) ऑपरेशन डायरेक्टिव को समझना
Admin SDK के पास खास अनुमतियां होती हैं. इसलिए, यह आपकी किसी भी क्वेरी और म्यूटेशन को लागू कर सकता है. भले ही, @auth डायरेक्टिव का इस्तेमाल करके ऐक्सेस लेवल सेट किए गए हों. इनमें NO_ACCESS लेवल भी शामिल है.
अगर क्लाइंट से जुड़े कामों के साथ-साथ, एडमिन से जुड़ी क्वेरी और म्यूटेशन को .gql सोर्स फ़ाइलों में व्यवस्थित किया जाता है, ताकि उन्हें एडमिन स्क्रिप्ट में इंपोर्ट किया जा सके, तो Firebase का सुझाव है कि एडमिन से जुड़े कामों को बिना किसी अनुमति के ऐक्सेस लेवल के तौर पर मार्क करें. इसके अलावा, उन्हें ज़्यादा साफ़ तौर पर मार्क करने के लिए, NO_ACCESS के तौर पर सेट करें. दोनों ही मामलों में, क्लाइंट या अन्य गैर-विशेषाधिकार वाले कॉन्टेक्स्ट से इस तरह की कार्रवाइयों को लागू होने से रोका जाता है.
SQL Connect एम्युलेटर के साथ SDK टूल का इस्तेमाल करना
प्रोटोटाइप और टेस्ट एनवायरमेंट में, स्थानीय डेटा पर डेटा सीडिंग और अन्य कार्रवाइयां करना मददगार हो सकता है. 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, एपीआई के तीन सेट उपलब्ध कराता है:
- जनरेट किए गए Admin SDK टूल, टाइप-सेफ़ SDK टूल होते हैं. इन्हें आपकी
gqlपरिभाषाओं से उसी तरह जनरेट किया जाता है जिस तरह क्लाइंट SDK टूल जनरेट किए जाते हैं. - यह आर्बिट्रेरी GraphQL ऑपरेशन चलाने के लिए एक सामान्य इंटरफ़ेस है. इसमें आपका कोड, क्वेरी और म्यूटेशन लागू करता है और उन्हें रीड-राइट
executeGraphqlतरीके या रीड-ओनलीexecuteGraphqlReadतरीके से पास करता है. - यह बल्क डेटा ऑपरेशन के लिए एक खास इंटरफ़ेस है. यह सामान्य
executeGraphqlतरीकों के बजाय, म्यूटेशन ऑपरेशन के लिए खास तरीके दिखाता है:insert,insertMany,upsert, औरupsertMany.
जनरेट किए गए एसडीके की मदद से डेटा मैनेज करना
gql परिभाषाओं से एडमिन SDK टूल जनरेट किए जा सकते हैं. यह क्लाइंट SDK टूल जनरेट करने जैसा ही है.
जनरेट किए गए Admin 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 परिभाषा में बताई गई जांचों के आधार पर की जाती है.
अगर जनरेट किए गए एसडीके को सार्वजनिक तौर पर ऐक्सेस किए जा सकने वाले एंडपॉइंट से कॉल किया जा रहा है, तो यह ज़रूरी है कि एंडपॉइंट के लिए पुष्टि करना ज़रूरी हो. साथ ही, किसी उपयोगकर्ता के तौर पर काम करने के लिए, पुष्टि करने वाले टोकन का इस्तेमाल करने से पहले, उसकी इंटिग्रिटी की पुष्टि करना ज़रूरी है.
कॉल किए जा सकने वाले 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) डायरेक्टिव के साथ तय करना चाहिए. ऐसा करने से, यह पक्का होता है कि सिर्फ़ एडमिन लेवल के कॉलर ही इन कार्रवाइयों को लागू कर सकते हैं.
executeGraphql तरीकों से डेटा मैनेज करना
अगर आपको ऐसे वन-ऑफ़ ऑपरेशन चलाने हैं जिनके लिए आपने gql
म्यूटेशन या क्वेरी तय नहीं की हैं, तो executeGraphql तरीके या रीड-ओनली
executeGraphqlRead तरीके का इस्तेमाल किया जा सकता है.
executeGraphql का इस्तेमाल करके, कस्टम नेस्टेड रिलेशनल ऑपरेशन (वन-टू-मेनी और वन-टू-वन) करना
किसी खास एनवायरमेंट में Admin SDK से ऑपरेशन को कॉल करते समय, आपको स्टैंडर्ड फ़्लैट (नॉन-नेस्टेड) इंसर्शन (जैसे, अलग-अलग फ़िल्म या कलाकार के रिकॉर्ड डालना) के लिए, अपने वैरिएबल पर @allow डायरेक्टिव की जानकारी देने की ज़रूरत नहीं होती.
हालांकि, नेस्ट किए गए रिलेशनल इंसर्ट (जैसे, किसी फ़िल्म को उसकी शुरुआती समीक्षाओं के साथ या किसी उपयोगकर्ता और उसकी प्रोफ़ाइल को इंसर्ट करना) के लिए, आपको अब भी अपने वैरिएबल की डेफ़िनिशन पर @allow डायरेक्टिव का एलान करना होगा. इससे, कंपाइल किए गए वैरिएबल स्कीमा के अंदर नेस्ट किए गए रिलेशनल फ़ील्ड को स्टैटिक तौर पर अनुमति दी जा सकेगी.
// Custom GraphQL mutation with nested relational insert (one-to-many)
const customMutation = `
mutation CustomBatchInsert(
$data: [Movie_Data!]!
@allow(fields: "title genre reviews_on_movie { rating reviewText }")
) {
movie_insertMany(data: $data)
}
`;
const variables = {
data: [
{
title: "Interstellar",
genre: "Sci-Fi",
reviews_on_movie: [
{
rating: 5,
reviewText: "Visually stunning and emotionally powerful.",
user: { id: "user-789" }
}
]
}
]
};
const response = await dataConnect.executeGraphql(customMutation, { variables });
// Custom GraphQL mutation with a one-to-one nested relational insert
const customMutationOneToOne = `
mutation CustomBatchInsertOneToOne(
$data: [User_Data!]!
@allow(fields: "name profile_on_user { bio }")
) {
user_insertMany(data: $data)
}
`;
const variablesOneToOne = {
data: [
{
name: "Alice",
profile_on_user: {
bio: "Avid moviegoer and critic."
}
}
]
};
const responseOneToOne = await dataConnect.executeGraphql(customMutationOneToOne, { variables: variablesOneToOne });
किसी ऐसे उपयोगकर्ता की पहचान चुराना जिसकी पुष्टि नहीं हुई है
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" } } }
एडमिन क्रेडेंशियल इस्तेमाल करना
अगर आपको कोई ऐसी कार्रवाई करनी है जिसके लिए एडमिन लेवल की अनुमतियों की ज़रूरत है, तो कॉल से impersonate पैरामीटर को हटा दें:
// 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 का इस्तेमाल करें.
यह एसडीके, बल्क डेटा के साथ काम करने के लिए ये तरीके उपलब्ध कराता है. दिए गए आर्ग्युमेंट से, हर तरीका एक 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);
नेस्टेड रिलेशनल ऑपरेशन (वन-टू-मेनी और वन-टू-वन)
Admin SDK, एक साथ कई कार्रवाइयों में रिलेशनल डेटा के साथ काम करता है. कस्टम म्यूटेशन की तरह ही, वन-टू-मेनी रिलेशनशिप के लिए ऑब्जेक्ट के कलेक्शन का इस्तेमाल करें. साथ ही, वन-टू-वन रिलेशनशिप के लिए सिंगल ऑब्जेक्ट का इस्तेमाल करें:
// Example of inserting a movie with nested reviews (one-to-many)
const moviesData = [
{
title: "Interstellar",
genre: "Sci-Fi",
reviews_on_movie: [
{
rating: 5,
reviewText: "Visually stunning and emotionally powerful.",
user: { id: "user-789" }
}
]
}
];
// Atomically insert movies and their reviews in a single database round-trip.
const response = await dc.insertMany("movie", moviesData);
// Example of inserting a user with a nested profile (one-to-one)
const usersData = [
{
name: "Alice",
profile_on_user: {
bio: "Avid moviegoer and critic."
}
}
];
// Atomically insert users and their profiles.
const userResponse = await dc.insertMany("user", usersData);
एक साथ कई कार्रवाइयां करने के लिए परफ़ॉर्मेंस नोट
बैकएंड को किए गए हर अनुरोध के लिए, Cloud SQL को एक बार डेटा भेजा जाएगा और वहां से एक बार डेटा वापस आएगा. इसलिए, जितने ज़्यादा बैच होंगे, थ्रूपुट उतना ही ज़्यादा होगा.
हालांकि, बैच का साइज़ जितना बड़ा होगा, जनरेट किया गया एसक्यूएल स्टेटमेंट उतना ही लंबा होगा. PostgreSQL के एसक्यूएल स्टेटमेंट की लंबाई की सीमा पूरी होने पर, आपको गड़बड़ी का मैसेज दिखेगा.
अपने वर्कलोड के लिए सही बैच साइज़ ढूंढने के लिए, अलग-अलग बैच साइज़ आज़माएं.
आगे क्या करना है?
- Admin SDK का इस्तेमाल करके, अपने डेटाबेस में डेटा सीड करने के बारे में जानें
- Admin SDK के लिए एपीआई की समीक्षा करें.
- प्रोजेक्ट मैनेजमेंट से जुड़े अन्य कामों के लिए, Firebase सीएलआई और Google Cloud कंसोल का इस्तेमाल करें. जैसे, स्कीमा और कनेक्टर मैनेज करना और सेवाएं और डेटाबेस मैनेज करना.