استخدام حِزم SDK للمشرف التي تم إنشاؤها

تتيح لك حِزم SDK للمشرف Firebase SQL Connect استدعاء طلبات البحث والتعديل من بيئات موثوق بها، مثل "دوال Cloud" أو الأنظمة الخلفية المخصّصة أو محطة العمل الخاصة بك. بالطريقة نفسها التي تنشئ بها حِزم SDK لتطبيقاتك على الأجهزة، يمكنك إنشاء حزمة SDK مخصّصة للمشرف بالتوازي مع تصميم المخططات وطلبات البحث والتعديل التي تنشرها في خدمة SQL Connect. بعد ذلك، يمكنك دمج طرق من حزمة SDK هذه في منطق النظام الخلفي أو النصوص البرمجية للإدارة.

كما ذكرنا في مكان آخر، من المهم ملاحظة أنّه لا يتم إرسال طلبات البحث SQL Connect والتعديل من قِبل العملاء في وقت الطلب. بدلاً من ذلك، عند نشر عمليات SQL Connect، يتم تخزينها على الخادم مثل دوال Cloud. وهذا يعني أنّه في أي وقت تنشر فيه تغييرات على طلبات البحث والتعديل، عليك أيضًا إعادة إنشاء حِزم SDK للمشرف وإعادة نشر أي خدمات تعتمد عليها.

قبل البدء

• تعرَّف على تصميم المخططات وطلبات البحث والتعديل في SQL Connect. في سير عمل نموذجي، ستطوّرها بالتوازي مع رمز تطبيقك، بما في ذلك أي خدمات تستخدم حِزم SDK للمشرف.

• ثبِّت Firebase CLI.

  .

• أدرِج حزمة Admin SDK لـ Node.js كإحدى التبعيات في أي مكان تخطط فيه لاستدعاء حِزم SDK للمشرف التي تم إنشاؤها.

إنشاء حِزم SDK للمشرف

بعد إنشاء المخططات وطلبات البحث والتعديل في SQL Connect، يمكنك إنشاء حزمة SDK للمشرف المقابلة:

1. افتح ملف connector.yaml أو أنشئه وأضِف تعريفًا لـ adminNodeSdk:

   connectorId: default
   generate:
     adminNodeSdk:
       outputDir: ../../dataconnect-generated/admin-generated
       package: "@dataconnect/admin-generated"
       packageJsonDir: ../..
   

   عادةً ما يكون ملف connector.yaml في الدليل نفسه الذي يحتوي على ملفات GraphQL ‏ (.gql) التي تتضمّن تعريفات طلبات البحث والتعديل. إذا سبق لك إنشاء حِزم SDK للعميل، تم إنشاء هذا الملف من قبل.

2. أنشئ حزمة SDK.

   إذا كانت إضافة SQL Connect VS Code مثبَّتة، ستحافظ دائمًا على حِزم SDK التي تم إنشاؤها محدّثة.

   وإلا، استخدِم Firebase CLI:

   firebase dataconnect:sdk:generate

   أو لإعادة إنشاء حِزم SDK تلقائيًا عند تعديل ملفات gql:

   firebase dataconnect:sdk:generate --watch

تنفيذ العمليات من حزمة 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 } }
);

انتحال صفة مستخدم غير مصادَق عليه

تم تصميم حِزم SDK للمشرف ليتم تشغيلها من بيئات موثوق بها، وبالتالي يمكنها الوصول إلى قواعد البيانات بدون قيود.

عند تشغيل عمليات عامة باستخدام حزمة SDK للمشرف، عليك تجنُّب تشغيل العملية بامتيازات المشرف الكاملة (باتّباع مبدأ الامتياز الأقل). بدلاً من ذلك، عليك تشغيل العملية إما كمستخدم منتحَل صفته (راجِع القسم التالي) أو كمستخدم غير مصادَق عليه منتحَل صفته. لا يمكن للمستخدمين غير المصادَق عليهم تشغيل العمليات التي تم وضع علامة PUBLIC عليها فقط.

في المثال أعلاه، يتم تنفيذ طلب البحث getSongs كمستخدم غير مصادَق عليه.

انتحال صفة مستخدم

يمكنك أيضًا تنفيذ عمليات نيابةً عن مستخدمين معيّنين من خلال تمرير جزء من رمز مميّز أو كلّه في الخيار impersonate، ويجب على الأقل تحديد رقم تعريف المستخدم في طلب `sub`.Firebase Authentication (هذه هي القيمة نفسها لقيمة الخادم auth.uid التي يمكنك الرجوع إليها في عمليات GraphQL SQL Connect ).

عند انتحال صفة مستخدم، لن تنجح العملية إلا إذا اجتازت بيانات المستخدم التي قدّمتها عمليات التحقّق من المصادقة المحدّدة في تعريف 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 verifyIdToken للتحقّق من رمز المصادقة المميّز وفك ترميزه. على سبيل المثال، لنفترض أنّ نقطة النهاية تم تنفيذها كدالة HTTP عادية وأنّك مرّرت الرمز المميّز إلى نقطة النهاية باستخدام العنوان، كما هو معتاد:Firebase Authenticationauthorization

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). ويضمن ذلك أنّه لا يمكن للمتصلين على مستوى المشرف فقط تنفيذ هذه العمليات.