Esta página foi traduzida pela API Cloud Translation.

Começar a usar a API Firestore no modo Datastore

Esta página oferece um breve exercício de criação de uma aplicação TaskList de linha de comandos com a API Firestore no modo Datastore. A aplicação TaskList armazena, atualiza e remove tarefas.

Pré-requisitos

Capacidade de escrever e executar uma aplicação de linha de comandos nas linguagens de programação usadas neste tópico
Além de uma compreensão básica de como desenvolver aplicações, deve poder transferir e instalar bibliotecas adicionais antes de tentar este tutorial.
Um Google Cloud projeto com a API do modo Datastore ativada
As aplicações que usam o modo Datastore estão associadas a um Google Cloud projeto com a API do modo Datastore ativada. Este projeto fornece credenciais de autenticação que usa na sua aplicação para a identificar junto da Google e autorizar a respetiva utilização da API do modo Datastore.
Siga estas instruções para criar um projeto, ativar a API Google Cloud Datastore no modo Datastore e configurar o seu ambiente de desenvolvimento local com credenciais de autenticação através do comando gcloud auth login. Tome nota do ID do projeto, que vai usar mais tarde.

Instalação e configuração

Instale bibliotecas cliente e configure quaisquer definições adicionais para o seu ambiente de desenvolvimento.

C#

Certifique-se de que tem o Visual Studio (versão 2013 ou posterior) instalado.
Transfira a aplicação de exemplo TaskList a partir do repositório de exemplos.
Extraia os ficheiros do ficheiro ZIP para um diretório na pasta Documentos.
No Visual Studio, abra o ficheiro dotnet-docs-samples-master\datastore\api\Datastore.sln.
Na janela Solution Explorer do Visual Studio, clique com o botão direito do rato no projeto TaskList e escolha Set as StartUp Project.
Clique novamente com o botão direito do rato no projeto TaskList e escolha Propriedades.
Na janela Propriedades, clique em Depurar e escreva o ID do seu Google Cloud projeto na caixa Argumentos da linha de comandos:.
Clique em Ficheiro e, de seguida, em Guardar para guardar as alterações.
Execute a aplicação! Prima F5 no teclado.

Ir

Clone a aplicação de exemplo TaskList.

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

Altere os diretórios para onde clonou o exemplo:

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

Num comando, execute o seguinte, onde <project-id> é o ID do seu Google Cloud projeto.
```
export DATASTORE_PROJECT_ID=<project-id>
```
(Utilizadores do Windows: use set em vez de export.)
Execute a aplicação!
```
go run tasks.go
```

Java

Certifique-se de que tem o Maven e o Java (versão 8 ou posterior) instalados.
Transfira a aplicação de exemplo TaskList a partir do repositório de exemplos.
Numa linha de comandos, extraia a transferência:
```
unzip main.zip
```
Altere os diretórios para a aplicação TaskList:
```
cd java-datastore-main/samples/snippets
```
Execute o seguinte comando, em que <project-id> é o ID do seu Google Cloud projeto.
```
gcloud config set project <project-id>
```

Compile e execute a aplicação!

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

Node.js

Prepare o seu ambiente para o desenvolvimento de Node.js.
Transfira a aplicação de exemplo TaskList a partir do repositório de exemplos.
Extraia a transferência:
```
unzip master.zip
```
Altere os diretórios para a aplicação TaskList:
```
cd nodejs-datastore-master/samples
```
Instale as dependências e associe a aplicação:
```
npm install
```
Num comando, execute o seguinte, onde <project-id> é o ID do seu Google Cloud projeto.
```
export GCLOUD_PROJECT=<project-id>
```
(Utilizadores do Windows: use set em vez de export.)
Execute a aplicação!
```
node tasks.js
```

PHP

Certifique-se de que tem o PHP (versão 5.6 ou posterior) e o Composer instalados.
Transfira a aplicação de exemplo TaskList a partir do repositório de exemplos.
Extraia a transferência:
```
unzip master.zip
```
Altere os diretórios para a aplicação TaskList:
```
cd php-docs-samples-master/datastore/tutorial
```
Instale dependências.
```
composer install
```
Execute a aplicação!
```
php src/list_tasks.php
```

Python

Certifique-se de que tem o Python (versão 2.7.9 ou posterior), o pip e o virtualenv instalados.

Ative uma sessão do virtualenv.

virtualenv venv
source venv/bin/activate

Transfira a aplicação de exemplo TaskList a partir do repositório de exemplos.
Extraia a transferência:
```
unzip master.zip
```

Altere os diretórios para a aplicação TaskList:

cd python-docs-samples-master/datastore/cloud-client

Instalar dependências:
```
pip install -r requirements.txt
```
Execute a aplicação! Use o ID do seu Google Cloud projeto para <project-id>.
```
python tasks.py new project-id
```

Ruby

Certifique-se de que tem o Ruby e o Bundler instalados.
Transfira a aplicação de exemplo TaskList a partir do repositório de exemplos.
Extraia a transferência:
```
unzip master.zip
```

Altere os diretórios para a aplicação TaskList:

cd google-cloud-ruby-master/google-cloud-datastore/samples

Instale as dependências:
```
bundle install
```
Num comando, execute o seguinte, onde <project-id> é o ID do seu Google Cloud projeto.
```
export GOOGLE_CLOUD_PROJECT=<project-id>
```
(Utilizadores do Windows: use set em vez de export.)
Execute a aplicação!
```
bundle exec ruby tasks.rb
```

Criar um objeto de serviço autorizado

Para fazer pedidos autenticados às Google Cloud APIs através das bibliotecas cliente das APIs Google, tem de:

Obtenha a credencial a usar para pedidos.
Crie um objeto de serviço que use essa credencial.

Em seguida, pode fazer chamadas API chamando métodos no objeto de serviço do modo Datastore.

Para este exemplo, vai obter as credenciais padrão da aplicação do ambiente e transmiti-las como um argumento para criar o objeto de serviço.

Segue-se a chamada para criar o objeto de serviço do modo Datastore autorizado:

C#

Para saber como instalar e usar a biblioteca cliente do Cloud Datastore, consulte as bibliotecas cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# Cloud Datastore.

Para se autenticar no Cloud Datastore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento 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

Armazenamento de dados

Os objetos no modo Datastore são conhecidos como entidades e cada entidade é de um tipo específico. A aplicação TaskList armazena entidades do tipo Task com as seguintes propriedades:

description: uma string especificada pelo utilizador como a descrição da tarefa
created: uma data que mostra quando a tarefa foi criada inicialmente
done: um valor booleano que indica se a tarefa foi concluída

Quando o utilizador adiciona uma nova tarefa, a aplicação TaskList cria uma entidade com valores para as propriedades indicadas anteriormente:Task

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

Para esta aplicação, também disponibilizamos um método para atualizar a propriedade, de modo a indicar que a tarefa está concluída:done

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

Veja o método para eliminar uma entidade Task, usando a chave da entidade Task:

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

Executar uma consulta

Além de obter entidades do modo Datastore diretamente pelas respetivas chaves, uma aplicação pode executar uma consulta para as obter pelos valores das respetivas propriedades. Uma consulta típica inclui o seguinte:

Um tipo de entidade ao qual a consulta se aplica
Zero ou mais filtros, por exemplo, para selecionar tipos cujas propriedades correspondam a um valor
Zero ou mais ordens de ordenação para sequenciar os resultados

Para esta aplicação, vamos consultar o modo Datastore para entidades Task ordenadas por hora de criação:

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

Passos seguintes

Este tutorial abrange apenas os passos mais básicos necessários para fazer chamadas para a API do modo Datastore a partir de uma aplicação de linha de comandos. O modo Datastore suporta transações ACID rápidas e altamente escaláveis, consultas semelhantes a SQL, índices e muito mais.

Para uma análise mais detalhada das capacidades do modo Datastore, consulte o artigo O que é o Firestore no modo Datastore?.
Para obter informações sobre a utilização do emulador do modo Datastore enquanto desenvolve a sua aplicação, consulte o emulador do modo Datastore.

Começar a usar a API Firestore no modo Datastore Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Pré-requisitos

Instalação e configuração

C#

Ir

Java

Node.js

PHP

Python

Ruby

Criar um objeto de serviço autorizado

C#

Go

Java

Node.js

PHP

Python

Ruby

Armazenamento de dados

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

Executar uma consulta

C#

Go

Java

Node.js

PHP

Python

Ruby

Passos seguintes

Começar a usar a API Firestore no modo Datastore