原生模式下的 Cloud Firestore 企业版现已推出！了解详情。

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

اصالت‌سنجی و متصل شدن به پایگاه داده

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

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

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

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

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

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

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

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

کنسول Firebase

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

رفتن به Firestore Database
روی پایگاه داده‌ای که می‌خواهید اصالت‌سنجی شود کلیک کنید.
در پانل کاوشگر، روی مشاهده موارد بیشتر کلیک کنید.
Connect using MongoDB tools (اتصال بااستفاده از ابزارهای MongoDB) را انتخاب کنید.
رشته اتصال را کپی کنید.

gcloud

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

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

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

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

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

نام کاربری و گذرواژه (SCRAM)
Compute Engine حساب سرویس
Cloud Run حساب سرویس
کتابخانه اصالت‌سنجی Google

اتصال با نام کاربری و گذرواژه (SCRAM)

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

قبل از شروع

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

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

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

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

کنسول Firebase

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

رفتن به Firestore Database
پایگاه داده‌ای را از فهرست پایگاه‌های داده انتخاب کنید.
در منوِ پیمایش، روی امنیت کلیک کنید.
روی افزودن کاربر کلیک کنید.
نام کاربری را وارد کنید.
نقشی برای کاربر جدید انتخاب کنید.
روی افزودن کاربر کلیک کنید.

گذرواژه کاربر جدید در کادر گفتگوی تأیید نمایش داده می‌شود.

gcloud CLI

برای اصالت‌سنجی با 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
```
به‌طور پیش‌فرض، این اطلاعات کاربری جدید کاربر هیچ اجازه‌ای ندارد. برای دسترسی خواندن و نوشتن به پایگاه داده، نقش 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: عنوانی برای این شرط. این شرط دسترسی را فقط به این پایگاه داده محدود می‌کند.

جاوا

این بخش نمونه کدی برای ایجاد اعتبارنامه کاربر و پیکربندی خط‌مشی IAM بااستفاده از کتابخانه‌های مشتری اداری Java ارائه می‌دهد. این نمونه از کتابخانه 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 بااستفاده از کتابخانه‌های کارخواه مدیریتی Python ارائه می‌دهد. این نمونه از کتابخانه کارخواه Google Cloud Firestore API برای ایجاد نام کاربری و گذرواژه، و از کتابخانه کارخواه Google Cloud Iam API و کتابخانه کارخواه Google Cloud Resource Manager API برای پیکربندی IAM استفاده می‌کند.

کتابخانه‌های Python موردنیاز را می‌توان با ابزار 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: شناسه یکتای پایگاه داده. برای مثال: f116f93a-519c-208a-9a72-3ef6c9a1f081
‫LOCATION: مکان پایگاه داده.
‫DATABASE_ID: شناسه پایگاه داده.

اتصال با Google Auth Library

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

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

این کار مستلزم افزودن کتابخانه 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: شناسه یکتای پایگاه داده. برای مثال: f116f93a-519c-208a-9a72-3ef6c9a1f081
‫LOCATION: مکان پایگاه داده شما.
DATABASE_ID شناسه پایگاه داده.

متصل شدن از محیط محاسباتی Google Cloud

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

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

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

قبل از شروع

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

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

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

پرواز رابط از Cloud Run

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

قبل از شروع

برای پیکربندی حساب سرویس برای Cloud Run، به پیکربندی هویت سرویس
- برای تعیین حساب سرویسی که قبلاً با سرویس Cloud Run شما مرتبط شده است، به gcloud run services describe مراجعه کنید

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

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

برای اعطای نقش roles/datastore.user به حساب سرویس برای خواندن و نوشتن در Cloud Firestore، فرمان زیر را اجرا کنید:

gcloud projects add-iam-policy-binding PROJECT_NAME --member="serviceAccount: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: شناسه یکتای پایگاه داده. برای مثال: f116f93a-519c-208a-9a72-3ef6c9a1f081
‫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: شناسه یکتای پایگاه داده. برای مثال: f116f93a-519c-208a-9a72-3ef6c9a1f081
‫LOCATION: مکان پایگاه داده
DATABASE_ID: شناسه پایگاه داده

اصالت‌سنجی و متصل شدن به پایگاه داده با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

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

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

کنسول Firebase

gcloud

اتصال با نام کاربری و گذرواژه (SCRAM)

قبل از شروع

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

کنسول Firebase

gcloud CLI

جاوا

پایتون

اتصال با Google Auth Library

متصل شدن از محیط محاسباتی Google Cloud

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

قبل از شروع

پرواز رابط از Cloud Run

قبل از شروع

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

رشته اتصال را بسازید

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

اصالت‌سنجی و متصل شدن به پایگاه داده