Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

אימות וחיבור למסד נתונים

דרישות לחיבור

הדרישות הבאות חלות על לקוחות של Firestore עם תאימות ל-MongoDB:

הנהגים צריכים להתחבר במצב load balanced. כך נמנע מהדרייברים לנסות להבין את טופולוגיית השרת המדויקת שאליה הם מתחברים.
מנהלי ההתקנים צריכים להתחבר עם SSL מופעל.
מנהלי ההתקנים צריכים להשבית כתיבות שניתן לנסות שוב. ‫Firestore עם תאימות ל-MongoDB לא תומך בכתיבות שאפשר לנסות שוב. אין צורך להשבית קריאות שאפשר לנסות שוב כי הן נתמכות.

אחזור מחרוזת החיבור

מחרוזת החיבור למסד הנתונים תלויה במזהה המשתמש של מסד הנתונים, במיקום של מסד הנתונים ובמנגנון האימות. בהוראות הבאות מוסבר איך נוצר מחרוזת החיבור.

מחרוזת החיבור המדויקת תלויה במנגנון האימות, אבל מחרוזת החיבור הבסיסית היא בפורמט הבא:

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

אפשר לקבל את מחרוזת החיבור הבסיסית באחת מהדרכים הבאות:

המסוף

נכנסים לדף Databases במסוף Google Cloud .

מעבר אל Databases
ברשימת מסדי הנתונים, לוחצים על מזהה מסד הנתונים הרלוונטי.
בחלונית Explorer מוצג מחרוזת החיבור הבסיסית. מעתיקים את מחרוזת החיבור הזו ומשתמשים בה כדי להתחבר למסד הנתונים.

gcloud

כדי לאחזר את ה-UID ואת פרטי המיקום, משתמשים ב-gcloud firestore database describe:

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

מחליפים את DATABASE_ID במזהה מסד הנתונים.

הפלט כולל את המיקום ואת ה-UID של מסד הנתונים. השתמשו במידע הזה כדי ליצור את מחרוזת החיבור הבסיסית.

משתמשים במחרוזת החיבור הבסיסית ובאחת מהשיטות הבאות כדי לבצע אימות ולהתחבר למסד הנתונים:

שם משתמש וסיסמה (SCRAM)
חשבון שירות של Compute Engine
חשבון שירות של Cloud Run
Google Auth Library

התחברות באמצעות שם משתמש וסיסמה (SCRAM)

כדי ליצור פרטי כניסה למשתמש במסד הנתונים ולהתחבר למסד הנתונים, צריך לבצע את השלבים הבאים.

לפני שמתחילים

כדי לקבל את ההרשאות שדרושות ליצירת משתמש, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים במסד הנתונים:

הכל: userCredsAdmin (roles/datastore.userCredsAdmin)

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.

יצירת משתמש וחיבור למסד נתונים

כדי ליצור משתמש במסד נתונים של Firestore עם תאימות ל-MongoDB, משתמשים באחת מהשיטות הבאות:

מסוףGoogle Cloud

נכנסים לדף Databases במסוף Google Cloud .

מעבר אל Databases
בוחרים מסד נתונים מתוך רשימת מסדי הנתונים.
בתפריט הניווט, לוחצים על אבטחה.
לוחצים על הוספת משתמש.
מזינים שם משתמש.
בוחרים תפקיד למשתמש החדש.
לוחצים על הוספה.
הסיסמה של המשתמש החדש תוצג בתיבת הדו-שיח לאישור.

זהירות: הסיסמה מוצגת פעם אחת ואי אפשר לאחזר אותה. אחסון הסיסמה לשימוש עתידי.

‫CLI של gcloud

כדי לבצע אימות באמצעות 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: שם לתנאי הזה. התנאי הזה מגביל את הגישה רק למסד הנתונים הזה.

Java

בקטע הזה מופיע קוד לדוגמה ליצירת פרטי כניסה של משתמש ולהגדרת מדיניות IAM באמצעות ספריות לקוח אדמיניסטרטיביות של Java. בדוגמה נעשה שימוש בספרייה Firestore Admin Client ליצירת שם משתמש וסיסמה, ובספרייה Google Cloud Resource Manager להגדרת IAM.

ב-builds של 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);
    }
  }
}

Python

בקטע הזה מופיעה דוגמת קוד ליצירת פרטי כניסה של משתמש ולהגדרת מדיניות IAM באמצעות ספריות לקוח אדמיניסטרטיביות של Python. בדוגמה נעשה שימוש בספרייה Google Cloud Firestore API client library ליצירת שם משתמש וסיסמה, ובספריות Google Cloud Iam API client library ו-Google Cloud Resource Manager API client library להגדרת 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: ה-UID של מסד הנתונים. לדוגמה: f116f93a-519c-208a-9a72-3ef6c9a1f081
‫LOCATION: המיקום של מסד הנתונים.
‫DATABASE_ID: מזהה מסד הנתונים.

חיבור ל-Google Auth Library

בדוגמת הקוד הבאה נרשם גורם מטפל בקריאה חוזרת (callback) של OIDC שמשתמש בGoogle Cloud ספריית OAuth רגילה.

הספרייה הזו מאפשרת להשתמש במספר סוגים שונים של אימות (Application Default Credentials, איחוד שירותי אימות הזהות של עומסי עבודה).

לשם כך צריך להוסיף את ספריית האימות כהסתמכות:

// 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: ה-UID של מסד הנתונים. לדוגמה: f116f93a-519c-208a-9a72-3ef6c9a1f081
‫LOCATION: המיקום של מסד הנתונים.
DATABASE_ID מזהה מסד הנתונים.

התחברות מסביבת מחשוב Google Cloud

בקטע הזה מוסבר איך להתחבר ל-Firestore עם תאימות ל-MongoDB מסביבת מחשוב, כמו Compute Engine או שירות או משימה של Cloud Run. Google Cloud

התחברות ממכונה וירטואלית ב-Compute Engine

אתם יכולים לבצע אימות ולהתחבר למסד הנתונים באמצעות חשבון שירות של Compute Engine. כדי לעשות את זה, צריך ליצור מדיניות IAM עבורGoogle Cloud הפרויקט שמכיל את מסד הנתונים.

לפני שמתחילים

מגדירים חשבון שירות שמנוהל על ידי משתמש עבור המכונה הווירטואלית:

כדי להגדיר חשבון שירות במהלך יצירת מכונה וירטואלית, אפשר לעיין במאמר יצירת מכונה וירטואלית שמשתמשת בחשבון שירות שמנוהל על ידי משתמש.
- כדי להגדיר חשבון שירות במכונה וירטואלית קיימת, ראו שינוי חשבון השירות המצורף.

כדי להשלים את הגדרת מדיניות IAM לחשבון השירות של Compute Engine, צריך לפעול לפי ההוראות שבקטעים הגדרת פרטי הכניסה.

התחברות מ-Cloud Run

אתם יכולים לבצע אימות ולהתחבר למסד הנתונים באמצעות חשבון שירות של Cloud Run. כדי לעשות את זה, יוצרים מדיניות IAM עבורGoogle Cloud הפרויקט שמכיל את מסד הנתונים.

לפני שמתחילים

כדי להגדיר את חשבון השירות בשביל Cloud Run, ראו הגדרת זהות שירות
- כדי לזהות את חשבון השירות שכבר משויך לשירות Cloud Run, אפשר לעיין במאמר בנושא gcloud run services describe.

כדי להשלים את ההגדרה של מדיניות IAM לחשבון השירות של Cloud Run, צריך לפעול לפי ההוראות שבקטעים הגדרת פרטי הכניסה.

הגדרת פרטי כניסה

כדי לתת לחשבון השירות את התפקיד roles/datastore.user לקריאה וכתיבה ב-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: ה-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: ה-UID של מסד הנתונים. לדוגמה: f116f93a-519c-208a-9a72-3ef6c9a1f081
‫LOCATION: מיקום מסד הנתונים
‫DATABASE_ID: מזהה מסד נתונים