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

فقط مربوط به نسخه Cloud Firestore Enterprise است.

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

موارد زیر برای Cloud Firestore با کلاینت‌های سازگار با MongoDB مورد نیاز است:

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

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

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

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

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

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

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

    به پایگاه داده فایراستور بروید

  2. روی پایگاه داده‌ای که می‌خواهید اعتبارسنجی کنید کلیک کنید.
  3. در پنل اکسپلورر ، روی سپس View more کلیک کنید.
  4. اتصال با استفاده از ابزارهای MongoDB را انتخاب کنید.
  5. رشته اتصال را کپی کنید.
جی‌کلاود

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

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

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

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

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

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

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

قبل از اینکه شروع کنی

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

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

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

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

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

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

  2. یک پایگاه داده از لیست پایگاه‌های داده انتخاب کنید.
  3. در منوی پیمایش، روی «تأیید» کلیک کنید.
  4. روی افزودن کاربر کلیک کنید.
  5. یک نام کاربری وارد کنید.
  6. یک نقش برای کاربر جدید انتخاب کنید.
  7. روی افزودن کلیک کنید.

    رمز عبور کاربر جدید در کادر محاوره‌ای تأیید نمایش داده خواهد شد.

gcloud CLI
  1. برای احراز هویت با SCRAM، ابتدا باید یک اعتبارنامه کاربری ایجاد کنید. از دستور gcloud firestore user-creds استفاده کنید:
    gcloud 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"'
    موارد زیر را جایگزین کنید:
جاوا

این بخش یک نمونه کد برای ایجاد اعتبارنامه‌های کاربر و پیکربندی سیاست IAM با استفاده از کتابخانه‌های کلاینت مدیریتی جاوا ارائه می‌دهد. این نمونه از کتابخانه Firestore Admin Client برای ایجاد نام کاربری و رمز عبور و از کتابخانه Google Cloud Resource Manager برای پیکربندی IAM استفاده می‌کند.

برای ساخت‌های Maven، می‌توانید از مختصات زیر استفاده کنید:

com.google.cloud:google-cloud-firestore-admin:3.33.1
com.google.cloud:google-cloud-resourcemanager:1.76.0

ارائه اعتبارنامه‌های کاربر و یک سیاست IAM:

import com.google.cloud.firestore.v1.FirestoreAdminClient;
import com.google.cloud.resourcemanager.v3.ProjectName;
import com.google.cloud.resourcemanager.v3.ProjectsClient;
import com.google.firestore.admin.v1.CreateUserCredsRequest;
import com.google.firestore.admin.v1.GetUserCredsRequest;
import com.google.firestore.admin.v1.UserCreds;
import com.google.iam.v1.Binding;
import com.google.iam.v1.GetIamPolicyRequest;
import com.google.iam.v1.GetPolicyOptions;
import com.google.iam.v1.Policy;
import com.google.iam.v1.SetIamPolicyRequest;
import com.google.protobuf.FieldMask;
import com.google.type.Expr;

public class FirestoreUserCredsExample {
  /**
   * Provision user credentials and configure an IAM policy to allow SCRAM authentication into the
   * specified Firestore with Mongo Compatibility database.
   */
  private static void provisionFirestoreUserCredsAndIAM(
      String projectId, String databaseId, String userName) throws Exception {
    UserCreds userCreds = createUserCreds(projectId, databaseId, userName);

    // Note the password returned in the UserCreds proto - it cannot be retrieved again
    // after the initial call to the createUserCreds API.
    System.out.printf(
        "Created credentials for username: %s:\nIAM principal: %s\nPassword: [%s]\n",
        userName, userCreds.getResourceIdentity().getPrincipal(), userCreds.getSecurePassword());

    // Provision an IAM binding for the principal associated with these user credentials.
    updateIamPolicyForUserCreds(projectId, databaseId, userName, userCreds);

    // Emit the password again.
    System.out.printf(
        "Successfully configured IAM policy for database: %s, username: %s\n",
        databaseId, userName);
    System.out.printf("Please make a note of the password: [%s]\n", userCreds.getSecurePassword());
  }

  /** Provision new user credentials using the FirestoreAdminClient. */
  private static UserCreds createUserCreds(String projectId, String databaseId, String userName)
      throws Exception {
    FirestoreAdminClient firestoreAdminClient = FirestoreAdminClient.create();
    return firestoreAdminClient.createUserCreds(
        CreateUserCredsRequest.newBuilder()
            .setParent(String.format("projects/%s/databases/%s", projectId, databaseId))
            .setUserCredsId(userName)
            .build());
  }

  /** Update the IAM policy using the Resource Manager ProjectsClient. */
  private static void updateIamPolicyForUserCreds(
      String projectId, String databaseId, String userName, UserCreds userCreds) throws Exception {
    try (ProjectsClient projectsClient = ProjectsClient.create()) {
      ProjectName projectName = ProjectName.of(projectId);

      // Get the current IAM policy.
      Policy currentPolicy =
          projectsClient.getIamPolicy(
              GetIamPolicyRequest.newBuilder()
                  .setResource(projectName.toString())
                  .setOptions(GetPolicyOptions.newBuilder().setRequestedPolicyVersion(3).build())
                  .build());

      String role = "roles/datastore.user";
      String title = String.format("Conditional IAM binding for %s", userName);
      String expression =
          String.format("resource.name == \"projects/%s/databases/%s\"", projectId, databaseId);

      // Construct an updated IAM policy with an additional binding for the user credentials.
      Policy.Builder policyBuilder = currentPolicy.toBuilder();
      Binding newBinding =
          Binding.newBuilder()
              .setRole(role)
              .setCondition(Expr.newBuilder().setTitle(title).setExpression(expression).build())
              .addMembers(userCreds.getResourceIdentity().getPrincipal())
              .build();
      policyBuilder.addBindings(newBinding);

      // Update the policy
      SetIamPolicyRequest request =
          SetIamPolicyRequest.newBuilder()
              .setResource(projectName.toString())
              .setPolicy(policyBuilder.build())
              .setUpdateMask(FieldMask.newBuilder().addPaths("bindings").addPaths("etag").build())
              .build();
      System.out.println(request);

      Policy updatedPolicy = projectsClient.setIamPolicy(request);
      System.out.println("Policy updated successfully: " + updatedPolicy);
    }
  }
}
پایتون

این بخش یک نمونه کد برای ایجاد اعتبارنامه‌های کاربر و پیکربندی سیاست IAM با استفاده از کتابخانه‌های کلاینت مدیریتی پایتون ارائه می‌دهد. این نمونه از کتابخانه کلاینت API گوگل کلود فایراستور برای ایجاد نام کاربری و رمز عبور و از کتابخانه کلاینت API گوگل کلود آی‌ام و کتابخانه کلاینت API گوگل کلود ریسورس منیجر برای پیکربندی IAM استفاده می‌کند.

کتابخانه‌های مورد نیاز پایتون را می‌توان با ابزار pip نصب کرد:

pip install google-cloud-iam
pip install google-cloud-firestore
pip install google-cloud-resource-manager

ارائه اعتبارنامه‌های کاربر و یک سیاست IAM:

from google.cloud import resourcemanager_v3
from google.cloud.firestore_admin_v1 import FirestoreAdminClient
from google.cloud.firestore_admin_v1 import types
from google.iam.v1 import iam_policy_pb2
from google.iam.v1 import policy_pb2
from google.type import expr_pb2


def create_user_creds(project_id: str, database_id: str, user_name: str):
  """Provision new user credentials using the FirestoreAdminClient."""
  client = FirestoreAdminClient()
  request = types.CreateUserCredsRequest(
      parent=f'projects/{project_id}/databases/{database_id}',
      user_creds_id=user_name,
  )
  response = client.create_user_creds(request)
  return response


def update_iam_policy_for_user_creds(
    project_id: str, database_id: str, user_name: str, user_creds
):
  """Update the IAM policy using the Resource Manager ProjectsClient."""
  client = resourcemanager_v3.ProjectsClient()
  request = iam_policy_pb2.GetIamPolicyRequest()
  request.resource = f'projects/{project_id}'
  request.options.requested_policy_version = 3

  # Get the current IAM policy
  current_policy = client.get_iam_policy(request)

  # Construct an updated IAM policy with an additional binding
  # for the user credentials.
  updated_policy = policy_pb2.Policy()
  binding = policy_pb2.Binding()
  iam_condition = expr_pb2.Expr()

  iam_condition.title = f'Conditional IAM binding for {user_name}'
  iam_condition.expression = (
      f'resource.name == "projects/{project_id}/databases/{database_id}"'
  )

  binding.role = 'roles/datastore.user'
  binding.condition.CopyFrom(iam_condition)
  binding.members.append(user_creds.resource_identity.principal)
  updated_policy.bindings.append(binding)

  # Update the policy
  updated_policy.MergeFrom(current_policy)
  set_policy_request = iam_policy_pb2.SetIamPolicyRequest()
  set_policy_request.resource = f'projects/{project_id}'
  set_policy_request.policy.CopyFrom(updated_policy)

  final_policy = client.set_iam_policy(set_policy_request)
  print(f'Policy updated successfully {final_policy}')


def provision_firestore_user_creds_and_iam(
    project_id: str, database_id: str, user_name: str
):
  """Provision user credentials and configure an IAM policy."""
  user_creds = create_user_creds(project_id, database_id, user_name)

  # Note the password returned in the UserCreds proto - it cannot be
  # retrieved again after the initial call to the create_user_creds API.
  print(f'Created credentials for username: {user_name}')
  print(f'IAM principal: {user_creds.resource_identity.principal}')
  print(f'Password: [{user_creds.secure_password}]')

  # Provision an IAM binding for the principal associated with
  # these user credentials.
  update_iam_policy_for_user_creds(
      project_id, database_id, user_name, user_creds
  )

  # Emit the password again
  print(
      f'Successfully configured IAM policy for database: {database_id},'
      f' username: {user_name}'
  )
  print(f'Please make a note of the password: [{user_creds.secure_password}]')

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

mongodb://USERNAME:PASSWORD@UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&authMechanism=SCRAM-SHA-256&tls=true&retryWrites=false

موارد زیر را جایگزین کنید:

  • USERNAME : نام کاربری.
  • PASSWORD : رمز عبوری که برای این کاربر ایجاد کرده‌اید.
  • UID : شناسه کاربری پایگاه داده.
  • LOCATION : محل پایگاه داده.
  • DATABASE_ID : شناسه پایگاه داده.

با کتابخانه Google Auth ارتباط برقرار کنید

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

این کتابخانه به شما امکان می‌دهد از انواع مختلفی از احراز هویت (اعتبارنامه‌های پیش‌فرض برنامه، فدراسیون هویت بار کاری) استفاده کنید.

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

// 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 شناسه پایگاه داده.

اتصال از یک محیط محاسباتی Google Cloud

این بخش اتصال به Cloud Firestore با سازگاری MongoDB از یک محیط محاسباتی Google Cloud ، مانند Compute Engine یا یک سرویس یا کار Cloud Run را شرح می‌دهد.

اتصال از طریق ماشین مجازی Compute Engine

شما می‌توانید با استفاده از یک حساب کاربری سرویس Compute Engine ، پایگاه داده خود را احراز هویت کرده و به آن متصل شوید. برای انجام این کار، یک سیاست IAM برای پروژه Google Cloud که شامل پایگاه داده شما است، ایجاد کنید.

قبل از اینکه شروع کنی

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

برای تکمیل پیکربندی خط‌مشی IAM برای حساب سرویس Compute Engine خود، به دستورالعمل‌های موجود در بخش‌های پیکربندی اعتبارنامه‌ها مراجعه کنید.

از Cloud Run متصل شوید

شما می‌توانید با استفاده از یک حساب کاربری سرویس Cloud Run پایگاه داده خود را احراز هویت کرده و به آن متصل شوید. برای انجام این کار، یک سیاست IAM برای پروژه Google Cloud که شامل پایگاه داده شما است، ایجاد کنید.

قبل از اینکه شروع کنی

برای تکمیل پیکربندی خط‌مشی IAM برای حساب سرویس Cloud Run خود، به دستورالعمل‌های موجود در بخش‌های پیکربندی اعتبارنامه‌ها مراجعه کنید.

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

برای اعطای نقش 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 : شناسه پایگاه داده