Cette page a été traduite par l'API Cloud Translation.

Premiers pas avec l'API Cloud Firestore en mode Datastore

Cette page propose un court exercice consistant à créer une application de ligne de commande TaskList avec l'API Firestore en mode Datastore. L'application TaskList permet de stocker, répertorier, mettre à jour et supprimer des tâches.

Prérequis

Capacité à écrire et à exécuter une application de ligne de commande dans les langages de programmation utilisés dans cet article
Avant de suivre ce tutoriel, outre une compréhension de base du développement d'applications, vous devez pouvoir télécharger et installer des bibliothèques supplémentaires.
Un projet Google Cloud avec l'API en mode Datastore activée
Les applications qui utilisent le mode Datastore sont associées à un projet Google Cloud avec l'API en mode Datastore activée. Ce projet fournit les identifiants d'authentification que vous employez dans votre application pour l'identifier auprès de Google et l'autoriser à utiliser l'API en mode Datastore.
Suivez ces instructions pour créer un projet, activer l'API en mode Datastore pour celui-ci, et définir des identifiants d'authentification pour votre environnement de développement local à l'aide de la commande gcloud auth login. Notez l'ID du projet, car vous en aurez besoin ultérieurement.

Installation et configuration

Installez les bibliothèques clientes et configurez tout paramètre supplémentaire pour votre environnement de développement.

C#

Assurez-vous que Visual Studio (version 2013 ou ultérieure) est installé.
Téléchargez l'exemple d'application TaskList à partir du dépôt d'exemples.
Extrayez les fichiers du fichier ZIP dans un répertoire de votre dossier Documents.
Dans Visual Studio, ouvrez le fichier dotnet-docs-samples-master\datastore\api\Datastore.sln.
Dans la fenêtre Solution Explorer (Explorateur de solutions) de Visual Studio, cliquez avec le bouton droit sur le projet TaskList et choisissez Définir comme projet de démarrage.
Cliquez à nouveau avec le bouton droit sur le projet TaskList, puis choisissez Propriétés.
Dans la fenêtre Propriétés, cliquez sur Debug (Débogage), puis saisissez l'ID de votre projet Google Cloud dans la zone Command line arguments (Arguments de ligne de commande).
Cliquez sur Fichier, puis sur Enregistrer pour enregistrer les modifications.
Exécutez l'application. Appuyez sur la touche F5 de votre clavier.

Go

Clonez l'exemple d'application TaskList.

go get github.com/GoogleCloudPlatform/golang-samples/datastore/tasks

Remplacez les répertoires par ceux dans lesquels vous avez cloné l'exemple :

cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/datastore/tasks

À l'invite de commande, exécutez la commande suivante, où <project-id> correspond à l'ID de votre projet Google Cloud.
```
export DATASTORE_PROJECT_ID=<project-id>
```
(Utilisateurs de Windows : utilisez set au lieu de export.)
Exécutez l'application.
```
go run tasks.go
```

Java

Assurez-vous que Maven et Java (version 8 ou ultérieure) sont installés.
Téléchargez l'exemple d'application TaskList à partir du dépôt d'exemples.
À l'invite de commande, extrayez le téléchargement:
```
unzip main.zip
```
Modifiez les répertoires pour qu'ils pointent vers l'application TaskList :
```
cd java-datastore-main/samples/snippets
```
Exécutez la commande suivante, où <project-id> correspond à l'ID de votre projet Google Cloud.
```
gcloud config set project <project-id>
```

Compilez et exécutez l'application.

mvn clean compile
mvn exec:java -Dexec.mainClass="com.google.datastore.snippets.TaskList"

Node.js

Préparez votre environnement pour un développement en Node.js.
Téléchargez l'exemple d'application TaskList à partir du dépôt d'exemples.
Extrayez le téléchargement:
```
unzip master.zip
```
Modifiez les répertoires pour qu'ils pointent vers l'application TaskList :
```
cd nodejs-datastore-master/samples
```
Installez les dépendances et associez l'application :
```
npm install
```
À l'invite de commande, exécutez la commande suivante, où <project-id> correspond à l'ID de votre projet Google Cloud.
```
export GCLOUD_PROJECT=<project-id>
```
(Utilisateurs de Windows : utilisez set au lieu de export.)
Exécutez l'application.
```
node tasks.js
```

PHP

Assurez-vous que PHP (version 5.6 ou ultérieure) et Composer sont installés.
Téléchargez l'exemple d'application TaskList à partir du dépôt d'exemples.
Extrayez le téléchargement:
```
unzip master.zip
```
Modifiez les répertoires pour qu'ils pointent vers l'application TaskList :
```
cd php-docs-samples-master/datastore/tutorial
```
Installez les dépendances.
```
composer install
```
Exécutez l'application.
```
php src/list_tasks.php
```

Python

Assurez-vous que Python (version 2.7.9 ou ultérieure), pip et virtualenv sont installés.

Activez une session virtualenv.

virtualenv venv
source venv/bin/activate

Téléchargez l'exemple d'application TaskList à partir du dépôt d'exemples.
Extrayez le téléchargement:
```
unzip master.zip
```
Modifiez les répertoires pour qu'ils pointent vers l'application TaskList :
```
cd python-docs-samples-master/datastore/cloud-client
```
Installez les dépendances :
```
pip install -r requirements.txt
```
Exécutez l'application. Utilisez l'ID de votre projet Google Cloud pour <project-id>.
```
python tasks.py new project-id
```

Ruby

Assurez-vous que Ruby et Bundler sont installés.
Téléchargez l'exemple d'application TaskList à partir du dépôt d'exemples.
Extrayez le téléchargement:
```
unzip master.zip
```
Modifiez les répertoires pour qu'ils pointent vers l'application TaskList :
```
cd google-cloud-ruby-master/google-cloud-datastore/samples
```
Installez les dépendances :
```
bundle install
```
À l'invite de commande, exécutez la commande suivante, où <project-id> correspond à l'ID de votre projet Google Cloud.
```
export GOOGLE_CLOUD_PROJECT=<project-id>
```
(Utilisateurs de Windows : utilisez set au lieu de export.)
Exécutez l'application.
```
bundle exec ruby tasks.rb
```

Créer un objet de service autorisé

Pour envoyer des requêtes authentifiées aux API Google Cloud à l'aide des bibliothèques clientes d'API Google, vous devez :

extraire les identifiants à utiliser pour les requêtes ;
créer un objet de service qui utilise ces identifiants.

Vous pouvez ensuite effectuer des appels d'API en appelant des méthodes sur l'objet de service en mode Datastore.

Dans cet exemple, vous allez extraire les identifiants par défaut de l'application de l'environnement, puis les transmettre en tant qu'argument pour créer l'objet de service.

Voici l'appel permettant de créer l'objet de service en mode Datastore autorisé :

C#

Pour savoir comment installer et utiliser la bibliothèque cliente pour Cloud Datastore, consultez la page Bibliothèques clientes Cloud Datastore. Pour en savoir plus, consultez la documentation de référence de l'API Cloud Datastore C#.

Pour vous authentifier auprès de Cloud Datastore, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

// Create an authorized Datastore service using Application Default Credentials.
_db = DatastoreDb.Create(projectId);
// Create a Key factory to construct keys associated with this project.
_keyFactory = _db.CreateKeyFactory("Task");

Go

import (
	"context"
	"log"

	"cloud.google.com/go/datastore"
)

func createClient(projectID string) (*datastore.Client, error) {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectID)
	if err != nil {
		log.Fatalf("Could not create datastore client: %v", err)
	}
	// Note: call the following from main() to ensure the client
	// properly frees all resources.
	// defer client.Close()
	return client, nil
}

Java

// Create an authorized Datastore service using Application Default Credentials.
private final Datastore datastore = DatastoreOptions.getDefaultInstance().getService();

// Create a Key factory to construct keys associated with this project.
private final KeyFactory keyFactory = datastore.newKeyFactory().setKind("Task");

Node.js

// By default, the client will authenticate using the service account file
// specified by the GOOGLE_APPLICATION_CREDENTIALS environment variable and use
// the project specified by the GCLOUD_PROJECT environment variable. See
// https://googlecloudplatform.github.io/google-cloud-node/#/docs/datastore/latest/guides/authentication
const {Datastore} = require('@google-cloud/datastore');

// Creates a client
const datastore = new Datastore();

PHP

use Google\Cloud\Datastore\DatastoreClient;

/**
 * Create a Cloud Datastore client.
 *
 * @param string $projectId The Google Cloud project ID.
 */
function build_service(string $projectId)
{
    $datastore = new DatastoreClient(['projectId' => $projectId]);
    return $datastore;
}

Python

from google.cloud import datastore

def create_client(project_id):
    return datastore.Client(project_id)

Ruby

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

Stocker des données

Dans le mode Datastore, les objets sont appelés entités, et chaque entité est d'un genre particulier. L'application TaskList stocke des entités du genre Task, avec les propriétés suivantes :

description : chaîne spécifiée par l'utilisateur en tant que description de la tâche
created : date de création initiale de la tâche
done : valeur booléenne indiquant si la tâche a été effectuée

Lorsque l'utilisateur ajoute une tâche, l'application TaskList crée une entité Task avec des valeurs pour les propriétés précédemment listées:

C#

/// <summary>
///  Adds a task entity to the Datastore
/// </summary>
/// <param name="description">The task description.</param>
/// <returns>The key of the entity.</returns>
Key AddTask(string description)
{
    Entity task = new Entity()
    {
        Key = _keyFactory.CreateIncompleteKey(),
        ["description"] = new Value()
        {
            StringValue = description,
            ExcludeFromIndexes = true
        },
        ["created"] = DateTime.UtcNow,
        ["done"] = false
    };
    return _db.Insert(task);
}

Go

import (
	"context"
	"log"
	"time"

	"cloud.google.com/go/datastore"
)

// Task is the model used to store tasks in the datastore.
type Task struct {
	Desc    string    `datastore:"description"`
	Created time.Time `datastore:"created"`
	Done    bool      `datastore:"done"`
	id      int64     // The integer ID used in the datastore.
}

// AddTask adds a task with the given description to the datastore,
// returning the key of the newly created entity.
func AddTask(projectID string, desc string) (*datastore.Key, error) {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectID)
	if err != nil {
		log.Fatalf("Could not create datastore client: %v", err)
	}
	defer client.Close()
	task := &Task{
		Desc:    desc,
		Created: time.Now(),
	}
	key := datastore.IncompleteKey("Task", nil)
	return client.Put(ctx, key, task)

}

Java

/**
 * Adds a task entity to the Datastore.
 *
 * @param description The task description
 * @return The {@link Key} of the entity
 * @throws DatastoreException if the ID allocation or put fails
 */
Key addTask(String description) {
  Key key = datastore.allocateId(keyFactory.newKey());
  Entity task =
      Entity.newBuilder(key)
          .set(
              "description",
              StringValue.newBuilder(description).setExcludeFromIndexes(true).build())
          .set("created", Timestamp.now())
          .set("done", false)
          .build();
  datastore.put(task);
  return key;
}

Node.js

async function addTask(description) {
  const taskKey = datastore.key('Task');
  const entity = {
    key: taskKey,
    data: [
      {
        name: 'created',
        value: new Date().toJSON(),
      },
      {
        name: 'description',
        value: description,
        excludeFromIndexes: true,
      },
      {
        name: 'done',
        value: false,
      },
    ],
  };

  try {
    await datastore.save(entity);
    console.log(`Task ${taskKey.id} created successfully.`);
  } catch (err) {
    console.error('ERROR:', err);
  }
}

PHP

use Google\Cloud\Datastore\DatastoreClient;

/**
 * Create a new task with a given description.
 *
 * @param string $projectId The Google Cloud project ID.
 * @param string $description
 */
function add_task(string $projectId, string $description)
{
    $datastore = new DatastoreClient(['projectId' => $projectId]);

    $taskKey = $datastore->key('Task');
    $task = $datastore->entity(
        $taskKey,
        [
            'created' => new DateTime(),
            'description' => $description,
            'done' => false
        ],
        ['excludeFromIndexes' => ['description']]
    );
    $datastore->insert($task);
    printf('Created new task with ID %d.' . PHP_EOL, $task->key()->pathEnd()['id']);
}

Python

from google.cloud import datastore

def add_task(client: datastore.Client, description: str):
    # Create an incomplete key for an entity of kind "Task". An incomplete
    # key is one where Datastore will automatically generate an Id
    key = client.key("Task")

    # Create an unsaved Entity object, and tell Datastore not to index the
    # `description` field
    task = datastore.Entity(key, exclude_from_indexes=("description",))

    # Apply new field values and save the Task entity to Datastore
    task.update(
        {
            "created": datetime.datetime.now(tz=datetime.timezone.utc),
            "description": description,
            "done": False,
        }
    )
    client.put(task)
    return task.key

Ruby

def add_task description
  require "google/cloud/datastore"

  datastore = Google::Cloud::Datastore.new

  task = datastore.entity "Task" do |t|
    t["description"] = description
    t["created"]     = Time.now
    t["done"]        = false
    t.exclude_from_indexes! "description", true
  end

  datastore.save task

  puts task.key.id

  task.key.id
end

Pour cette application, nous fournissons également une méthode permettant de mettre à jour la propriété done pour indiquer que la tâche est terminée:

C#

/// <summary>
/// Marks a task entity as done.
/// </summary>
/// <param name="id">The ID of the task entity as given by Key.</param>
/// <returns>true if the task was found.</returns>
bool MarkDone(long id)
{
    using (var transaction = _db.BeginTransaction())
    {
        Entity task = transaction.Lookup(_keyFactory.CreateKey(id));
        if (task != null)
        {
            task["done"] = true;
            transaction.Update(task);
        }
        transaction.Commit();
        return task != null;
    }
}

Go

import (
	"context"
	"log"

	"cloud.google.com/go/datastore"
)

// MarkDone marks the task done with the given ID.
func MarkDone(projectID string, taskID int64) error {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectID)
	if err != nil {
		log.Fatalf("Could not create datastore client: %v", err)
	}
	defer client.Close()
	// Create a key using the given integer ID.
	key := datastore.IDKey("Task", taskID, nil)

	// In a transaction load each task, set done to true and store.
	_, err = client.RunInTransaction(ctx, func(tx *datastore.Transaction) error {
		var task Task
		if err := tx.Get(key, &task); err != nil {
			return err
		}
		task.Done = true
		_, err := tx.Put(key, &task)
		return err
	})
	return err
}

Java

/**
 * Marks a task entity as done.
 *
 * @param id The ID of the task entity as given by {@link Key#id()}
 * @return true if the task was found, false if not
 * @throws DatastoreException if the transaction fails
 */
boolean markDone(long id) {
  Transaction transaction = datastore.newTransaction();
  try {
    Entity task = transaction.get(keyFactory.newKey(id));
    if (task != null) {
      transaction.put(Entity.newBuilder(task).set("done", true).build());
    }
    transaction.commit();
    return task != null;
  } finally {
    if (transaction.isActive()) {
      transaction.rollback();
    }
  }
}

Node.js

async function markDone(taskId) {
  const transaction = datastore.transaction();
  const taskKey = datastore.key(['Task', datastore.int(taskId)]);

  try {
    await transaction.run();
    const [task] = await transaction.get(taskKey);
    task.done = true;
    transaction.save({
      key: taskKey,
      data: task,
    });
    await transaction.commit();
    console.log(`Task ${taskId} updated successfully.`);
  } catch (err) {
    await transaction.rollback();
  }
}

PHP

use Google\Cloud\Datastore\DatastoreClient;

/**
 * Mark a task with a given id as done.
 *
 * @param string $projectId The Google Cloud project ID.
 * @param string $taskId
 */
function mark_done(string $projectId, string $taskId)
{
    $datastore = new DatastoreClient(['projectId' => $projectId]);

    $taskKey = $datastore->key('Task', $taskId);
    $transaction = $datastore->transaction();
    $task = $transaction->lookup($taskKey);
    $task['done'] = true;
    $transaction->upsert($task);
    $transaction->commit();
    printf('Task %d updated successfully.' . PHP_EOL, $taskId);
}

Python

from google.cloud import datastore

def mark_done(client: datastore.Client, task_id: str | int):
    with client.transaction():
        # Create a key for an entity of kind "Task", and with the supplied
        # `task_id` as its Id
        key = client.key("Task", task_id)
        # Use that key to load the entity
        task = client.get(key)

        if not task:
            raise ValueError(f"Task {task_id} does not exist.")

        # Update a field indicating that the associated
        # work has been completed
        task["done"] = True

        # Persist the change back to Datastore
        client.put(task)

Ruby

def mark_done task_id
  require "google/cloud/datastore"

  datastore = Google::Cloud::Datastore.new

  task = datastore.find "Task", task_id

  task["done"] = true

  datastore.save task
end

Voici la méthode permettant de supprimer une entité Task, à l'aide de la clé Task de l'entité :

C#

/// <summary>
/// Deletes a task entity.
/// </summary>
/// <param name="id">The ID of the task entity as given by Key.</param>
void DeleteTask(long id)
{
    _db.Delete(_keyFactory.CreateKey(id));
}

Go

import (
	"context"
	"log"

	"cloud.google.com/go/datastore"
)

// DeleteTask deletes the task with the given ID.
func DeleteTask(projectID string, taskID int64) error {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectID)
	if err != nil {
		log.Fatalf("Could not create datastore client: %v", err)
	}
	return client.Delete(ctx, datastore.IDKey("Task", taskID, nil))
}

Java

/**
 * Deletes a task entity.
 *
 * @param id The ID of the task entity as given by {@link Key#id()}
 * @throws DatastoreException if the delete fails
 */
void deleteTask(long id) {
  datastore.delete(keyFactory.newKey(id));
}

Node.js

async function deleteTask(taskId) {
  const taskKey = datastore.key(['Task', datastore.int(taskId)]);

  await datastore.delete(taskKey);
  console.log(`Task ${taskId} deleted successfully.`);
}

PHP

use Google\Cloud\Datastore\DatastoreClient;

/**
 * Delete a task with a given id.
 *
 * @param string $projectId The Google Cloud project ID.
 * @param string $taskId
 */
function delete_task(string $projectId, string $taskId)
{
    $datastore = new DatastoreClient(['projectId' => $projectId]);

    $taskKey = $datastore->key('Task', $taskId);
    $datastore->delete($taskKey);

    printf('Task %d deleted successfully.' . PHP_EOL, $taskId);
}

Python

from google.cloud import datastore

def delete_task(client: datastore.Client, task_id: str | int):
    # Create a key for an entity of kind "Task", and with the supplied
    # `task_id` as its Id
    key = client.key("Task", task_id)
    # Use that key to delete its associated document, if it exists
    client.delete(key)

Ruby

def delete_task task_id
  require "google/cloud/datastore"

  datastore = Google::Cloud::Datastore.new

  task = datastore.find "Task", task_id

  datastore.delete task
end

Exécuter une requête

En plus de récupérer les entités à partir du mode Datastore directement à l'aide de leurs clés, une application peut exécuter une requête pour les extraire en fonction des valeurs de leurs propriétés. Une requête type comprend les éléments suivants :

Un genre d'entité auquel s'applique la requête.
Zéro, un ou plusieurs filtres, par exemple pour sélectionner des genres dont les propriétés correspondent à une valeur.
Zéro, un ou plusieurs ordres de tri, pour séquencer les résultats.

Pour cette application, nous allons interroger le mode Datastore pour obtenir les entités Task triées par date de création :

C#

/// <summary>
/// Returns a list of all task entities in ascending order of creation time.
/// </summary>
IEnumerable<Entity> ListTasks()
{
    Query query = new Query("Task")
    {
        Order = { { "created", PropertyOrder.Types.Direction.Descending } }
    };
    return _db.RunQuery(query).Entities;
}

Go

import (
	"context"
	"log"

	"cloud.google.com/go/datastore"
)

// ListTasks returns all the tasks in ascending order of creation time.
func ListTasks(projectID string) ([]*Task, error) {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectID)
	if err != nil {
		log.Fatalf("Could not create datastore client: %v", err)
	}

	var tasks []*Task
	// Create a query to fetch all Task entities, ordered by "created".
	query := datastore.NewQuery("Task").Order("created")
	keys, err := client.GetAll(ctx, query, &tasks)
	if err != nil {
		return nil, err
	}

	// Set the id field on each Task from the corresponding key.
	for i, key := range keys {
		tasks[i].id = key.ID
	}

	return tasks, nil
}

Java

/**
 * Returns a list of all task entities in ascending order of creation time.
 *
 * @throws DatastoreException if the query fails
 */
Iterator<Entity> listTasks() {
  Query<Entity> query =
      Query.newEntityQueryBuilder().setKind("Task").setOrderBy(OrderBy.asc("created")).build();
  return datastore.run(query);
}

Node.js

async function listTasks() {
  const query = datastore.createQuery('Task').order('created');

  const [tasks] = await datastore.runQuery(query);
  console.log('Tasks:');
  tasks.forEach(task => {
    const taskKey = task[datastore.KEY];
    console.log(taskKey.id, task);
  });
}

PHP

use Google\Cloud\Datastore\DatastoreClient;

/**
 * Return an iterator for all the tasks in ascending order of creation time.
 *
 * @param string $projectId The Google Cloud project ID.
 */
function list_tasks(string $projectId)
{
    $datastore = new DatastoreClient(['projectId' => $projectId]);

    $query = $datastore->query()
        ->kind('Task')
        ->order('created');
    $result = $datastore->runQuery($query);
    /* @var Entity $task */
    foreach ($result as $index => $task) {
        printf('ID: %s' . PHP_EOL, $task->key()->pathEnd()['id']);
        printf('  Description: %s' . PHP_EOL, $task['description']);
        printf('  Status: %s' . PHP_EOL, $task['done'] ? 'done' : 'created');
        printf('  Created: %s' . PHP_EOL, $task['created']->format('Y-m-d H:i:s e'));
        print(PHP_EOL);
    }
}

Python

from google.cloud import datastore

def list_tasks(client: datastore.Client):
    # Create a query against all of your objects of kind "Task"
    query = client.query(kind="Task")
    query.order = ["created"]

    return list(query.fetch())

Ruby

def list_tasks
  require "google/cloud/datastore"

  datastore = Google::Cloud::Datastore.new

  query = datastore.query("Task").order("created")
  tasks = datastore.run query

  tasks.each do |t|
    puts t["description"]
    puts t["done"] ? "  Done" : "  Not Done"
    puts "  ID: #{t.key.id}"
  end
end

Étapes suivantes

Ce tutoriel n'aborde que les étapes les plus élémentaires nécessaires pour appeler l'API en mode Datastore à partir d'une application de ligne de commande. Le mode Datastore est compatible avec les transactions ACID rapides et hautement évolutives, les requêtes de type SQL, les index, etc.

Consultez la page Qu'est-ce que Firestore en mode Datastore ? pour en savoir plus sur les fonctionnalités du mode Datastore.
Consultez la page Émulateur en mode Datastore pour savoir comment utiliser l'émulateur en mode Datastore lors du développement de votre application.