بدء استخدام إصدار Firestore Enterprise باستخدام مكتبات برامج الخادم والعميل

يوضّح لك هذا الدليل السريع كيفية إعداد Cloud Firestore وإضافة البيانات، ثم استخدام العمليات الأساسية أو عمليات مسار التعلّم للاستعلام عن البيانات التي أضفتها للتو في وحدة تحكُّم Firebase باستخدام مكتبات برامج الخادم للعميل في Java وNode.js وPython.

استخدِم مكتبات برامج العميل هذه لإعداد بيئات خادم مميزة تتيح الوصول الكامل إلى قاعدة البيانات.

إنشاء قاعدة بيانات Cloud Firestore

  1. إذا لم يسبق لك ذلك، أنشئ مشروع Firebase: في وحدة تحكُّم Firebase، انقر على إضافة مشروع، ثم اتّبِع التعليمات الظاهرة على الشاشة لإنشاء مشروع Firebase أو لإضافة خدمات Firebase إلى مشروع حالي Google Cloud.

  2. في اللوحة اليمنى، انتقِل إلى قواعد البيانات ومساحة التخزين > Firestore.

  3. انقر على إنشاء قاعدة بيانات.

  4. اختَر Enterprise لوضع قاعدة البيانات.

  5. اختَر Firestore في الوضع الأصلي لوضع العملية، الذي يتيح العمليات الأساسية وعمليات خطوط النقل.

  6. اختَر موقعًا لقاعدة البيانات.

  7. اختَر وضعًا لبدء استخدام Cloud Firestore Security Rules

    وضع الاختبار

    هذا الوضع مناسب للبدء في استخدام مكتبات برامج العميل على الأجهزة الجوّالة والويب، ولكنّه يسمح لأي مستخدِم بقراءة بياناتك والكتابة فوقها. بعد الاختبار، احرص على مراجعة قسم تأمين بياناتك.

    للبدء في استخدام حزمة تطوير البرامج (SDK) على الويب أو منصات Apple أو Android، اختَر وضع الاختبار.

    وضع الإنتاج

    يمنع هذا الوضع جميع عمليات القراءة والكتابة من برامج العميل على الأجهزة الجوّالة والويب. ومع ذلك، يمكن لخوادم التطبيقات التي تمّت مصادقتها (Node.js وPython وJava) الوصول إلى قاعدة البيانات.

    سيتم تطبيق المجموعة الأولية من Cloud Firestore Security Rules على قاعدة بيانات Cloud Firestore التلقائية. إذا أنشأت قواعد بيانات متعددة لمشروعك، يمكنك نشر Cloud Firestore Security Rules لكل قاعدة بيانات.

  8. انقر على إنشاء.

عند تفعيل Cloud Firestore، يتم أيضًا تفعيل واجهة برمجة التطبيقات في Cloud API Manager.

إعداد بيئة التطوير

أضِف التبعيات ومكتبات برامج العميل المطلوبة إلى تطبيقك.

Node.js
  1. أضِف حزمة Firebase Admin SDK إلى تطبيقك: 
    npm install firebase-admin --save
  2. اتّبِع التعليمات أدناه لتهيئة Cloud Firestore باستخدام بيانات الاعتماد المناسبة في بيئتك.
Python
  1. أضِف حزمة Firebase Admin SDK إلى تطبيق Python: 
    pip install --upgrade firebase-admin
  2. اتّبِع التعليمات أدناه لتهيئة Cloud Firestore باستخدام بيانات الاعتماد المناسبة في بيئتك.
Java
  1. أضِف حزمة Firebase Admin SDK إلى تطبيقك:
    • باستخدام Gradle: 
      implementation 'com.google.firebase:firebase-admin:9.9.0'
    • باستخدام Maven: 
      <dependency>
  <groupId>com.google.firebase</groupId>
  <artifactId>firebase-admin</artifactId>
  <version>9.9.0</version>
</dependency>
  2. اتّبِع التعليمات أدناه لتهيئة Cloud Firestore باستخدام بيانات الاعتماد المناسبة في بيئتك.

تهيئة Cloud Firestore

هيئ مثيلاً من Cloud Firestore:

Node.js
تتم تهيئة حزمة Cloud Firestore SDK بطرق مختلفة حسب بيئتك. في ما يلي الطرق الأكثر شيوعًا. للحصول على مرجع كامل، يُرجى الاطّلاع على مقالة تهيئة حزمة Admin SDK.
  • التهيئة على Cloud Functions 
    const { initializeApp, applicationDefault, cert } = require('firebase-admin/app');
const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
     
    initializeApp();

const db = getFirestore();
  • التهيئة على Google Cloud 
    const { initializeApp, applicationDefault, cert } = require('firebase-admin/app');
const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
     
    initializeApp({
  credential: applicationDefault()
});

const db = getFirestore();
  • التهيئة على الخادم الخاص بك

    لاستخدام حزمة Firebase Admin SDK على الخادم الخاص بك (أو أي بيئة Node.js أخرى)، استخدِم حساب خدمة. انتقِل إلى إدارة الهوية وإمكانية الوصول والمشرف > حسابات الخدمة في Google Cloud Console. أنشئ مفتاحًا خاصًا جديدًا واحفظ ملف JSON. بعد ذلك، استخدِم الملف لتهيئة حزمة SDK: 

    const { initializeApp, applicationDefault, cert } = require('firebase-admin/app');
const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
     
    const serviceAccount = require('./path/to/serviceAccountKey.json');

initializeApp({
  credential: cert(serviceAccount)
});

const db = getFirestore();
Python
تتم تهيئة حزمة Cloud Firestore SDK بطرق مختلفة حسب بيئتك. في ما يلي الطرق الأكثر شيوعًا. للحصول على مرجع كامل، يُرجى الاطّلاع على مقالة تهيئة حزمة Admin SDK.
  • التهيئة على Google Cloud 
    import firebase_admin
from firebase_admin import firestore

# Application Default credentials are automatically created.
app = firebase_admin.initialize_app()
db = firestore.client()

    يمكن أيضًا استخدام بيانات الاعتماد التلقائية الحالية للتطبيق لتهيئة حزمة SDK.

    import firebase_admin
from firebase_admin import credentials
from firebase_admin import firestore

# Use the application default credentials.
cred = credentials.ApplicationDefault()

firebase_admin.initialize_app(cred)
db = firestore.client()
  • التهيئة على الخادم الخاص بك

    لاستخدام حزمة Firebase Admin SDK على الخادم الخاص بك، استخدِم حساب خدمة.

    انتقِل إلى إدارة الهوية وإمكانية الوصول والمشرف > حسابات الخدمة في Google Cloud Console. أنشئ مفتاحًا خاصًا جديدًا واحفظ ملف JSON. بعد ذلك، استخدِم الملف لتهيئة حزمة SDK: 

    import firebase_admin
from firebase_admin import credentials
from firebase_admin import firestore

# Use a service account.
cred = credentials.Certificate('path/to/serviceAccount.json')

app = firebase_admin.initialize_app(cred)

db = firestore.client()
    • Java
    تتم تهيئة حزمة Cloud Firestore SDK بطرق مختلفة حسب بيئتك. في ما يلي الطرق الأكثر شيوعًا. للحصول على مرجع كامل، يُرجى الاطّلاع على مقالة تهيئة حزمة Admin SDK.
  • التهيئة على Google Cloud 
    import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.firestore.Firestore;

import com.google.firebase.FirebaseApp;
import com.google.firebase.FirebaseOptions;

// Use the application default credentials
GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
FirebaseOptions options = new FirebaseOptions.Builder()
    .setCredentials(credentials)
    .setProjectId(projectId)
    .build();
FirebaseApp.initializeApp(options);

Firestore db = FirestoreClient.getFirestore();
  • التهيئة على الخادم الخاص بك

    لاستخدام حزمة Firebase Admin SDK على الخادم الخاص بك، استخدِم حساب خدمة.

    انتقِل إلى إدارة الهوية وإمكانية الوصول والمشرف > حسابات الخدمة في Google Cloud Console. أنشئ مفتاحًا خاصًا جديدًا واحفظ ملف JSON. بعد ذلك، استخدِم الملف لتهيئة حزمة SDK: 

    import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.firestore.Firestore;

import com.google.firebase.FirebaseApp;
import com.google.firebase.FirebaseOptions;

// Use a service account
InputStream serviceAccount = new FileInputStream("path/to/serviceAccount.json");
GoogleCredentials credentials = GoogleCredentials.fromStream(serviceAccount);
FirebaseOptions options = new FirebaseOptions.Builder()
    .setCredentials(credentials)
    .build();
FirebaseApp.initializeApp(options);

Firestore db = FirestoreClient.getFirestore();

    • إضافة البيانات باستخدام العمليات الأساسية

    لاستكشاف العمليات الأساسية وعمليات خطوط النقل للاستعلام عن البيانات، أضِف بيانات إلى قاعدة البيانات باستخدام العمليات الأساسية.

    Cloud Firestore يخزّن البيانات في مستندات، ويتم تخزين هذه المستندات في مجموعات. Cloud Firestore ينشئ المجموعات والمستندات ضمنيًا في المرة الأولى التي تضيف فيها بيانات إلى المستند. ليس عليك إنشاء المجموعات أو المستندات بشكلٍ صريح.

    أنشئ مجموعة ومستندًا جديدَين باستخدام نموذج الرمز البرمجي التالي.

    Node.js
    const docRef = db.collection('users').doc('alovelace');

await docRef.set({
  first: 'Ada',
  last: 'Lovelace',
  born: 1815
});
    Java
    DocumentReference docRef = db.collection("users").document("alovelace");
// Add document data  with id "alovelace" using a hashmap
Map<String, Object> data = new HashMap<>();
data.put("first", "Ada");
data.put("last", "Lovelace");
data.put("born", 1815);
//asynchronously write data
ApiFuture<WriteResult> result = docRef.set(data);
// ...
// result.get() blocks on response
System.out.println("Update time : " + result.get().getUpdateTime());
    Python
    doc_ref = db.collection("users").document("alovelace")
doc_ref.set({"first": "Ada", "last": "Lovelace", "born": 1815})

    قراءة البيانات باستخدام العمليات الأساسية

    استخدِم أداة عرض البيانات في وحدة تحكُّم Firebase للتأكّد بسرعة من أنّك أضفت بيانات إلى Cloud Firestore.

    يمكنك أيضًا استخدام طريقة "get" لاسترداد المجموعة بأكملها.

    Node.js
    const snapshot = await db.collection('users').get();
snapshot.forEach((doc) => {
  console.log(doc.id, '=>', doc.data());
});
    Python
    users_ref = db.collection("users")
docs = users_ref.stream()

for doc in docs:
    print(f"{doc.id} => {doc.to_dict()}")
    Java
    // asynchronously retrieve all users
ApiFuture<QuerySnapshot> query = db.collection("users").get();
// ...
// query.get() blocks on response
QuerySnapshot querySnapshot = query.get();
List<QueryDocumentSnapshot> documents = querySnapshot.getDocuments();
for (QueryDocumentSnapshot document : documents) {
  System.out.println("User: " + document.getId());
  System.out.println("First: " + document.getString("first"));
  if (document.contains("middle")) {
    System.out.println("Middle: " + document.getString("middle"));
  }
  System.out.println("Last: " + document.getString("last"));
  System.out.println("Born: " + document.getLong("born"));
}

    قراءة البيانات باستخدام عمليات خطوط النقل

    يمكنك الآن مقارنة تجربة الاستعلام عن البيانات باستخدام خطوط النقل بتجربة الاستعلام عن البيانات باستخدام العمليات الأساسية.

    Node.js
    const readDataPipeline = db.pipeline()
  .collection("users");

// Execute the pipeline and handle the result
try {
  const querySnapshot = await readDataPipeline.execute();
  querySnapshot.results.forEach((result) => {
    console.log(`${result.id} => ${result.data()}`);
  });
} catch (error) {
    console.error("Error getting documents: ", error);
}
    Python
    pipeline = client.pipeline().collection("users")
for result in pipeline.execute():
    print(f"{result.id} => {result.data()}")
    Java
    Pipeline pipeline = firestore.pipeline().collection("users");
ApiFuture<Pipeline.Snapshot> future = pipeline.execute();
for (com.google.cloud.firestore.PipelineResult result : future.get().getResults()) {
  System.out.println(result.getId() + " => " + result.getData());
}
// or, asynchronously
pipeline.execute(
    new ApiStreamObserver<com.google.cloud.firestore.PipelineResult>() {
      @Override
      public void onNext(com.google.cloud.firestore.PipelineResult result) {
        System.out.println(result.getId() + " => " + result.getData());
      }

      @Override
      public void onError(Throwable t) {
        System.err.println(t);
      }

      @Override
      public void onCompleted() {
        System.out.println("done");
      }
    });

    الخطوات التالية

    تعمّق في معرفتك بالعمليات الأساسية وعمليات خطوط النقل من خلال المواضيع التالية: