احراز هویت و اتصال به پایگاه داده

فقط مربوط به Cloud Firestore Enterprise edition.

الزامات اتصال

موارد زیر برای Cloud Firestore با مشتریان سازگاری MongoDB مورد نیاز است:

• رانندگان باید در حالت load balanced متصل شوند. این مانع از تلاش درایورها برای درک توپولوژی سرور دقیقی می شود که به آن متصل می شوند.
• درایورها باید با SSL فعال وصل شوند.
• درایورها باید نوشتن های قابل امتحان مجدد را غیرفعال کنند. Cloud Firestore با سازگاری MongoDB در حال حاضر از نوشتن های قابل امتحان مجدد پشتیبانی نمی کند.

رشته اتصال را بازیابی کنید

رشته اتصال پایگاه داده به UID پایگاه داده، محل پایگاه داده و مکانیزم احراز هویت بستگی دارد. دستورالعمل های زیر نحوه تشکیل رشته اتصال را توضیح می دهد.

توجه: یک پایگاه داده دارای شناسه پایگاه داده و UID است. شناسه پایگاه داده نام منبعی است که هنگام ایجاد پایگاه داده تعیین می کنید. UID یک سیستم UUID4 برای پایگاه داده است.

رشته اتصال دقیق به مکانیزم احراز هویت بستگی دارد، اما رشته اتصال پایه از فرمت زیر استفاده می کند:

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

می توانید رشته اتصال پایه را به یکی از روش های زیر بدست آورید:

کنسول Firebase

1. در کنسول Firebase ، به صفحه Firestore Database بروید.

   به پایگاه داده Firestore بروید

2. روی پایگاه داده ای که می خواهید احراز هویت کنید کلیک کنید.
3. در پانل Explorer ، روی View more کلیک کنید.
4. Connect using MongoDB tools را انتخاب کنید.
5. رشته اتصال را کپی کنید.

gcloud

gcloud firestore database describe برای بازیابی UID و اطلاعات مکان استفاده کنید:

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

DATABASE_ID با شناسه پایگاه داده جایگزین کنید.

خروجی شامل مکان و UID پایگاه داده است. از این اطلاعات برای ساخت رشته اتصال پایه استفاده کنید.

از رشته اتصال پایه و یکی از روش های زیر برای احراز هویت و اتصال به پایگاه داده خود استفاده کنید:

• نام کاربری و رمز عبور (SCRAM)
• حساب خدمات Compute Engine
• کتابخانه Google Auth

اتصال با نام کاربری و رمز عبور (SCRAM)

این مراحل را دنبال کنید تا یک اعتبار کاربری برای پایگاه داده خود ایجاد کنید و به پایگاه داده خود متصل شوید.

قبل از شروع

برای دریافت مجوزهایی که برای ایجاد کاربر نیاز دارید، از سرپرست خود بخواهید نقش userCredsAdmin ( roles/datastore.userCredsAdmin ) IAM را در پایگاه داده شما به شما اعطا کند. برای اطلاعات بیشتر درباره اعطای نقش، به مدیریت دسترسی به پروژه‌ها، پوشه‌ها و سازمان‌ها مراجعه کنید.

همچنین ممکن است بتوانید مجوزهای لازم را از طریق نقش های سفارشی یا سایر نقش های از پیش تعریف شده دریافت کنید.

یک کاربر ایجاد کنید و به پایگاه داده متصل شوید

برای ایجاد یک کاربر برای Cloud Firestore خود با پایگاه داده سازگاری MongoDB، از یکی از روش های زیر استفاده کنید:

کنسول Google Cloud

1. در کنسول Google Cloud، به صفحه پایگاه داده بروید.

   به پایگاه داده بروید

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 : UID پایگاه داده.
• LOCATION : مکان پایگاه داده.
• DATABASE_ID : شناسه پایگاه داده.

با کتابخانه Google Auth متصل شوید

نمونه کد زیر یک کنترل کننده تماس OIDC را با استفاده از کتابخانه استاندارد OAuth Google Cloud ثبت می کند.

این کتابخانه به شما امکان می دهد از انواع مختلف احراز هویت (Application Default Credentials، Workload Identity Federation) استفاده کنید.

این نیاز به افزودن کتابخانه اعتبار به عنوان یک وابستگی دارد:

// 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 ایجاد کنید که حاوی پایگاه داده شما است.

قبل از شروع

یک حساب سرویس مدیریت شده توسط کاربر برای VM خود پیکربندی کنید:

• برای پیکربندی حساب سرویس در حین ایجاد VM، به ایجاد یک VM که از یک حساب سرویس مدیریت شده توسط کاربر استفاده می کند، مراجعه کنید.
• برای پیکربندی حساب سرویس در یک ماشین مجازی موجود، به تغییر حساب سرویس پیوست شده مراجعه کنید.

ایمیل حساب سرویس خود را یادداشت کنید.

اعتبارنامه ها را پیکربندی کنید

برای اعطای نقش 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 و مکان، به بازیابی رشته اتصال مراجعه کنید.

با یک نشانه دسترسی موقت متصل شوید

برای اجرای ابزارهای تشخیصی مانند mongosh می‌توانید از یک نشانه دسترسی موقت Google Cloud استفاده کنید. می‌توانید از 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 : UID پایگاه داده
• LOCATION : مکان پایگاه داده
• DATABASE_ID : شناسه پایگاه داده