المصادقة والربط بقاعدة بيانات

ينطبق ذلك على إصدار Cloud Firestore Enterprise فقط.

متطلبات الاتصال

في ما يلي المتطلبات اللازمة لعملاء Cloud Firestore المتوافقين مع MongoDB:

• يجب أن يتصل السائقون في وضع load balanced. يمنع ذلك برامج التشغيل من محاولة فهم بنية الخادم الدقيقة التي تتصل بها.
• يجب أن يتم الربط باستخدام طبقة المقابس الآمنة (SSL) مفعّلة.
• يجب أن يوقف برامج التشغيل عمليات الكتابة القابلة لإعادة المحاولة. لا تتيح خدمة Cloud Firestore المتوافقة مع MongoDB عمليات الكتابة القابلة لإعادة المحاولة في الوقت الحالي.

استرداد سلسلة الاتصال

تعتمد سلسلة اتصال قاعدة البيانات على المعرّف الفريد لقاعدة البيانات وموقعها الجغرافي وآلية المصادقة. توضّح التعليمات التالية كيفية إنشاء سلسلة الاتصال.

ملاحظة: تحتوي قاعدة البيانات على معرّف قاعدة بيانات ومعرّف فريد. معرّف قاعدة البيانات هو اسم المورد الذي تحدّده عند إنشاء قاعدة بيانات. المعرّف UID هو معرّف فريد عالمي (UUID4) من إنشاء النظام لقاعدة البيانات.

يعتمد سلسلة الاتصال الدقيقة على آلية المصادقة، ولكن تستخدم سلسلة الاتصال الأساسية التنسيق التالي:

mongodb://UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&tls=true&retryWrites=false

يمكنك الحصول على سلسلة الاتصال الأساسية بإحدى الطرق التالية:

Firebase وحدة التحكّم

1. في وحدة تحكّم Firebase، انتقِل إلى صفحة قاعدة بيانات Firestore.

   الانتقال إلى قاعدة بيانات Firestore

2. انقر على قاعدة البيانات التي تريد إثبات ملكيتها.
3. في لوحة المستكشف، انقر على عرض المزيد.
4. انقر على الربط باستخدام أدوات MongoDB.
5. انسخ سلسلة الاتصال.

gcloud

استخدِم gcloud firestore database describe لاسترداد المعرّف الفريد والموقع الجغرافي:

gcloud firestore databases describe \
--database=DATABASE_ID \
--format='yaml(locationId, uid)'

استبدِل DATABASE_ID بمعرّف قاعدة البيانات.

تتضمّن النتيجة الموقع الجغرافي ومعرّف UID لقاعدة البيانات. استخدِم هذه المعلومات لإنشاء سلسلة الاتصال الأساسية.

استخدِم سلسلة الاتصال الأساسية وإحدى الطرق التالية للمصادقة والاتصال بقاعدة البيانات:

• اسم المستخدم وكلمة المرور (SCRAM)
• حساب خدمة Compute Engine
• Google Auth Library

الاتصال باستخدام اسم المستخدم وكلمة المرور (SCRAM)

اتّبِع الخطوات التالية لإنشاء بيانات اعتماد مستخدم لقاعدة البيانات والاتصال بها.

قبل البدء

للحصول على الأذونات اللازمة لإنشاء مستخدم، اطلب من المشرف منحك دور userCredsAdmin (roles/datastore.userCredsAdmin) في خدمة إدارة الهوية وإمكانية الوصول (IAM) على قاعدة البيانات. لمزيد من المعلومات حول منح الأدوار، يُرجى الاطّلاع على إدارة الوصول إلى المشاريع والمجلدات والمؤسسات.

قد تتمكّن أيضًا من الحصول على الأذونات المطلوبة من خلال الأدوار المخصّصة أو الأدوار الأخرى المحدّدة مسبقًا.

إنشاء مستخدم والاتصال بقاعدة بيانات

لإنشاء مستخدم لقاعدة بيانات Cloud Firestore المتوافقة مع MongoDB، استخدِم إحدى الطريقتَين التاليتَين:

Google Cloud Console

1. في Google Cloud Console، انتقِل إلى صفحة قواعد البيانات.

   الانتقال إلى "قواعد البيانات"

2. اختَر قاعدة بيانات من قائمة قواعد البيانات.
3. في قائمة التنقل، انقر على المصادقة.
4. انقر على إضافة مستخدم.
5. أدخِل اسم مستخدم.
6. اختَر دورًا للمستخدم الجديد.
7. انقر على إضافة.

   سيتم عرض كلمة مرور المستخدم الجديد في مربّع حوار التأكيد.

   تنبيه: يتم عرض كلمة المرور مرة واحدة ولا يمكن استردادها. تخزين كلمة المرور هذه لاستخدامها في المستقبل

gcloud CLI

1. للمصادقة باستخدام SCRAM، يجب أولاً إنشاء بيانات اعتماد مستخدم. استخدِم الأمر gcloud alpha firestore user-creds:

   gcloud alpha firestore user-creds create USERNAME --database=DATABASE_ID

   استبدِل ما يلي:
   • ‫USERNAME: اسم المستخدم المطلوب إنشاؤه.
   • ‫DATABASE_ID: رقم تعريف قاعدة البيانات

   يتضمّن ناتج هذا الأمر كلمة مرور المستخدم.

   تنبيه: يتم عرض كلمة المرور مرة واحدة ولا يمكن استردادها. تخزين كلمة المرور هذه لاستخدامها في المستقبل

   تشبه النتائج ما يلي:

   name: projects/PROJECT_NAME/databases/DATABASE_ID/userCreds/USERNAME
   resourceIdentity:
     principal: principal://firestore.googleapis.com/projects/PROJECT_NUMBER/name/databases/DATABASE_ID/userCreds/USERNAME
   securePassword: PASSWORD

2. لا تتضمّن بيانات اعتماد المستخدم الجديد هذه أي أذونات تلقائيًا. للحصول على إذن بالقراءة والكتابة في قاعدة البيانات، أضِف الدور roles/datastore.user لقاعدة البيانات المحدّدة هذه:

   gcloud projects add-iam-policy-binding PROJECT_NAME \
   --member='principal://firestore.googleapis.com/projects/PROJECT_NUMBER/name/databases/DATABASE_ID/userCreds/USERNAME' \
   --role=roles/datastore.user \
   --condition='expression=resource.name == "projects/PROJECT_NAME/databases/DATABASE_ID",title="CONDITION_TITLE"'

   استبدِل ما يلي:
   • ‫PROJECT_NAME: اسم مشروعك
   • استبدِل PROJECT_NUMBER برقم المشروع.
   • ‫DATABASE_ID: رقم تعريف قاعدة البيانات
   • USERNAME: اسم المستخدم الذي أنشأته سابقًا
   • ‫CONDITION_TITLE: عنوان لهذه الحالة يؤدي هذا الشرط إلى حصر الوصول إلى قاعدة البيانات هذه فقط.

استخدِم سلسلة الاتصال التالية للاتصال بقاعدة البيانات باستخدام SCRAM:

mongodb://USERNAME:[e-mail]:443/DATABASE_ID?loadBalanced=true&authMechanism=SCRAM-SHA-256&tls=true&retryWrites=false

استبدِل ما يلي:

• USERNAME: اسم المستخدم
• PASSWORD: كلمة المرور التي أنشأتها لهذا المستخدم
• UID: المعرّف الفريد لقاعدة البيانات
• ‫LOCATION: موقع قاعدة البيانات
• ‫DATABASE_ID: رقم تعريف قاعدة البيانات

الربط بمكتبة Google Auth

يسجّل نموذج الرمز البرمجي التالي معالج ردّ الاتصال OIDC باستخدام Google Cloud مكتبة OAuth العادية.

تتيح لك هذه المكتبة استخدام عدد من أنواع المصادقة المختلفة (بيانات الاعتماد التلقائية للتطبيق، واتحاد هوية عبء العمل).

يتطلّب ذلك إضافة مكتبة المصادقة كعنصر يَعتمد عليه تشغيل التطبيق:

// Maven
<dependency>
  <groupId>com.google.auth</groupId>
  <artifactId>google-auth-library-oauth2-http</artifactId>
  <version>1.19.0</version>
</dependency>

// Gradle
implementation 'com.google.auth:google-auth-library-oauth2-http:1.19.0'

يوضّح نموذج الرمز البرمجي التالي كيفية الربط:

val db = MongoClients.create(
    clientSettings(
      "DATABASE_UID",
      "LOCATION"
    ).build()
  ).getDatabase("DATABASE_ID")


/**
 * Creates a connection to a Firestore with MongoDB Compatibility database.
 * @param databaseUid The uid of the database to connect to as a string. For example: f116f93a-519c-208a-9a72-3ef6c9a1f081
 * @param locationId The location of the database to connect to, for example: nam5, us-central1, us-east4 etc...
 * @param environment Determines whether to try and fetch an authentication credential from the
 * Compute Engine VM metadata service or whether to call gcloud.
 */
private static MongoClientSettings.Builder clientSettings(
  String databaseUid: String
  String locationId:String
): MongoClientSettings.Builder {
  MongoCredential credential =
    MongoCredential.createOidcCredential(null)
      .withMechanismProperty(
        MongoCredential.OIDC_CALLBACK_KEY,
        new MongoCredential.OidcCallback() {
          @Override
          MongoCredential.OidcCallbackResult onRequest(
MongoCredential.OidcCallbackContext context) {
     // Customize this credential builder for additional credential types.
     GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
            return new MongoCredential.OidcCallbackResult(
         credentials.getAccessToken().getTokenValue(),
         Duration.between(Instant.now(),
credentials.getAccessToken().getExpirationTime().toInstant()));
          }
        },
      );
  return MongoClientSettings.builder()
    .hosts(listOf(ServerAddress(
        "$databaseUid.$locationId.firestore.goog", 443)))
    .credential(credential)
    .applyToClusterSettings(builder ->
         builder.mode(ClusterConnectionMode.LOAD_BALANCED))
    ).applyToSslSettings(ssl -> ssl.enabled(true)).retryWrites(false);
}

استبدِل ما يلي:

• ‫DATABASE_UID: اسم مشروعك
• LOCATION: موقع قاعدة البيانات
• DATABASE_ID رقم تعريف قاعدة البيانات

الاتصال من جهاز Compute Engine افتراضي

يمكنك المصادقة والاتصال بقاعدة البيانات باستخدام حساب خدمة Compute Engine. لإجراء ذلك، أنشئ سياسة إدارة هوية وإمكانية وصول (IAM) لمشروع Google Cloud الذي يحتوي على قاعدة البيانات.

قبل البدء

إعداد حساب خدمة يديره المستخدم لجهازك الظاهري:

• لضبط حساب الخدمة أثناء إنشاء الجهاز الافتراضي، يُرجى الاطّلاع على إنشاء جهاز افتراضي يستخدم حساب خدمة يديره المستخدم.
• لضبط حساب الخدمة على جهاز افتراضي حالي، يُرجى الاطّلاع على تغيير حساب الخدمة المرتبط.

دوِّن عنوان البريد الإلكتروني لحساب الخدمة.

ضبط بيانات الاعتماد

لمنح حساب الخدمة دور roles/datastore.user للقراءة والكتابة في Cloud Firestore، نفِّذ الأمر التالي:

gcloud projects add-iam-policy-binding PROJECT_NAME --member="SERVICE_ACCOUNT_EMAIL" --role=roles/datastore.user

استبدِل ما يلي:

• ‫PROJECT_NAME: اسم مشروعك
• SERVICE_ACCOUNT_EMAIL: عنوان البريد الإلكتروني لحساب الخدمة الذي أنشأته

إنشاء سلسلة الاتصال

استخدِم التنسيق التالي لإنشاء سلسلة الاتصال:

mongodb://DATABASE_UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&tls=true&retryWrites=false&authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:FIRESTORE

استبدِل ما يلي:

• ‫DATABASE_UID: اسم مشروعك
• LOCATION: موقع قاعدة البيانات
• DATABASE_ID رقم تعريف قاعدة البيانات

لمزيد من المعلومات حول استرداد معرّف UID والموقع الجغرافي، يُرجى الاطّلاع على استرداد سلسلة الاتصال.

الربط باستخدام رمز دخول مؤقت

يمكنك استخدام رمز مميّز مؤقت للوصول Google Cloud لتشغيل أدوات التشخيص، مثل mongosh. يمكنك استخدام gcloud auth print-access-token للمصادقة باستخدام رمز مميّز قصير الأمد للوصول. هذا الرمز المميز صالح لمدة ساعة واحدة.

على سبيل المثال، استخدِم الأمر التالي للاتصال بقاعدة البيانات باستخدام mongosh:

mongosh --tls \
      --username access_token --password $(gcloud auth print-access-token) \
      'mongodb://UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&authMechanism=PLAIN&authSource=$external&retryWrites=false'

استبدِل ما يلي:

• DATABASE_UID: المعرّف الفريد لقاعدة البيانات
• ‫LOCATION: موقع قاعدة البيانات
• ‫DATABASE_ID: رقم تعريف قاعدة البيانات