Hello World en Ruby

Esta muestra de código es una aplicación “hello world” que se ejecuta en Ruby. En este ejemplo, se muestra cómo completar las siguientes tareas:

• Configura la autenticación
• Conéctate a una instancia de Bigtable.
• Crear una tabla nueva
• Escribir datos en la tabla
• Volver a leer datos
• Borrar la tabla

Configura la autenticación

Para usar las muestras de Ruby incluidas en esta página en un entorno de desarrollo local, instala e inicializa la gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

Instala Google Cloud CLI.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

If you're using a local shell, then create local authentication credentials for your user account:

gcloud auth application-default login

You don't need to do this if you're using Cloud Shell.

If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

Para obtener más información, consulta Set up authentication for a local development environment.

Nota: Para ejecutar los siguientes ejemplos, asegúrate de que la cuenta autenticada tenga el rol de IAM de Administrador de Bigtable. Para obtener información sobre cómo otorgar roles a una cuenta, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Configura tu entorno

Para ejecutar este ejemplo, debes tener instalado Ruby.

1. Instala Ruby

Para verificar la versión mínima de Ruby requerida para la biblioteca cliente, consulta required_ruby_version en el archivo google-cloud-bigtable.gemspec.

Cómo configurar Ruby en una VM de Compute Engine

Si deseas ejecutar el ejemplo en una VM de Compute Engine, sigue estas instrucciones para configurar Ruby en una VM de Debian o Ubuntu.

1. En la consola de Google Cloud , ve a la página Instancias de VM.

   Ir a Instancias de VM

2. Si no tienes una VM de Linux que use el sistema operativo Debian o Ubuntu, crea una y conéctate a ella. Para obtener más información, consulta la Guía de inicio rápido para usar una VM de Linux.

3. En la ventana de la terminal de tu VM, actualiza las listas de paquetes:

   sudo apt update
   

4. Instala Ruby, las herramientas de desarrollo de Ruby y build-essential, que son necesarios para la biblioteca cliente:

   sudo apt install -y ruby ruby-dev build-essential
   

5. Verifica que la versión de Ruby instalada cumpla con el requisito mínimo especificado en el archivo google-cloud-bigtable.gemspec:

   ruby --version
   

2. Instala la biblioteca cliente

Para instalar la biblioteca cliente, haz lo siguiente:

1. Inicializa Bundler para crear un archivo Gemfile en el directorio raíz de tu proyecto:

   bundle init
   

2. Agrega google-cloud-bigtable a tu Gemfile y, luego, instálalo:

   bundle add google-cloud-bigtable
   

Para obtener más información sobre la biblioteca cliente, consulta el archivo README de google-cloud-bigtable.

Ejecuta la muestra

En esta muestra de código, se usa el paquete de la biblioteca cliente de Ruby para Bigtable de la biblioteca cliente de Google Cloud para Ruby a fin de comunicarse con Bigtable.

Para ejecutar el programa de muestra, sigue las instrucciones que se indican en GitHub.

Usa la biblioteca cliente de Cloud con Bigtable

La aplicación de muestra se conecta con Bigtable y demuestra algunas operaciones simples.

Requisitos de la biblioteca cliente

La muestra necesita google/cloud/bigtable, que proporciona el módulo Bigtable.

require "google/cloud/bigtable"

Conéctate a Bigtable

Establece las variables que usarás en tu aplicación y reemplaza "YOUR_PROJECT_ID" por el ID de un proyecto Google Cloud válido. Luego, crea un objeto Bigtable nuevo, que usarás para conectarte a Bigtable.

# These variables are used in the sample code below.
# instance_id      = "my-instance"
# table_id         = "my-table"
# column_family    = "cf"
# column_qualifier = "greeting"

bigtable = Google::Cloud::Bigtable.new
table_client = bigtable.table_admin_client

Crea una tabla

Comprueba si tu tabla ya existe. Si no es así, llama al método create_table() para crear un objeto Table. La tabla tiene una sola familia de columnas, que contiene una versión de cada valor.

Nota: Las columnas que se relacionan entre sí se suelen agrupar en una familia de columnas. Para obtener más información sobre las familias de columnas, consulta el modelo de almacenamiento de Bigtable.

# This is the full resource name for the table. Use this name to make admin
# calls for the table, such as reading or deleting the resource.
table_name = table_client.table_path project: bigtable.project_id,
                                     instance: instance_id,
                                     table: table_id
begin
  # Attempt to get the table to see if it already exists
  table_client.get_table name: table_name
  puts "#{table_id} is already exists."
  exit 0
rescue Google::Cloud::NotFoundError
  # The table doesn't exist, so let's create it.
  # The following is the resource name for the table's instance.
  instance_name = table_client.instance_path project: bigtable.project_id,
                                             instance: instance_id
  # This is the configuration of the table's column families.
  table_config = {
    column_families: {
      column_family => {
        gc_rule: Google::Cloud::Bigtable::Admin::V2::GcRule.max_num_versions(1)
      }
    }
  }
  # Now call the API to create the table.
  table_client.create_table parent: instance_name,
                            table_id: table_id,
                            table: table_config
  puts "Table #{table_id} created."
end

Escribe filas en una tabla

A continuación, usa un arreglo de strings de saludos a fin de crear algunas filas nuevas para la tabla. Por cada saludo, crea una entrada con el método new_mutation_entry() de la tabla. A continuación, usa el método set_cell() de la entrada para asignar la familia de columnas, el calificador de columna, el saludo y una marca de tiempo a la entrada. Por último, escribe la entrada en la tabla usando el método mutate_row() de la tabla.

Nota: En esta aplicación de ejemplo, set_Cell() solo se llama una vez por mutación, pero puedes llamarla hasta 10,000 veces por cada una.

puts "Write some greetings to the table #{table_id}"
greetings = ["Hello World!", "Hello Bigtable!", "Hello Ruby!"]

# Get a table data object for the new table we created.
table = bigtable.table instance_id, table_id

# Insert rows one by one
# Note: To perform multiple mutation on multiple rows use `mutate_rows`.
greetings.each_with_index do |value, i|
  puts " Writing,  Row key: greeting#{i}, Value: #{value}"

  entry = table.new_mutation_entry "greeting#{i}"
  entry.set_cell(
    column_family,
    column_qualifier,
    value,
    timestamp: (Time.now.to_f * 1_000_000).round(-3)
  )

  table.mutate_row entry
end

Crea un filtro

Antes de leer los datos que escribiste, crea un filtro para limitar los datos que muestre Bigtable. El filtro le indica a Bigtable que muestre solo la versión más reciente de cada valor, incluso si la tabla contiene versiones anteriores que no pasaron por el proceso de recolección de elementos no utilizados.

# Only retrieve the most recent version of the cell.
filter = Google::Cloud::Bigtable::RowFilter.cells_per_column 1

Lee una fila por su clave de fila

Crea un objeto de fila, llama al método read_row() y, luego, aplica el filtro para obtener una versión de cada valor de la fila.

puts "Reading a single row by row key"
row = table.read_row "greeting0", filter: filter
puts "Row key: #{row.key}, Value: #{row.cells[column_family].first.value}"

Analiza todas las filas de una tabla

Llama al método read_rows() y aplica el filtro para pasar todas las filas de la tabla. Dado que aplicaste el filtro, Bigtable solo mostrará una versión de cada valor.

puts "Reading the entire table"
table.read_rows.each do |row|
  puts "Row key: #{row.key}, Value: #{row.cells[column_family].first.value}"
end

Borra una tabla

Borra la tabla con el método delete().

puts "Deleting the table #{table_id}"
# Call the admin API to delete the table given its full resource path.
table_client.delete_table name: table_name

Revisión general

El código de muestra completo sin comentarios.

# Copyright 2021 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

def hello_world instance_id, table_id, column_family, column_qualifier
  require "google/cloud/bigtable"

  # These variables are used in the sample code below.
  # instance_id      = "my-instance"
  # table_id         = "my-table"
  # column_family    = "cf"
  # column_qualifier = "greeting"

  bigtable = Google::Cloud::Bigtable.new
  table_client = bigtable.table_admin_client

  # This is the full resource name for the table. Use this name to make admin
  # calls for the table, such as reading or deleting the resource.
  table_name = table_client.table_path project: bigtable.project_id,
                                       instance: instance_id,
                                       table: table_id
  begin
    # Attempt to get the table to see if it already exists
    table_client.get_table name: table_name
    puts "#{table_id} is already exists."
    exit 0
  rescue Google::Cloud::NotFoundError
    # The table doesn't exist, so let's create it.
    # The following is the resource name for the table's instance.
    instance_name = table_client.instance_path project: bigtable.project_id,
                                               instance: instance_id
    # This is the configuration of the table's column families.
    table_config = {
      column_families: {
        column_family => {
          gc_rule: Google::Cloud::Bigtable::Admin::V2::GcRule.max_num_versions(1)
        }
      }
    }
    # Now call the API to create the table.
    table_client.create_table parent: instance_name,
                              table_id: table_id,
                              table: table_config
    puts "Table #{table_id} created."
  end

  puts "Write some greetings to the table #{table_id}"
  greetings = ["Hello World!", "Hello Bigtable!", "Hello Ruby!"]

  # Get a table data object for the new table we created.
  table = bigtable.table instance_id, table_id

  # Insert rows one by one
  # Note: To perform multiple mutation on multiple rows use `mutate_rows`.
  greetings.each_with_index do |value, i|
    puts " Writing,  Row key: greeting#{i}, Value: #{value}"

    entry = table.new_mutation_entry "greeting#{i}"
    entry.set_cell(
      column_family,
      column_qualifier,
      value,
      timestamp: (Time.now.to_f * 1_000_000).round(-3)
    )

    table.mutate_row entry
  end

  # Only retrieve the most recent version of the cell.
  filter = Google::Cloud::Bigtable::RowFilter.cells_per_column 1

  puts "Reading a single row by row key"
  row = table.read_row "greeting0", filter: filter
  puts "Row key: #{row.key}, Value: #{row.cells[column_family].first.value}"

  puts "Reading the entire table"
  table.read_rows.each do |row|
    puts "Row key: #{row.key}, Value: #{row.cells[column_family].first.value}"
  end

  puts "Deleting the table #{table_id}"
  # Call the admin API to delete the table given its full resource path.
  table_client.delete_table name: table_name
end