שימוש ב-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);

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

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

ה-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, תיתקלו בשגיאה.

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

מה השלב הבא?