| فقط مربوط به نسخه 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
در کنسول Firebase ، به صفحه پایگاه داده فایراستور بروید.
- روی پایگاه دادهای که میخواهید اعتبارسنجی کنید کلیک کنید.
- در پنل اکسپلورر ، روی سپس View more کلیک کنید.
- اتصال با استفاده از ابزارهای MongoDB را انتخاب کنید.
- رشته اتصال را کپی کنید.
جیکلاود
برای بازیابی اطلاعات UID و موقعیت مکانی gcloud firestore database describe استفاده کنید:
gcloud firestore databases describe \ --database=DATABASE_ID \ --format='yaml(locationId, uid)'
به جای DATABASE_ID شناسه پایگاه داده را وارد کنید.
خروجی شامل مکان و شناسه کاربری پایگاه داده است. از این اطلاعات برای ساخت رشته اتصال پایه استفاده کنید.
برای احراز هویت و اتصال به پایگاه داده خود، از رشته اتصال پایه و یکی از روشهای زیر استفاده کنید:
- نام کاربری و رمز عبور (SCRAM)
- حساب سرویس Compute Engine
- حساب کاربری سرویس Cloud Run
- کتابخانه احراز هویت گوگل
با نام کاربری و رمز عبور (SCRAM) متصل شوید
برای ایجاد اعتبارنامه کاربری برای پایگاه داده خود و اتصال به پایگاه داده، این مراحل را دنبال کنید.
قبل از اینکه شروع کنی
برای دریافت مجوزهایی که برای ایجاد یک کاربر نیاز دارید، از مدیر سیستم خود بخواهید که نقش IAM کاربر UserCredsAdmin (roles/datastore.userCredsAdmin ) را در پایگاه داده شما به شما اعطا کند. برای اطلاعات بیشتر در مورد اعطای نقشها، به مدیریت دسترسی به پروژهها، پوشهها و سازمانها مراجعه کنید.همچنین ممکن است بتوانید مجوزهای لازم را از طریق نقشهای سفارشی یا سایر نقشهای از پیش تعریف شده دریافت کنید.
ایجاد کاربر و اتصال به پایگاه داده
برای ایجاد یک کاربر برای Cloud Firestore خود با پایگاه داده سازگار با MongoDB، از یکی از روشهای زیر استفاده کنید:
کنسول گوگل کلود
در کنسول گوگل کلود، به صفحه پایگاههای داده بروید.
- یک پایگاه داده از لیست پایگاههای داده انتخاب کنید.
- در منوی پیمایش، روی «تأیید» کلیک کنید.
- روی افزودن کاربر کلیک کنید.
- یک نام کاربری وارد کنید.
- یک نقش برای کاربر جدید انتخاب کنید.
- روی افزودن کلیک کنید.
رمز عبور کاربر جدید در کادر محاورهای تأیید نمایش داده خواهد شد.
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 با استفاده از کتابخانههای کلاینت مدیریتی جاوا ارائه میدهد. این نمونه از کتابخانه 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 که شامل پایگاه داده شما است، ایجاد کنید.
قبل از اینکه شروع کنی
- برای پیکربندی حساب سرویس برای Cloud Run ، به پیکربندی هویت سرویس مراجعه کنید.
- برای تعیین حساب سرویسی که از قبل با سرویس Cloud Run شما مرتبط است، به بخش «توضیحات سرویسهای gcloud run» مراجعه کنید.
برای تکمیل پیکربندی خطمشی 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 : شناسه پایگاه داده