Wymagania dotyczące połączenia
W przypadku klientów Cloud Firestore wymagane są te elementy:
- Kierowcy muszą łączyć się w trybie
load balanced. Dzięki temu sterowniki nie muszą próbować zrozumieć dokładnej topologii serwera, z którym się łączą. - Sterowniki muszą łączyć się z włączonym protokołem SSL.
- Sterowniki muszą wyłączyć zapisy z możliwością ponowienia. Cloud Firestore nie obsługuje ponownych prób zapisu. Nie musisz wyłączać odczytów z możliwością ponowienia, ponieważ są one obsługiwane.
Pobieranie ciągu znaków połączenia
Ciąg znaków połączenia z bazą danych zależy od identyfikatora UID bazy danych, jej lokalizacji i mechanizmu uwierzytelniania. Poniższe instrukcje opisują, jak tworzony jest ciąg znaków połączenia.
Dokładny ciąg znaków połączenia zależy od mechanizmu uwierzytelniania, ale podstawowy ciąg znaków połączenia ma ten format:
mongodb://UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&tls=true&retryWrites=false
Podstawowy ciąg znaków połączenia możesz uzyskać na jeden z tych sposobów:
Konsola Firebase
-
W konsoli Firebase otwórz stronę Baza danych Firestore.
- Kliknij bazę danych, którą chcesz uwierzytelnić.
- W panelu Eksplorator kliknij Wyświetl więcej.
- Wybierz Połącz za pomocą narzędzi MongoDB.
- Skopiuj ciąg znaków połączenia.
gcloud
Użyj gcloud firestore database describe, aby pobrać identyfikator UID i informacje o lokalizacji:
gcloud firestore databases describe \ --database=DATABASE_ID \ --format='yaml(locationId, uid)'
Zastąp DATABASE_ID identyfikatorem bazy danych.
Dane wyjściowe zawierają lokalizację i identyfikator UID bazy danych. Użyj tych informacji, aby utworzyć podstawowy ciąg znaków połączenia.
Użyj podstawowego ciągu znaków połączenia i jednej z tych metod, aby uwierzytelnić się i połączyć z bazą danych:
- Nazwa użytkownika i hasło (SCRAM)
- Konto usługi Compute Engine
- Konto usługi Cloud Run
- Biblioteka Google Auth
Łączenie przy użyciu nazwy użytkownika i hasła (SCRAM)
Aby utworzyć dane logowania użytkownika do bazy danych i połączyć się z nią, wykonaj te czynności.
Zanim zaczniesz
Aby uzyskać uprawnienia niezbędne do utworzenia użytkownika, poproś administratora o przypisanie Ci roli uprawnień userCredsAdmin (roles/datastore.userCredsAdmin) w bazie danych. Więcej informacji o przyznawaniu ról znajdziesz w artykule o zarządzaniu dostępem do projektów, folderów i organizacji.
Wymagane uprawnienia możesz też uzyskać, używając ról niestandardowych lub innych ról zdefiniowanych.
Tworzenie użytkownika i łączenie się z bazą danych
Aby utworzyć użytkownika bazy danych Cloud Firestore, użyj jednej z tych metod:
Konsola Firebase
W konsoli Firebase otwórz stronę Baza danych Firestore.
- Wybierz bazę danych z listy baz danych.
- W menu nawigacyjnym kliknij Zabezpieczenia.
- Kliknij Add User (Dodaj użytkownika).
- Wpisz nazwę użytkownika.
- Wybierz rolę dla nowego użytkownika.
- Kliknij Dodaj użytkownika.
Hasło nowego użytkownika zostanie wyświetlone w oknie potwierdzenia.
gcloud CLI
-
Aby uwierzytelniać za pomocą SCRAM, musisz najpierw utworzyć dane logowania użytkownika. Użyj polecenia
gcloud firestore user-creds: Zastąp te elementy:gcloud firestore user-creds create USERNAME --database=DATABASE_ID
- USERNAME: nazwa użytkownika, którą chcesz utworzyć.
- DATABASE_ID: identyfikator bazy danych.
Wynik tego polecenia zawiera hasło użytkownika.
Dane wyjściowe będą wyglądać mniej więcej tak:
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
-
Domyślnie te nowe dane logowania użytkownika nie mają żadnych uprawnień. Aby uzyskać dostęp do bazy danych z uprawnieniami do odczytu i zapisu, dodaj rolę
roles/datastore.userdla tej konkretnej bazy danych: Zastąp te elementy: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: nazwa projektu.
- PROJECT_NUMBER: numer projektu.
- DATABASE_ID: identyfikator bazy danych.
- USERNAME: utworzona wcześniej nazwa użytkownika.
- CONDITION_TITLE: tytuł tego warunku. Ten warunek ogranicza dostęp tylko do tej bazy danych.
Java
W tej sekcji znajdziesz przykładowy kod do tworzenia danych logowania użytkownika i konfigurowania zasad uprawnień przy użyciu bibliotek klienta administracyjnego w języku Java. Przykładowy kod używa biblioteki Firestore Admin Client do utworzenia nazwy użytkownika i hasła oraz biblioteki Google Cloud Resource Manager do skonfigurowania uprawnień.
W przypadku kompilacji Maven możesz użyć tych współrzędnych:
com.google.cloud:google-cloud-firestore-admin:3.33.1 com.google.cloud:google-cloud-resourcemanager:1.76.0
Udostępnij dane logowania użytkownika i zasadę uprawnień:
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
W tej sekcji znajdziesz przykładowy kod do tworzenia danych logowania użytkownika i konfigurowania zasad uprawnień za pomocą bibliotek klienta administracyjnego w Pythonie. W przykładzie użyto biblioteki klienta Google Cloud Firestore API do utworzenia nazwy użytkownika i hasła oraz biblioteki klienta Google Cloud IAM API i biblioteki klienta Google Cloud Resource Manager API do skonfigurowania uprawnień.
Wymagane biblioteki Pythona można zainstalować za pomocą narzędzia pip:
pip install google-cloud-iam pip install google-cloud-firestore pip install google-cloud-resource-manager
Udostępnij dane logowania użytkownika i zasadę uprawnień:
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}]')
Aby połączyć się z bazą danych za pomocą SCRAM, użyj tego ciągu znaków połączenia:
mongodb://USERNAME:PASSWORD@UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&authMechanism=SCRAM-SHA-256&tls=true&retryWrites=false
Zastąp następujące elementy:
- USERNAME: nazwa użytkownika.
- PASSWORD: hasło wygenerowane dla tego użytkownika.
- UID: identyfikator UID bazy danych. Na przykład: f116f93a-519c-208a-9a72-3ef6c9a1f081
- LOCATION: lokalizacja bazy danych.
- DATABASE_ID: identyfikator bazy danych.
Łączenie się z biblioteką Google Auth Library
Poniższy przykładowy kod rejestruje moduł obsługi wywołania zwrotnego OIDC, który korzysta ze Google Cloud standardowej biblioteki OAuth.
Ta biblioteka umożliwia korzystanie z różnych typów uwierzytelniania (domyślne uwierzytelnianie aplikacji, federacja tożsamości zadań).
Wymaga to dodania biblioteki uwierzytelniania jako zależności:
// 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'
Poniższy przykładowy kod pokazuje, jak się połączyć:
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); }
Zastąp następujące elementy:
- DATABASE_UID: identyfikator UID bazy danych. Na przykład: f116f93a-519c-208a-9a72-3ef6c9a1f081
- LOCATION: lokalizacja bazy danych.
- DATABASE_ID identyfikator bazy danych.
Nawiązywanie połączenia ze środowiska obliczeniowego Google Cloud
W tej sekcji opisano nawiązywanie połączenia z Cloud Firestore ze środowiska obliczeniowego Google Cloud, takiego jak Compute Engine lub usługa bądź zadanie Cloud Run.
Połączenie z maszyny wirtualnej Compute Engine
Możesz uwierzytelnić się i połączyć z bazą danych za pomocą konta usługi Compute Engine. Aby to zrobić, utwórz zasadę uprawnień dla projektu Google Cloud, który zawiera Twoją bazę danych.
Zanim zaczniesz
Skonfiguruj konto usługi zarządzane przez użytkownika dla maszyny wirtualnej:
- Aby dowiedzieć się, jak skonfigurować konto usługi podczas tworzenia maszyny wirtualnej, zapoznaj się z artykułem Tworzenie maszyny wirtualnej, która korzysta z konta usługi zarządzanego przez użytkownika.
- Aby skonfigurować konto usługi na istniejącej maszynie wirtualnej, zapoznaj się z artykułem Zmienianie dołączonego konta usługi.
Aby dokończyć konfigurowanie zasad uprawnień dla konta usługi Compute Engine, postępuj zgodnie z instrukcjami w sekcjach Konfigurowanie danych logowania.
Połącz z: Cloud Run
Możesz uwierzytelnić się i połączyć z bazą danych za pomocą konta usługi Cloud Run. Aby to zrobić, utwórz zasadę uprawnień dla projektu Google Cloud, który zawiera Twoją bazę danych.
Zanim zaczniesz
- Aby skonfigurować konto usługi dla Cloud Run, zapoznaj się z artykułem Konfigurowanie tożsamości usługi.
- Aby określić konto usługi, które jest już powiązane z usługą Cloud Run, zapoznaj się z artykułem gcloud run services describe.
Aby dokończyć konfigurowanie zasad uprawnień dla konta usługi Cloud Run, postępuj zgodnie z instrukcjami w sekcjach Konfigurowanie danych logowania.
Konfigurowanie danych logowania
Aby przyznać kontu usługi rolę roles/datastore.user z uprawnieniami do odczytu i zapisu w Cloud Firestore, uruchom to polecenie:
gcloud projects add-iam-policy-binding PROJECT_NAME --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" --role=roles/datastore.user
Zastąp następujące elementy:
- PROJECT_NAME: nazwa projektu.
- SERVICE_ACCOUNT_EMAIL: adres e-mail utworzonego przez Ciebie konta usługi.
Tworzenie ciągu znaków połączenia
Aby utworzyć ciąg znaków połączenia, użyj tego formatu:
mongodb://DATABASE_UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&tls=true&retryWrites=false&authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:FIRESTORE
Zastąp następujące elementy:
- DATABASE_UID: identyfikator UID bazy danych. Na przykład: f116f93a-519c-208a-9a72-3ef6c9a1f081
- LOCATION: lokalizacja bazy danych.
- DATABASE_ID identyfikator bazy danych.
Więcej informacji o pobieraniu identyfikatora UID i lokalizacji znajdziesz w artykule Pobieranie ciągu znaków połączenia.
Łączenie za pomocą tymczasowego tokena dostępu
Możesz użyć tymczasowego tokena dostępu Google Cloud, aby uruchomić narzędzia diagnostyczne, takie jak mongosh. Możesz użyć gcloud auth
print-access-token, aby uwierzytelnić się za pomocą krótkoterminowego tokena dostępu. Ten token jest ważny przez godzinę.
Aby na przykład połączyć się z bazą danych za pomocą mongosh, użyj tego polecenia:
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'
Zastąp następujące elementy:
- DATABASE_UID: identyfikator UID bazy danych. Na przykład: f116f93a-519c-208a-9a72-3ef6c9a1f081
- LOCATION: lokalizacja bazy danych.
- DATABASE_ID: identyfikator bazy danych,