Se connecter à des bases de données entièrement gérées depuis Cloud Run

1. Présentation

Dans cet atelier, vous allez intégrer des bases de données sans serveur(Spanner et Firestore) à des applications(Go et Node.js) exécutées dans Cloud Run. L'application Cymbal Eats inclut plusieurs services qui s'exécutent sur Cloud Run. Dans les étapes suivantes, vous allez configurer des services pour utiliser la base de données relationnelle Cloud Spanner et Cloud Firestore, une base de données de documents NoSQL. L'utilisation de produits sans serveur pour le niveau de données et l'environnement d'exécution des applications vous permet d'éliminer toute la gestion de l'infrastructure et de vous concentrer sur la création de votre application sans avoir à vous soucier des frais généraux.

2. Objectifs de l'atelier

Dans cet atelier, vous allez apprendre à effectuer les tâches suivantes :

• Intégrer Spanner
• Activer les services gérés Spanner
• Intégrer au code
• Déployer le code se connectant à Spanner
• Intégrer Firestore
• Activer les services gérés Firestore
• Intégrer au code
• Déployer le code se connectant à Firestore

3. Préparation

Configuration de l'environnement d'auto-formation

1. Connectez-vous à la console Google Cloud, puis créez un projet ou réutilisez un projet existant. (Si vous ne possédez pas encore de compte Gmail ou Google Workspace, vous devez en créer un.)

• Le nom du projet est le nom à afficher pour les participants au projet. Il s'agit d'une chaîne de caractères non utilisée par les API Google. Vous pourrez toujours le modifier.
• L'ID du projet est unique parmi tous les projets Google Cloud et non modifiable une fois défini. La console Cloud génère automatiquement une chaîne unique (en général, vous n'y accordez d'importance particulière). Dans la plupart des ateliers de programmation, vous devrez indiquer l'ID de votre projet (généralement identifié par PROJECT_ID). Si l'ID généré ne vous convient pas, vous pouvez en générer un autre de manière aléatoire. Vous pouvez également en spécifier un et voir s'il est disponible. Après cette étape, l'ID n'est plus modifiable et restera donc le même pour toute la durée du projet.
• Pour information, il existe une troisième valeur (le numéro de projet) que certaines API utilisent. Pour en savoir plus sur ces trois valeurs, consultez la documentation.

Attention : Un ID de projet est unique. Une fois que vous l'avez choisi, personne d'autre ne peut l'employer. Vous en êtes le seul utilisateur. Même si un projet est supprimé, son ID ne peut pas être réutilisé.

Remarque : Si vous utilisez un compte Gmail, vous pouvez conserver l'emplacement par défaut défini sur Aucune organisation. Si vous utilisez un compte Google Workspace, choisissez un emplacement qui ait du sens pour votre organisation.

2. Vous devez ensuite activer la facturation dans la console Cloud pour utiliser les ressources/API Cloud. L'exécution de cet atelier de programmation est très peu coûteuse, voire sans frais. Pour désactiver les ressources et éviter ainsi que des frais ne vous soient facturés après ce tutoriel, vous pouvez supprimer le projet ou les ressources que vous avez créées. Les nouveaux utilisateurs de Google Cloud peuvent participer au programme d'essai sans frais pour bénéficier d'un crédit de 300 $.

Configurer l'environnement

1. Créer une variable d'ID de projet

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export SPANNER_INSTANCE=inventory-instance
export SPANNER_DB=inventory-db
export REGION=us-east1
export SPANNER_CONNECTION_STRING=projects/$PROJECT_ID/instances/$SPANNER_INSTANCE/databases/$SPANNER_DB

2. Activer les API Spanner, Cloud Run, Cloud Build et Artifact Registry

gcloud services enable \
     compute.googleapis.com \
     spanner.googleapis.com \
     run.googleapis.com \
     cloudbuild.googleapis.com \
     artifactregistry.googleapis.com \
     firestore.googleapis.com \
     appengine.googleapis.com \
     artifactregistry.googleapis.com

3. Cloner le dépôt

git clone https://github.com/GoogleCloudPlatform/cymbal-eats.git

4. Accéder au répertoire

cd cymbal-eats/inventory-service/spanner

4. Créer et configurer une instance Spanner

Spanner est la base de données relationnelle backend du service d'inventaire. Vous allez créer une instance, une base de données et un schéma Spanner au cours des étapes suivantes.

Créer une instance

1. Créer une instance Cloud Spanner

gcloud spanner instances create $SPANNER_INSTANCE --config=regional-${REGION} \
--description="Cymbal Menu Inventory" --nodes=1

Exemple de résultat

Creating instance...done.   

2. Vérifier si l'instance Spanner est correctement configurée

gcloud spanner instances list

Exemple de résultat :

NAME: inventory-instance
DISPLAY_NAME: Cymbal Menu Inventory
CONFIG: regional-us-east1
NODE_COUNT: 1
PROCESSING_UNITS: 100
STATE: READY

Créer une base de données et un schéma

Créez une base de données et utilisez le langage de définition de données (LDD) du langage SQL standard de Google pour générer le schéma de la base de données.

1. Créer un fichier LDD

echo "CREATE TABLE InventoryHistory (ItemRowID STRING (36) NOT NULL, ItemID INT64 NOT NULL, InventoryChange INT64, Timestamp TIMESTAMP) PRIMARY KEY(ItemRowID)" >> table.ddl

2. Créer la base de données Spanner

gcloud spanner databases create $SPANNER_DB \
--instance=$SPANNER_INSTANCE \
--ddl-file=table.ddl

Exemple de résultat :

Creating database...done.

Vérifier l'état et le schéma de la base de données

1. Afficher l'état de la base de données

gcloud spanner databases describe $SPANNER_DB \
--instance=$SPANNER_INSTANCE

Exemple de résultat :

createTime: '2022-04-22T15:11:33.559300Z'
databaseDialect: GOOGLE_STANDARD_SQL
earliestVersionTime: '2022-04-22T15:11:33.559300Z'
encryptionInfo:
- encryptionType: GOOGLE_DEFAULT_ENCRYPTION
name: projects/cymbal-eats-7-348013/instances/menu-inventory/databases/menu-inventory
state: READY
versionRetentionPeriod: 1h

Remarque: L'état de la base de données indique READY (PRÊT)

2. Afficher le schéma de la base de données

gcloud spanner databases ddl describe $SPANNER_DB \
--instance=$SPANNER_INSTANCE

Exemple de résultat :

CREATE TABLE InventoryHistory (
  ItemRowID STRING(36) NOT NULL,
  ItemID INT64 NOT NULL,
  InventoryChange INT64,
  TimeStamp TIMESTAMP,
) PRIMARY KEY(ItemRowID);

Remarque:La base de données comporte quatre colonnes. ItemRowID est la clé primaire.

Vous pouvez également afficher les détails dans la console de présentation de Spanner.

5. Intégrer Spanner

Dans cette section, vous allez apprendre à intégrer Spanner à votre application. En outre, SQL Spanner fournit des bibliothèques clientes, des pilotes JDBC, des pilotes R2DBC, des API REST et des API RPC, qui vous permettent d'intégrer Spanner à n'importe quelle application.

Dans la section suivante, vous allez utiliser la bibliothèque cliente Go pour installer, authentifier et modifier des données dans Spanner.

Installer la bibliothèque cliente

La bibliothèque cliente Cloud Spanner facilite l'intégration à Cloud Spanner en utilisant automatiquement les identifiants par défaut de l'application (ADC) pour trouver les identifiants de votre compte de service.

Remarque:Le code de démarrage génère des erreurs pendant sa mise à jour. Vous pouvez ignorer ces erreurs.

Configurer l'authentification

La Google Cloud CLI et les bibliothèques clientes Google Cloud détectent automatiquement lorsqu'elles s'exécutent sur Google Cloud et utilisent le compte de service d'exécution de la révision Cloud Run actuelle. Cette stratégie, appelée "Identifiants par défaut de l'application", permet la portabilité du code entre plusieurs environnements.

Toutefois, il est préférable de créer une identité dédiée en lui attribuant un compte de service géré par l'utilisateur plutôt que le compte de service par défaut.

1. Accorder au compte de service le rôle d'administrateur de bases de données Spanner

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$[e-mail]" \
--role="roles/spanner.databaseAdmin"

Exemple de résultat :

Updated IAM policy for project [cymbal-eats-6422-3462].
[...]

Avec le rôle Administrateur de bases de données Spanner, le compte de service peut:

• Obtenir/répertorier toutes les instances Cloud Spanner du projet
• Créer/répertorier/supprimer les bases de données d'une instance
• Accorder/révoquer l'accès aux bases de données du projet
• Lire et écrire dans toutes les bases de données Cloud Spanner du projet

Bibliothèques clientes

Les bibliothèques clientes Spanner permettent d'éliminer les complexités de l'intégration à Spanner et sont disponibles dans de nombreux langages de programmation courants.

Créer un client Spanner

Le client Spanner est un client permettant de lire et d'écrire des données dans une base de données Cloud Spanner. Vous pouvez utiliser un client simultanément en toute sécurité, à l'exception de sa méthode Close.

L'extrait de code ci-dessous crée un client Spanner

main.go

var dataClient *spanner.Client
...
dataClient, err = spanner.NewClient(ctx, databaseName)

Un client peut être considéré comme une connexion à une base de données: toutes vos interactions avec Cloud Spanner doivent s'effectuer par le biais d'un client. Généralement, vous créez un client lorsque votre application démarre, puis vous le réutilisez pour lire, écrire et exécuter des transactions. Chaque client utilise des ressources dans Cloud Spanner.

Modifier les données

Il existe plusieurs façons d'insérer, de mettre à jour et de supprimer des données dans une base de données Spanner. Vous trouverez ci-dessous les méthodes disponibles.

• Console Google Cloud
• CLI gcloud
• DML
• Mutations

Dans cet atelier, vous allez utiliser des mutations pour modifier des données dans Spanner.

Mutations dans Spanner

Un objet Mutation est un conteneur destiné aux opérations de mutation. Une mutation représente une séquence d'opérations (insertions, mises à jour, suppressions, etc.) que Cloud Spanner applique de manière atomique à différentes lignes et tables d'une base de données Cloud Spanner.

main.go

m := []*spanner.Mutation{}

m = append(m, spanner.Insert(
        "inventoryHistory",
         inventoryHistoryColumns,
        []interface{}{uuid.New().String(), element.ItemID, element.InventoryChange, time.Now()}))

L'extrait de code insère une nouvelle ligne dans le tableau de l'historique de l'inventaire.

Déploiement et test

Maintenant que Spanner est configuré et que vous avez passé en revue les éléments de code clés qui déploient l'application sur Cloud Run,

Déployer l'application sur Cloud Run

Cloud Run peut automatiquement créer, transférer et déployer votre code à l'aide d'une seule commande. Dans la commande suivante, vous allez appeler la commande deploy sur le service run, en transmettant les variables utilisées par l'application en cours d'exécution, telles que SPANNER_CONNECTION_STRING que vous avez créée précédemment.

1. Cliquez sur "Ouvrir le terminal".
2. Déployer le service d'inventaire sur Cloud Run

gcloud run deploy inventory-service \
    --source . \
    --region $REGION \
    --update-env-vars SPANNER_CONNECTION_STRING=$SPANNER_CONNECTION_STRING \
    --allow-unauthenticated \
    --project=$PROJECT_ID \
    --quiet

Exemple de résultat :

Service [inventory-service] revision [inventory-service-00001-sug] has been deployed and is serving 100 percent of traffic.
Service URL: https://inventory-service-ilwytgcbca-uk.a.run.app

Remarque:Si vous êtes invité à continuer, saisissez "Y"

3. Stocker l'URL du service

INVENTORY_SERVICE_URL=$(gcloud run services describe inventory-service \
  --platform managed \
  --region $REGION \
  --format=json | jq \
  --raw-output ".status.url")

Tester l'application Cloud Run

Insérer un élément

1. Dans cloudshell, saisissez la commande suivante :

POST_URL=$INVENTORY_SERVICE_URL/updateInventoryItem
curl -i -X POST ${POST_URL} \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "itemID": 1,
        "inventoryChange": 5
    }
]'

Exemple de résultat :

HTTP/2 200
access-control-allow-origin: *
content-type: application/json
x-cloud-trace-context: 10c32f0863d26521497dc26e86419f13;o=1
date: Fri, 22 Apr 2022 21:41:38 GMT
server: Google Frontend
content-length: 2

OK

Interroger un élément

1. Interroger le service d'inventaire

GET_URL=$INVENTORY_SERVICE_URL/getAvailableInventory
curl -i ${GET_URL}

Exemple de réponse

HTTP/2 200
access-control-allow-origin: *
content-type: text/plain; charset=utf-8
x-cloud-trace-context: b94f921e4c2ae90210472c88eb05ace8;o=1
date: Fri, 22 Apr 2022 21:45:50 GMT
server: Google Frontend
content-length: 166

[{"ItemID":1,"Inventory":5}]

6. Concepts Spanner

Cloud Spanner interroge ses bases de données à l'aide d'instructions SQL déclaratives. Les instructions SQL indiquent ce que l’utilisateur veut sans décrire comment les résultats seront obtenus.

1. Dans le terminal, saisissez la commande suivante pour interroger la table afin d'obtenir l'enregistrement créé précédemment.

gcloud spanner databases execute-sql $SPANNER_DB \
--instance=$SPANNER_INSTANCE \
--sql='SELECT * FROM InventoryHistory WHERE ItemID=1'

Exemple de résultat :

ItemRowID: 1
ItemID: 1
InventoryChange: 3
Timestamp: 

Plans d'exécution de requêtes

Un plan d'exécution de requêtes est une série d'étapes que Spanner utilise pour obtenir des résultats. Il peut y avoir plusieurs façons d'obtenir les résultats d'une instruction SQL particulière. Les plans d'exécution de requêtes sont accessibles dans la console et dans les bibliothèques clientes. Pour savoir comment Spanner gère les requêtes SQL:

1. Dans la console, ouvrez la page "Instances Cloud Spanner".
2. Accéder à la page Instances de Cloud Spanner
3. Cliquez sur le nom de l'instance Cloud Spanner. Dans la section "Bases de données", sélectionnez la base de données que vous souhaitez interroger.
4. Cliquez sur "Requête".
5. Saisissez la requête suivante dans l'éditeur de requête.

SELECT * FROM InventoryHistory WHERE ItemID=1

6. Cliquez sur EXÉCUTER.
7. Cliquez sur EXPLICATION.

La console Cloud affiche un plan d'exécution visuel pour votre requête.

Conceptuellement, un plan d'exécution correspond à une arborescence d'opérateurs relationnels. Chaque opérateur lit les lignes à partir de ses entrées et génère des lignes de sortie. La racine de l'exécution est renvoyée à la suite de la requête SQL.

Optimiseur de requêtes

L'optimiseur de requêtes Cloud Spanner compare les plans d'exécution alternatifs et sélectionne le plus efficace. Au fil du temps, l'optimiseur de requête évoluera, en élargissant les choix dans le plan d'exécution des requêtes et en améliorant la précision des estimations qui guident ces choix, ce qui conduira à des plans d'exécution des requêtes plus efficaces.

Cloud Spanner déploie les mises à jour de l'optimiseur en tant que nouvelles versions de l'optimiseur de requêtes. Par défaut, chaque base de données commence à utiliser la dernière version de l'optimiseur au moins 30 jours après sa publication.

Pour afficher la version utilisée lors de l'exécution d'une requête dans gcloud spanner, définissez l'option "-query-mode" sur PROFILE

1. Saisissez la commande suivante pour afficher la version de l'optimiseur

gcloud spanner databases execute-sql $SPANNER_DB --instance=$SPANNER_INSTANCE \
--query-mode=PROFILE --sql='SELECT * FROM InventoryHistory'

Exemple de résultat :

TOTAL_ELAPSED_TIME: 6.18 msecs
CPU_TIME: 5.17 msecs
ROWS_RETURNED: 1
ROWS_SCANNED: 1
OPTIMIZER_VERSION: 3
 RELATIONAL Distributed Union
 (1 execution, 0.11 msecs total latency)
 subquery_cluster_node: 1
    |
    +- RELATIONAL Distributed Union
    |  (1 execution, 0.09 msecs total latency)
    |  call_type: Local, subquery_cluster_node: 2
    |   |
    |   \- RELATIONAL Serialize Result
    |      (1 execution, 0.08 msecs total latency)
    |       |
    |       +- RELATIONAL Scan
    |       |  (1 execution, 0.08 msecs total latency)
    |       |  Full scan: true, scan_target: InventoryHistory, scan_type: TableScan
    |       |   |
    |       |   +- SCALAR Reference
    |       |   |  ItemRowID
    |       |   |
    |       |   +- SCALAR Reference
    |       |   |  ItemID
    |       |   |
    |       |   +- SCALAR Reference
    |       |   |  InventoryChange
    |       |   |
    |       |   \- SCALAR Reference
    |       |      Timestamp
    |       |
    |       +- SCALAR Reference
    |       |  $ItemRowID
    |       |
    |       +- SCALAR Reference
    |       |  $ItemID
    |       |
    |       +- SCALAR Reference
    |       |  $InventoryChange
    |       |
    |       \- SCALAR Reference
    |          $Timestamp
    |
    \- SCALAR Constant
       true

ItemRowID: 1
ItemID: 1
InventoryChange: 3
Timestamp:

La version actuelle est définie sur la version 3. Pour connaître la version la plus récente, consultez l'historique des versions.

Mettre à jour la version de l'optimiseur

Au moment de cet atelier, la version la plus récente est la version 4. Vous allez maintenant mettre à jour la table Spanner afin qu'elle utilise la version 4 pour l'optimiseur de requêtes.

2. Mettre à jour l'optimiseur

gcloud spanner databases ddl update $SPANNER_DB \
--instance=$SPANNER_INSTANCE \
--ddl='ALTER DATABASE InventoryHistory
SET OPTIONS (optimizer_version = 4)'

Exemple de résultat :

Schema updating...done. 

3. Saisissez la commande suivante pour afficher la mise à jour de la version de l'optimiseur

gcloud spanner databases execute-sql $SPANNER_DB --instance=$SPANNER_INSTANCE \
--query-mode=PROFILE --sql='SELECT * FROM InventoryHistory'

Exemple de résultat :

TOTAL_ELAPSED_TIME: 8.57 msecs
CPU_TIME: 8.54 msecs
ROWS_RETURNED: 1
ROWS_SCANNED: 1
OPTIMIZER_VERSION: 4
[...]

OPTIMIZER_VERSION a été mis à jour à la version 4.

Visualiser la version de l'optimiseur de requêtes dans l'explorateur de métriques

Vous pouvez utiliser l'Explorateur de métriques dans la console Cloud pour visualiser le nombre de requêtes pour votre instance de base de données. Vous pouvez voir quelle version de l'optimiseur est utilisée dans chaque base de données.

1. Accédez à Monitoring dans la console Cloud et sélectionnez Explorateur de métriques dans le menu de gauche.
2. Dans le champ Type de ressource, sélectionnez "Instance Cloud Spanner".
3. Dans le champ Métrique, sélectionnez "Nombre de requêtes", puis "Appliquer".
4. Dans le champ Group by (Grouper par), sélectionnez "database", "optimiseur_version" et "status".

7. Créer et configurer une base de données Firestore

Conçue pour le scaling automatique et les hautes performances, Firestore est une base de données de documents NoSQL qui simplifie le développement d'applications. Bien que l'interface Firestore présente de nombreuses fonctionnalités identiques aux bases de données traditionnelles, une base de données NoSQL diffère d'elles en décrivant les relations entre les objets de données.

La tâche suivante va vous guider dans la création d'une application Cloud Run de service de commande reposant sur Firestore. Le service de commande appelle le service d'inventaire créé dans la section précédente pour interroger la base de données Spanner avant de lancer la commande. Ce service permet de garantir un inventaire suffisant et la possibilité de honorer la commande.

8. Concepts Firestore

Modèle de données

Une base de données Firestore est constituée de collections et de documents.

Documents

Chaque document contient un ensemble de paires clé/valeur. Firestore est optimisé pour le stockage de grandes collections de petits documents.

Dans l'exemple ci-dessus, le document d'ID de commande contient quatre paires clé-valeur. Les éléments "orderItems" clés incluent un tableau de paires clé-valeur.

Collections

Vous devez stocker tous les documents dans des collections. Les documents peuvent contenir des sous-collections et des objets imbriqués, y compris des champs primitifs comme des chaînes ou des objets complexes comme des listes.

Dans l'exemple ci-dessus, le document correspondant à l'ID de commande est stocké dans la collection de commandes.

Créer une base de données Firestore

1. Créer la base de données Firestore

gcloud firestore databases create --location=$REGION

Exemple de résultat :

Success! Selected Google Cloud Firestore Native database for cymbal-eats-6422-3462

La nouvelle base de données Firestore que vous avez créée est actuellement vide. La nouvelle base de données dispose également d'un ensemble de règles de sécurité par défaut qui autorisent tout utilisateur à effectuer des opérations de lecture et empêchent toute personne d'écrire dans la base de données.

9. Intégrer Firestore à votre application

Dans cette section, vous allez mettre à jour le compte de service, ajouter des comptes de service d'accès Firestore, examiner et déployer les règles de sécurité Firestore, et examiner la modification des données dans Firestore.

Configurer l'authentification

1. Attribuer le rôle utilisateur Datastore au compte de service

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$[e-mail]" \
  --role="roles/datastore.user"

Exemple de résultat :

Updated IAM policy for project [cymbal-eats-6422-3462].

Le rôle utilisateur Datastore accorde un accès en lecture/écriture aux données d'une base de données Firestore.

Règles de sécurité Firestore

Les règles de sécurité offrent un format à la fois expressif et simple pour le contrôle des accès et la validation des données.

1. Accéder au répertoire "order-service/starter-code"

cd ~/cymbal-eats/order-service

2. Ouvrir le fichier firestore.rules dans l'éditeur Cloud

cat firestore.rules

firestore.rules

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents { ⇐ All database
    match /{document=**} { ⇐ All documents
      allow read: if true; ⇐ Allow reads
    }
    match /{document=**} {
      allow write: if false; ⇐ Deny writes
    }
  }
}

Le fichier "firestore.rules" contient des règles permettant d'autoriser toutes les opérations de lecture et de refuser toutes les opérations d'écriture pour l'ensemble des tables de la base de données Firestore. Pour en savoir plus sur les règles Firestore, consultez Premiers pas avec les règles de sécurité.

Avertissement:Il est recommandé de limiter l'accès au stockage Firestore. Dans le cadre de cet atelier, toutes les lectures sont autorisées. Cette configuration de production n'est pas recommandée.

Activer les services gérés Firestore

1. Cliquez sur "Ouvrir le terminal".
2. Créez un fichier .firebaserc avec l'ID de projet actuel. Les paramètres des cibles de déploiement sont stockés dans le fichier .firebaserc du répertoire de votre projet.

firebaserc.tmpl

sed "s/PROJECT_ID/$PROJECT_ID/g" firebaserc.tmpl > .firebaserc

2. Télécharger le binaire Firebase

curl -sL https://firebase.tools | upgrade=true bash

Exemple de résultat :

-- Checking for existing firebase-tools on PATH...
Your machine already has firebase-tools@10.7.0 installed. Nothing to do.
-- All done!

3. Déployer les règles Firestore

firebase deploy 

Exemple de résultat

=== Deploying to 'cymbal-eats-6422-3462'...

i  deploying firestore
i  cloud.firestore: checking firestore.rules for compilation errors...
✔  cloud.firestore: rules file firestore.rules compiled successfully
i  firestore: uploading rules firestore.rules...
✔  firestore: released rules firestore.rules to cloud.firestore

✔  Deploy complete!

Project Console: https://console.firebase.google.com/project/cymbal-eats-6422-3462/overview

La mise à jour des règles de sécurité Cloud Firestore peut prendre jusqu'à une minute pour affecter les nouvelles requêtes et les nouveaux écouteurs. Toutefois, la propagation complète des modifications et leur impact sur les écouteurs actifs peuvent prendre jusqu'à 10 minutes.

Modifier les données

Dans Firestore, les collections et les documents sont créés implicitement. Il vous suffit d'attribuer des données à un document au sein d'une collection. Si la collection ou le document n'existe pas, Firestore le crée.

Ajouter des données à Firestore

Il existe plusieurs façons d'écrire des données dans Cloud Firestore :

• Définissez les données d'un document au sein d'une collection, en spécifiant explicitement un identifiant de document.
• Ajoutez un document à une collection. Dans ce cas, Cloud Firestore génère automatiquement l'identifiant du document.
• Créez un document vide avec un identifiant généré automatiquement et attribuez-lui des données ultérieurement.

La section suivante va vous guider dans la création d'un document à l'aide de la méthode set.

Définir un document

Utilisez la méthode set() pour créer un document. Avec la méthode set(), vous devez spécifier un ID pour le document à créer.

Examinez l'extrait de code ci-dessous.

index.js

const orderDoc = db.doc(`orders/123`);
await orderDoc.set({
    orderNumber: 123,
    name: Anne,
    address: 555 Bright Street,
    city: Mountain View,
    state: CA,
    zip: 94043,
    orderItems: [id: 1],
    status: 'New'
  });

Ce code crée un document spécifiant l'ID 123 généré par l'utilisateur. Pour que Firestore génère un ID en votre nom, utilisez la méthode add() ou create().

Lorsque vous utilisez set() si le document n'existe pas, il est créé. Si le document existe, son contenu sera remplacé par les nouvelles données fournies.

Mettre à jour un document

La méthode de mise à jour update() vous permet de mettre à jour certains champs d'un document sans écraser l'ensemble du document.

Dans l'extrait ci-dessous, le code met à jour la commande 123

index.js

const orderDoc = db.doc(`orders/123`);
await orderDoc.update(name: "Anna");

Supprimer un document

Dans Firestore, vous pouvez supprimer des collections, des documents ou des champs spécifiques d'un document. Pour supprimer un document, utilisez la méthode delete().

L'extrait ci-dessous supprime la commande 123.

index.js

const orderDoc = db.doc(`orders/123`);
await orderDoc.delete();

Remarque:La suppression d'un document n'entraîne pas la suppression de ses sous-collections.

10. Déploiement et test

Dans cette section, vous allez déployer l'application sur Cloud Run et tester les méthodes de création, de mise à jour et de suppression.

Déployer l'application sur Cloud Run

1. Stockez l'URL dans la variable INVENTORY_SERVICE_URL pour intégrer le service Inventory

INVENTORY_SERVICE_URL=$(gcloud run services describe inventory-service \
 --region=$REGION \
 --format=json | jq \
 --raw-output ".status.url")

Le service des commandes doit communiquer avec le service d'inventaire pour vérifier l'existence des stocks et le traitement des commandes. Au cours de cette étape, vous allez stocker l'URL du service d'inventaire dans une variable qui sera transmise au service de commandes en tant que variable d'environnement.

2. Déployer le service des commandes

gcloud run deploy order-service \
  --source . \
  --platform managed \
  --region $REGION \
  --allow-unauthenticated \
  --project=$PROJECT_ID \
  --set-env-vars=INVENTORY_SERVICE_URL=$INVENTORY_SERVICE_URL \
  --quiet

Exemple de résultat :

[...]
Done.
Service [order-service] revision [order-service-00001-qot] has been deployed and is serving 100 percent of traffic.
Service URL: https://order-service-3jbm3exegq-uk.a.run.app

Tester l'application Cloud Run

Créer un document

1. Stocker l'URL de l'application du service de commande dans une variable à des fins de test

ORDER_SERVICE_URL=$(gcloud run services describe order-service \
  --platform managed \
  --region $REGION \
  --format=json | jq \
  --raw-output ".status.url")

2. Créer une requête de commande et publier une nouvelle commande dans la base de données Firestore

curl --request POST $ORDER_SERVICE_URL/order \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Jane Doe",
         "email": "[e-mail]",
    "address": "123 Maple",
    "city": "Buffalo",
    "state": "NY",
    "zip": "12346",
    "orderItems": [
        {
            "id": 1
        }
    ]
}'

Exemple de résultat :

{"orderNumber":46429}

Enregistrer le numéro de commande pour une utilisation ultérieure

export ORDER_NUMBER=<value_from_output>

Afficher les résultats

Afficher les résultats dans Firestore

1. Accédez à la console Firestore.
2. Cliquez sur "Données".

Mettre à jour un document

La commande n'incluait pas la quantité.

1. Mettre à jour l'enregistrement et ajouter une paire clé-valeur de quantité

curl --location -g --request PATCH $ORDER_SERVICE_URL/order/${ORDER_NUMBER} \
--header 'Content-Type: application/json' \
--data-raw '{
"orderItems": [
        {   
            "id": 1,
            "quantity": 1   
        }
    ]
}'

Exemple de résultat :

{"status":"success"}

Afficher les résultats

Afficher les résultats dans Firestore

3. Accédez à la console Firestore.
4. Cliquez sur "Données".

Lors de la mise à jour de la structure NoSQL dans Firestore à l'aide de patch(), seuls les éléments transmis dans l'appel sont mis à jour.

Supprimer un document

1. Supprimer l'élément 46429 de la collection de commandes Firestore

curl --location -g --request DELETE $ORDER_SERVICE_URL/order/${ORDER_NUMBER}

Afficher les résultats

5. Accédez à la console Firestore.
6. Cliquez sur "Données".

Le document 46429 a été supprimé, mais les collections des commandes sont conservées.

11. Félicitations !

Félicitations, vous avez terminé l'atelier !

Étapes suivantes :

Découvrez d'autres ateliers de programmation Cymbal Eats:

• Déclencher Cloud Workflows avec Eventarc
• Déclencher le traitement des événements depuis Cloud Storage
• Se connecter au service Cloud SQL privé depuis Cloud Run
• Sécuriser une application sans serveur avec Identity-Aware Proxy (IAP)
• Déclencher des jobs Cloud Run avec Cloud Scheduler
• Déployer une application sur Cloud Run en toute sécurité
• Sécuriser le trafic d'entrée Cloud Run
• Se connecter à une instance privée AlloyDB depuis GKE Autopilot

Effectuer un nettoyage

Pour éviter que les ressources utilisées lors de ce tutoriel soient facturées sur votre compte Google Cloud, supprimez le projet contenant les ressources, ou conservez le projet et supprimez chaque ressource individuellement.

Supprimer le projet

Le moyen le plus simple d'empêcher la facturation est de supprimer le projet que vous avez créé pour ce tutoriel.