שימוש ב-Admin SDK עם Data Connect

‏Firebase Admin SDK היא קבוצה של ספריות שרת שמאפשרות לבצע פעולות ב-Firebase מסביבות בעלות הרשאות, כמו ביצוע שאילתות ומוטציות בשירות Firebase Data Connect לניהול נתונים בכמות גדולה ופעולות אחרות עם הרשאות מוגברות ופרטי כניסה שמזויפים.

Admin SDK מספק ממשק API לקריאה להפעלת פעולות גם במצב קריאה/כתיבה וגם במצב קריאה בלבד. בעזרת הפעולות לקריאה בלבד, תוכלו ליישם פונקציות ניהוליות שלא יכולות לשנות נתונים במסדי הנתונים שלכם.

הגדרת Admin SDK

כדי להתחיל להשתמש ב-Firebase Data Connect בשרת, קודם צריך להתקין ולהגדיר את Admin SDK ל-Node.js.

איך מאתחלים את Admin SDK בסקריפטים

כדי לאתחל את ה-SDK, מייבאים את התוספים Data 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 שימושי לבדיקת פעולות Data Connect, בהתאם לשיקולים הבאים.

הסבר על ה-SDK וההוראות הפעולה של @auth(level: NO_ACCESS)

מכיוון ש-Admin SDK פועל עם הרשאות, הוא יכול להריץ את כל השאילתות והמוטציות שלכם ללא קשר לרמות הגישה שהוגדרו באמצעות הוראות @auth, כולל רמה NO_ACCESS.

אם אתם מארגנים את השאילתות והמוטציות הניהוליות בקובצי המקור .gql לצד פעולות הלקוח, כדי לייבא אותן לסקריפטים ניהוליים, מומלץ ב-Firebase לסמן את הפעולות הניהוליות ללא רמת גישה להרשאה, או להגדיר אותן כ-NO_ACCESS באופן מפורש יותר. כך אפשר למנוע ביצוע פעולות כאלה מלקוחות או בהקשרים אחרים ללא הרשאות.

שימוש ב-SDK עם אמולטור Data Connect

בסביבות של אב טיפוס ובדיקות, כדאי לבצע הטמעת נתונים ופעולות אחרות על נתונים מקומיים. בעזרת Admin SDK תוכלו לפשט את תהליכי העבודה, כי הוא מתעלם מאימות ומהרשאה בתהליכים מקומיים.

ערכות ה-SDK של Firebase לאדמינים מתחברות באופן אוטומטי למהדר Data Connect כשמשנים את משתנה הסביבה DATA_CONNECT_EMULATOR_HOST:

export DATA_CONNECT_EMULATOR_HOST="127.0.0.1:9399"

מידע נוסף זמין בדפים הבאים:

הטמעת תרחישים נפוצים לדוגמה

Admin SDK משמש לפעולות בעלות הרשאות על הנתונים הקריטיים שלכם.

ב-Admin SDK יש שני ממשקים:

  • ממשק כללי לרוב הפעולות של קריאה וכתיבה או קריאה בלבד, שבו הקוד מטמיע שאילתות ומוטציות ומעביר אותן לשיטה executeGraphql לקריאה וכתיבה או לשיטה executeGraphqlRead לקריאה בלבד.
  • ממשק מיוחד לפעולות על נתונים בכמות גדולה, שמציג שיטות ייעודיות לפעולות מוטציה במקום שיטות executeGraphql כלליות: insert,‏ insertMany,‏ upsert ו-upsertMany.

ניהול נתוני משתמשים באמצעות שיטות executeGraphql

תרחיש לדוגמה לשימוש ב-Admin SDK הוא ניהול נתוני משתמשים.

שימוש בפרטי כניסה של אדמין

הגישה הפשוטה ביותר היא לגשת לנתוני המשתמשים באמצעות פרטי כניסה של אדמין.

// 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" } } }

התחזות לפרטי כניסה של משתמשים

יש גם תרחישים לדוגמה שבהם רוצים שהסקריפטים ישנו נתוני משתמשים על סמך פרטי כניסה מוגבלים, בשם משתמש ספציפי. הגישה הזו מבוססת על העקרון של הרשאות מינימליות.

כדי להשתמש בממשק הזה, צריך לאסוף מידע מאסימון אימות 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" } } }

ניהול נתונים ציבוריים באמצעות שיטות executeGraphql

אפשר לעבוד עם נתונים שגלויים לכולם באמצעות ה-SDK, ולהתחזות למשתמש לא מאומת.

// 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);

ביצוע פעולות על נתונים בכמות גדולה

מומלץ להשתמש ב-Admin SDK ב-Firebase לפעולות של נתונים בכמות גדולה במסדי נתונים בסביבת הייצור.

ה-SDK מספק את השיטות הבאות לעבודה עם נתונים בכמות גדולה. כל שיטה יוצרת ומפעילה מוטציה של GraphQL מהארגומנטים שסופקו.


// Methods of the bulk operations API
// dc is a Data 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 שנוצר ארוך יותר. כשמגיעים למגבלת האורך של משפט ה-SQL ב-PostgreSQL, מתקבלת הודעת שגיאה.

בפועל, כדאי להתנסות כדי למצוא את גודל האצווה המתאים לעומס העבודה שלכם.

מה השלב הבא?