Yalnızca Cloud Firestore Enterprise sürümü için geçerlidir. |
Bağlantı koşulları
MongoDB uyumlu Cloud Firestore istemcileri için aşağıdakiler gereklidir:
- Sürücüler
load balanced
modunda bağlanmalıdır. Bu, sürücülerin bağlandıkları sunucunun tam topolojisini anlamaya çalışmasını engeller. - Sürücüler, SSL etkinleştirilmiş olarak bağlanmalıdır.
- Sürücüler, yeniden denenebilir yazma işlemlerini devre dışı bırakmalıdır. MongoDB uyumlu Cloud Firestore, yeniden denenebilir yazma işlemlerini desteklemez. Yeniden denenebilir okumalar desteklendiğinden bunları devre dışı bırakmanız gerekmez.
Bağlantı dizesini alma
Veritabanı bağlantı dizesi, veritabanının UID'sine, veritabanının konumuna ve kimlik doğrulama mekanizmasına bağlıdır. Aşağıdaki talimatlarda bağlantı dizesinin nasıl oluşturulduğu açıklanmaktadır.
Tam bağlantı dizesi, kimlik doğrulama mekanizmasına bağlıdır. Ancak temel bağlantı dizesi aşağıdaki biçimi kullanır:
mongodb://UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&tls=true&retryWrites=false
Temel bağlantı dizesini aşağıdaki yöntemlerden biriyle edinebilirsiniz:
Firebase konsolu
-
Firebase konsolunda Firestore Database sayfasına gidin.
- Kimliğini doğrulamak istediğiniz veritabanını tıklayın.
- Gezgin panelinde Daha fazla göster'i tıklayın.
- MongoDB araçlarını kullanarak bağlan'ı seçin.
- Bağlantı dizesini kopyalayın.
gcloud
UID ve konum bilgilerini almak için gcloud firestore database describe
öğesini kullanın:
gcloud firestore databases describe \ --database=DATABASE_ID \ --format='yaml(locationId, uid)'
DATABASE_ID yerine veritabanı kimliğini yazın.
Çıkış, veritabanının konumunu ve UID'sini içerir. Temel bağlantı dizesini oluşturmak için bu bilgileri kullanın.
Kimlik doğrulamak ve veritabanınıza bağlanmak için temel bağlantı dizesini ve aşağıdaki yöntemlerden birini kullanın:
- Kullanıcı adı ve şifre (SCRAM)
- Compute Engine hizmet hesabı
- Cloud Run hizmet hesabı
- Google Auth Library
Kullanıcı adı ve şifreyle (SCRAM) bağlanma
Veritabanınız için kullanıcı kimliği oluşturmak ve veritabanınıza bağlanmak üzere aşağıdaki adımları uygulayın.
Başlamadan önce
Kullanıcı oluşturmak için gereken izinleri almak üzere yöneticinizden veritabanınızda userCredsAdmin (roles/datastore.userCredsAdmin
) IAM rolünü vermesini isteyin. Rol verme hakkında daha fazla bilgi için Projelere, klasörlere ve kuruluşlara erişimi yönetme başlıklı makaleyi inceleyin.
Gerekli izinleri özel roller veya diğer önceden tanımlanmış roller aracılığıyla da alabilirsiniz.
Kullanıcı oluşturma ve veritabanına bağlanma
MongoDB uyumlu Cloud Firestore veritabanınız için kullanıcı oluşturmak üzere aşağıdaki yöntemlerden birini kullanın:
Google Cloud konsolu
-
Google Cloud Console'da Veritabanları sayfasına gidin.
- Veritabanları listesinden bir veritabanı seçin.
- Gezinme menüsünde Auth'u (Kimlik Doğrulama) tıklayın.
- Kullanıcı Ekle'yi tıklayın.
- Bir kullanıcı adı girin.
- Yeni kullanıcı için bir rol seçin.
-
Ekle'yi tıklayın.
Yeni kullanıcının şifresi onay iletişim kutusunda gösterilir.
gcloud CLI
-
SCRAM ile kimlik doğrulaması yapmak için
önce bir kullanıcı kimlik bilgisi oluşturmanız gerekir. Şu komutu kullanın:
gcloud firestore user-creds
Aşağıdakileri değiştirin:gcloud firestore user-creds create USERNAME --database=DATABASE_ID
- USERNAME: Oluşturulacak kullanıcı adı.
- DATABASE_ID: Veritabanı kimliği.
Bu komutun çıktısı, kullanıcının şifresini içerir.
Çıkış şu şekilde görünür:
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
-
Varsayılan olarak, bu yeni kullanıcı kimlik bilgilerinin herhangi bir izni yoktur. Veritabanına okuma ve yazma erişimi için bu veritabanına
roles/datastore.user
rolünü ekleyin: Aşağıdakileri değiştirin: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: Projenizin adı.
- PROJECT_NUMBER: Proje numarası.
- DATABASE_ID: Veritabanı kimliği.
- USERNAME: Daha önce oluşturduğunuz kullanıcı adı.
- CONDITION_TITLE: Bu koşul için bir başlık. Bu koşul, erişimi yalnızca bu veritabanıyla kısıtlar.
Java
Bu bölümde, Java yönetim istemci kitaplıklarını kullanarak kullanıcı kimlik bilgileri oluşturma ve IAM politikasını yapılandırma ile ilgili bir kod örneği verilmektedir. Örnekte, kullanıcı adı ve şifre oluşturmak için Firestore Admin Client kitaplığı, IAM'yi yapılandırmak için ise Google Cloud Resource Manager kitaplığı kullanılmaktadır.
Maven derlemeleri için aşağıdaki koordinatları kullanabilirsiniz:
com.google.cloud:google-cloud-firestore-admin:3.33.1 com.google.cloud:google-cloud-resourcemanager:1.76.0
Kullanıcı kimlik bilgilerini ve bir IAM politikasını sağlama:
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
Bu bölümde, Python yönetim istemci kitaplıklarını kullanarak kullanıcı kimlik bilgileri oluşturma ve IAM politikasını yapılandırma ile ilgili bir kod örneği verilmektedir. Örnekte, kullanıcı adı ve şifre oluşturmak için Google Cloud Firestore API istemci kitaplığı, IAM'yi yapılandırmak için ise Google Cloud IAM API istemci kitaplığı ve Google Cloud Resource Manager API istemci kitaplığı kullanılır.
Gerekli Python kitaplıkları pip aracıyla yüklenebilir:
pip install google-cloud-iam pip install google-cloud-firestore pip install google-cloud-resource-manager
Kullanıcı kimlik bilgilerini ve bir IAM politikasını sağlama:
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 ile veritabanınıza bağlanmak için aşağıdaki bağlantı dizesini kullanın:
mongodb://USERNAME:PASSWORD@UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&authMechanism=SCRAM-SHA-256&tls=true&retryWrites=false
Aşağıdakini değiştirin:
- USERNAME: Kullanıcı adı.
- PASSWORD: Bu kullanıcı için oluşturduğunuz şifre.
- UID: Veritabanının UID'si.
- LOCATION: Veritabanının konumu.
- DATABASE_ID: Veritabanı kimliği.
Google Auth Library ile bağlantı kurma
Aşağıdaki kod örneği, Google Cloud standart OAuth kitaplığını kullanarak bir OIDC geri çağırma işleyicisi kaydeder.
Bu kitaplık, çeşitli kimlik doğrulama türlerini (Uygulama Varsayılan Kimlik Bilgileri, Workload Identity Federation) kullanmanıza olanak tanır.
Bunun için kimlik doğrulama kitaplığının bağımlı kaynak olarak eklenmesi gerekir:
// 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'
Aşağıdaki kod örneğinde nasıl bağlanılacağı gösterilmektedir:
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); }
Aşağıdakini değiştirin:
- DATABASE_UID: Projenizin adı.
- LOCATION: Veritabanınızın konumu.
- DATABASE_ID veritabanı kimliği.
Google Cloud işlem ortamından bağlanma
Bu bölümde, Google Cloud bilgi işlem ortamından (ör. Compute Engine) veya Cloud Run hizmetinden ya da işinden MongoDB uyumlu Cloud Firestore'a bağlanma açıklanmaktadır.
Compute Engine sanal makinesinden bağlanma
Compute Engine hizmet hesabı kullanarak veritabanınızda kimlik doğrulaması yapabilir ve veritabanınıza bağlanabilirsiniz. Bunu yapmak için veritabanınızı içeren Google Cloud projesi için bir IAM politikası oluşturun.
Başlamadan önce
Sanal makineniz için kullanıcı tarafından yönetilen bir hizmet hesabı yapılandırın:
- Sanal makine oluşturma sırasında hizmet hesabını yapılandırmak için Kullanıcı tarafından yönetilen hizmet hesabı kullanan bir sanal makine oluşturma başlıklı makaleyi inceleyin.
- Mevcut bir VM'de hizmet hesabı yapılandırmak için Ekli hizmet hesabını değiştirme başlıklı makaleyi inceleyin.
Compute Engine hizmet hesabınız için IAM politikası yapılandırmasını tamamlamak üzere Kimlik bilgilerini yapılandırma bölümündeki talimatları uygulayın.
Cloud Run fiyattan bağlantılı uçuş
Cloud Run hizmet hesabı kullanarak veritabanınızda kimlik doğrulaması yapabilir ve veritabanınıza bağlanabilirsiniz. Bunu yapmak için veritabanınızı içeren Google Cloud projesi için bir IAM politikası oluşturun.
Başlamadan önce
- Cloud Run için hizmet hesabını yapılandırmak üzere Hizmet kimliğini yapılandırma başlıklı makaleye bakın.
- Cloud Run hizmetinizle zaten ilişkilendirilmiş olan hizmet hesabını belirlemek için gcloud run services describe komutuna bakın.
Cloud Run hizmet hesabınız için IAM politikası yapılandırmasını tamamlamak üzere Kimlik bilgilerini yapılandırma bölümündeki talimatları uygulayın.
Kimlik bilgilerini yapılandırma
Hizmet hesabına roles/datastore.user
rolünü vererek Cloud Firestore'e okuma ve yazma izni vermek için aşağıdaki komutu çalıştırın:
gcloud projects add-iam-policy-binding PROJECT_NAME --member="SERVICE_ACCOUNT_EMAIL" --role=roles/datastore.user
Aşağıdakini değiştirin:
- PROJECT_NAME: Projenizin adı.
- SERVICE_ACCOUNT_EMAIL: Oluşturduğunuz hizmet hesabının e-posta adresi.
Bağlantı dizesini oluşturma
Bağlantı dizesini oluşturmak için aşağıdaki biçimi kullanın:
mongodb://DATABASE_UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&tls=true&retryWrites=false&authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:FIRESTORE
Aşağıdakini değiştirin:
- DATABASE_UID: Projenizin adı.
- LOCATION: Veritabanınızın konumu.
- DATABASE_ID veritabanı kimliği.
UID ve konumun alınması hakkında daha fazla bilgi için Bağlantı dizesini alma başlıklı makaleyi inceleyin.
Geçici erişim jetonuyla bağlanma
Google Cloud gibi teşhis araçlarını çalıştırmak için geçici bir erişim jetonu kullanabilirsiniz.mongosh
Kısa süreli erişim jetonuyla kimlik doğrulamak için
gcloud auth print-access-token
kullanabilirsiniz. Bu jeton bir saat boyunca geçerlidir.
Örneğin, mongosh
ile veritabanınıza bağlanmak için aşağıdaki komutu kullanın:
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'
Aşağıdakini değiştirin:
- DATABASE_UID: Veritabanının UID'si
- LOCATION: veritabanı konumu
- DATABASE_ID: veritabanı kimliği