Dans ce guide de démarrage rapide, vous allez découvrir comment configurer Firestore, ajouter des données et les lire à l'aide de la bibliothèque cliente du serveur C#, Go, Java, Node.js, PHP, Python ou Ruby.
Avant de commencer
- Connectez-vous à votre compte Google.
Si vous n'en possédez pas déjà un, vous devez en créer un.
-
Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.
Créer une base de données Firestore en mode natif
S'il s'agit d'un nouveau projet, vous devez créer une instance de base de données Firestore.
Dans l'écran Sélectionner un service de base de données, sélectionnez Firestore en mode natif.
Sélectionnez un emplacement pour votre Firestore.
Ce paramètre d'emplacement correspond à l'emplacement par défaut des ressources Google Cloud Platform (GCP) pour le projet. Cet emplacement sera utilisée pour les services GCP exploités dans le projet qui requièrent un paramètre d'emplacement, plus précisément le bucket Cloud Storage par défaut et l'application App Engine (qui est nécessaire si vous utilisez Cloud Scheduler).
Cliquez sur Créer une base de données.
Lorsque vous créez un projet Firestore, cela active également l'API dans le Cloud API Manager.
Configurer l'authentification
Pour exécuter la bibliothèque cliente, vous devez d'abord configurer l'authentification en créant un compte de service et en définissant une variable d'environnement.
Cloud Console
-
Dans Cloud Console, accédez à la page Créer une clé de compte de service.
Accéder à la page "Créer une clé de compte de service" - Dans la liste Compte de service, sélectionnez Nouveau compte de service.
- Dans le champ Nom du compte de service, saisissez un nom.
Dans la liste Rôle, sélectionnez Projet > Propriétaire
- Cliquez sur Créer. Un fichier JSON contenant votre clé est téléchargé sur votre ordinateur.
Ligne de commande
Vous pouvez exécuter les commandes suivantes à l'aide du SDK Cloud sur votre ordinateur local, ou dans Cloud Shell.
-
Créez le compte de service. Remplacez NAME par le nom que vous souhaitez donner au compte de service.
gcloud iam service-accounts create NAME
-
Accordez des autorisations au compte de service. Remplacez PROJECT_ID par votre ID de projet.
gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role="roles/owner"
-
Générez le fichier de clé. Remplacez FILE_NAME par le nom du fichier de clé.
gcloud iam service-accounts keys create FILE_NAME.json --iam-account=NAME@PROJECT_ID.iam.gserviceaccount.com
Fournissez des identifiants d'authentification au code de votre application en définissant la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS
.
Remplacez [PATH] par le chemin du fichier JSON contenant la clé de votre compte de service. Cette variable ne s'applique qu'à la session d'interface système actuelle. Par conséquent, si vous ouvrez une nouvelle session, vous devez la définir à nouveau.
Linux ou macOS
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
Exemple :
export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/my-key.json"
Windows
Avec PowerShell :
$env:GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
Exemple :
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\my-key.json"
Avec l'invite de commande :
set GOOGLE_APPLICATION_CREDENTIALS=[PATH]
Ajouter la bibliothèque cliente du serveur à votre application
Ajoutez les dépendances et les bibliothèques clientes requises à votre application.
Java
Ajoutez la bibliothèque Java Firestore à votre application :
-
Avec Gradle :
compile 'com.google.cloud:google-cloud-firestore:1.32.0'
-
Avec Maven :
<dependencyManagement> <dependencies> <dependency> <groupId>com.google.cloud</groupId> <artifactId>libraries-bom</artifactId> <version>16.3.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>com.google.cloud</groupId> <artifactId>google-cloud-firestore</artifactId> </dependency>
-
Avec un IDE :
Si vous utilisez IntelliJ ou Eclipse, vous pouvez ajouter des bibliothèques clientes à votre projet à l'aide de ces plug-ins pour IDE :
Les plug-ins offrent des fonctionnalités supplémentaires, telles que la gestion des clés pour les comptes de service. Reportez-vous à la documentation de chaque plug-in pour plus de détails.
Python
Ajoutez la bibliothèque Python Firestore à votre application :
pip install --upgrade google-cloud-firestore
Node.js
Ajoutez la bibliothèque Node.js Firestore à votre application :
npm install --save @google-cloud/firestore
Go
Installez la bibliothèque Go Firestore :
go get cloud.google.com/go/firestore
Ajoutez la bibliothèque Go Firestore à votre application :
import "cloud.google.com/go/firestore"
PHP
- Installez et activez l'extension gRPC pour PHP. Vous en aurez besoin pour utiliser la bibliothèque cliente.
-
Ajoutez la bibliothèque PHP Firestore à votre application :
composer require google/cloud-firestore
C#
-
Ajoutez la bibliothèque C# Firestore à votre application dans le fichier
.csproj
:<ItemGroup> <PackageReference Include="Google.Cloud.Firestore" Version="1.1.0-beta01" /> </ItemGroup>
- Ajoutez le code ci-dessous à votre fichier
Program.cs
:using Google.Cloud.Firestore;
Ruby
-
Ajoutez la bibliothèque Ruby Firestore à votre application dans le
Gemfile
:gem "google-cloud-firestore"
-
Installez les dépendances du
Gemfile
avec la commande :bundle install
Initialiser Firestore
Initialiser une instance de Firestore :
Java
import com.google.cloud.firestore.Firestore; import com.google.cloud.firestore.FirestoreOptions; FirestoreOptions firestoreOptions = FirestoreOptions.getDefaultInstance().toBuilder() .setProjectId(projectId) .setCredentials(GoogleCredentials.getApplicationDefault()) .build(); Firestore db = firestoreOptions.getService();
Python
from google.cloud import firestore # Project ID is determined by the GCLOUD_PROJECT environment variable db = firestore.Client()
Node.js
const Firestore = require('@google-cloud/firestore'); const db = new Firestore({ projectId: 'YOUR_PROJECT_ID', keyFilename: '/path/to/keyfile.json', });
Go
import ( "context" "fmt" "log" "google.golang.org/api/iterator" "cloud.google.com/go/firestore" ) func createClient(ctx context.Context) *firestore.Client { // Sets your Google Cloud Platform project ID. projectID := "YOUR_PROJECT_ID" client, err := firestore.NewClient(ctx, projectID) if err != nil { log.Fatalf("Failed to create client: %v", err) } // Close client when done with // defer client.Close() return client }
PHP
use Google\Cloud\Firestore\FirestoreClient; /** * Initialize Cloud Firestore with default project ID. * ``` * initialize(); * ``` */ function initialize() { // Create the Cloud Firestore client $db = new FirestoreClient(); printf('Created Cloud Firestore client with default project ID.' . PHP_EOL); }
C#
FirestoreDb db = FirestoreDb.Create(project); Console.WriteLine("Created Cloud Firestore client with project ID: {0}", project);
Ruby
require "google/cloud/firestore" firestore = Google::Cloud::Firestore.new project_id: project_id puts "Created Cloud Firestore client with given project ID."
Ajouter des données
Firestore stocke les données dans des documents, qui sont eux-mêmes stockés dans des collections. Firestore crée implicitement les collections et les documents nécessaires la première fois qu’une donnée est ajoutée à un document. Vous n'avez pas besoin de créer explicitement les collections ni les documents.
Créez une collection et un document à l'aide de l'exemple de code ci-dessous.
Java
DocumentReference docRef = db.collection("users").document("alovelace"); // Add document data with id "alovelace" using a hashmap Map<String, Object> data = new HashMap<>(); data.put("first", "Ada"); data.put("last", "Lovelace"); data.put("born", 1815); //asynchronously write data ApiFuture<WriteResult> result = docRef.set(data); // ... // result.get() blocks on response System.out.println("Update time : " + result.get().getUpdateTime());
Python
doc_ref = db.collection(u'users').document(u'alovelace') doc_ref.set({ u'first': u'Ada', u'last': u'Lovelace', u'born': 1815 })
Node.js
const docRef = db.collection('users').doc('alovelace'); await docRef.set({ first: 'Ada', last: 'Lovelace', born: 1815 });
Go
_, _, err := client.Collection("users").Add(ctx, map[string]interface{}{ "first": "Ada", "last": "Lovelace", "born": 1815, }) if err != nil { log.Fatalf("Failed adding alovelace: %v", err) }
PHP
$docRef = $db->collection('users')->document('lovelace'); $docRef->set([ 'first' => 'Ada', 'last' => 'Lovelace', 'born' => 1815 ]); printf('Added data to the lovelace document in the users collection.' . PHP_EOL);
C#
DocumentReference docRef = db.Collection("users").Document("alovelace"); Dictionary<string, object> user = new Dictionary<string, object> { { "First", "Ada" }, { "Last", "Lovelace" }, { "Born", 1815 } }; await docRef.SetAsync(user);
Ruby
doc_ref = firestore.doc "#{collection_path}/alovelace" doc_ref.set( first: "Ada", last: "Lovelace", born: 1815 ) puts "Added data to the alovelace document in the users collection."
À présent, ajoutez un autre document à la collection users
. Notez que ce document contient une paire clé-valeur (deuxième prénom) qui n'est pas présente dans le premier document. Les documents d'une collection peuvent contenir différents ensembles d'informations.
Java
DocumentReference docRef = db.collection("users").document("aturing"); // Add document data with an additional field ("middle") Map<String, Object> data = new HashMap<>(); data.put("first", "Alan"); data.put("middle", "Mathison"); data.put("last", "Turing"); data.put("born", 1912); ApiFuture<WriteResult> result = docRef.set(data); System.out.println("Update time : " + result.get().getUpdateTime());
Python
doc_ref = db.collection(u'users').document(u'aturing') doc_ref.set({ u'first': u'Alan', u'middle': u'Mathison', u'last': u'Turing', u'born': 1912 })
Node.js
const aTuringRef = db.collection('users').doc('aturing'); await aTuringRef.set({ 'first': 'Alan', 'middle': 'Mathison', 'last': 'Turing', 'born': 1912 });
Go
_, _, err = client.Collection("users").Add(ctx, map[string]interface{}{ "first": "Alan", "middle": "Mathison", "last": "Turing", "born": 1912, }) if err != nil { log.Fatalf("Failed adding aturing: %v", err) }
PHP
$docRef = $db->collection('users')->document('aturing'); $docRef->set([ 'first' => 'Alan', 'middle' => 'Mathison', 'last' => 'Turing', 'born' => 1912 ]); printf('Added data to the aturing document in the users collection.' . PHP_EOL);
C#
DocumentReference docRef = db.Collection("users").Document("aturing"); Dictionary<string, object> user = new Dictionary<string, object> { { "First", "Alan" }, { "Middle", "Mathison" }, { "Last", "Turing" }, { "Born", 1912 } }; await docRef.SetAsync(user);
Ruby
doc_ref = firestore.doc "#{collection_path}/aturing" doc_ref.set( first: "Alan", middle: "Mathison", last: "Turing", born: 1912 ) puts "Added data to the aturing document in the users collection."
Lire des données
Pour vérifier rapidement que vous avez bien ajouté des données à Firestore, utilisez la visionneuse de données de la console Firebase.
Vous pouvez également utiliser la méthode get
pour récupérer l'ensemble de la collection.
Java
// asynchronously retrieve all users ApiFuture<QuerySnapshot> query = db.collection("users").get(); // ... // query.get() blocks on response QuerySnapshot querySnapshot = query.get(); List<QueryDocumentSnapshot> documents = querySnapshot.getDocuments(); for (QueryDocumentSnapshot document : documents) { System.out.println("User: " + document.getId()); System.out.println("First: " + document.getString("first")); if (document.contains("middle")) { System.out.println("Middle: " + document.getString("middle")); } System.out.println("Last: " + document.getString("last")); System.out.println("Born: " + document.getLong("born")); }
Python
users_ref = db.collection(u'users') docs = users_ref.stream() for doc in docs: print(f'{doc.id} => {doc.to_dict()}')
Node.js
const snapshot = await db.collection('users').get(); snapshot.forEach((doc) => { console.log(doc.id, '=>', doc.data()); });
Go
iter := client.Collection("users").Documents(ctx) for { doc, err := iter.Next() if err == iterator.Done { break } if err != nil { log.Fatalf("Failed to iterate: %v", err) } fmt.Println(doc.Data()) }
PHP
$usersRef = $db->collection('users'); $snapshot = $usersRef->documents(); foreach ($snapshot as $user) { printf('User: %s' . PHP_EOL, $user->id()); printf('First: %s' . PHP_EOL, $user['first']); if (!empty($user['middle'])) { printf('Middle: %s' . PHP_EOL, $user['middle']); } printf('Last: %s' . PHP_EOL, $user['last']); printf('Born: %d' . PHP_EOL, $user['born']); printf(PHP_EOL); } printf('Retrieved and printed out all documents from the users collection.' . PHP_EOL);
C#
CollectionReference usersRef = db.Collection("users"); QuerySnapshot snapshot = await usersRef.GetSnapshotAsync(); foreach (DocumentSnapshot document in snapshot.Documents) { Console.WriteLine("User: {0}", document.Id); Dictionary<string, object> documentDictionary = document.ToDictionary(); Console.WriteLine("First: {0}", documentDictionary["First"]); if (documentDictionary.ContainsKey("Middle")) { Console.WriteLine("Middle: {0}", documentDictionary["Middle"]); } Console.WriteLine("Last: {0}", documentDictionary["Last"]); Console.WriteLine("Born: {0}", documentDictionary["Born"]); Console.WriteLine(); }
Ruby
users_ref = firestore.col collection_path users_ref.get do |user| puts "#{user.document_id} data: #{user.data}." end
Étapes suivantes
Approfondissez vos connaissances sur les sujets suivants :
- Modèle de données : apprenez comment les données sont structurées dans Firestore, y compris les données hiérarchiques et les sous-collections.
- Ajouter des données : en savoir plus sur la création et la mise à jour de données dans Firestore.
- Obtenir des données : en savoir plus sur la récupération des données.
- Lancer des requêtes simples et des requêtes composées : en savoir plus sur l’exécution des requêtes simples et composées.
- Tris et limites dans les requêtes : découvrez comment trier et limiter les données renvoyées par les requêtes.