Ruby 版 Hello World

本代码示例是一个在 Ruby 上运行的“hello world”应用，其中演示了如何完成以下任务：

  • 设置身份验证
  • 连接到 Bigtable 实例。
  • 新建一个表。
  • 将数据写入表中。
  • 重新读取这些数据。
  • 删除表。

设置身份验证

如需在本地开发环境中使用本页面上的 Ruby 示例，请安装并初始化 gcloud CLI，然后使用您的用户凭据设置应用默认凭据。

  1. 安装 Google Cloud CLI。

  2. 如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

  3. 如果您使用的是本地 shell，请为您的用户账号创建本地身份验证凭证： 

    gcloud auth application-default login

    如果您使用的是 Cloud Shell，则无需执行此操作。

    如果系统返回身份验证错误，并且您使用的是外部身份提供方 (IdP)，请确认您已 使用联合身份登录 gcloud CLI。

如需了解详情，请参阅 为本地开发环境设置身份验证。

设置环境

如需运行此示例，您需要安装 Ruby。

1. 安装 Ruby

如需查看客户端库所需的最低 Ruby 版本，请参阅 google-cloud-bigtable.gemspec 文件中的 required_ruby_version。

在 Compute Engine 虚拟机上设置 Ruby 如果您想在 Compute Engine 虚拟机上运行示例，请按照以下说明在 Debian 或 Ubuntu 虚拟机上设置 Ruby。

  1. 在 Google Cloud 控制台中，转到虚拟机实例页面。

    转到虚拟机实例

  2. 如果您没有使用 Debian 或 Ubuntu 操作系统的 Linux 虚拟机，请创建一个并连接到该虚拟机。如需了解详情，请参阅快速入门：使用 Linux 虚拟机。

  3. 在虚拟机的终端窗口中，更新软件包列表：

    sudo apt update

  4. 安装 Ruby、Ruby 开发工具和客户端库所需的 build-essential：

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

  5. 验证已安装的 Ruby 版本是否符合 google-cloud-bigtable.gemspec 文件中指定的最低要求：

    ruby --version

2. 安装客户端库

如需安装客户端库，请执行以下操作：

  1. 初始化 bundler 以在项目的根目录中创建 Gemfile：

    bundle init

  2. 将 google-cloud-bigtable 添加到 Gemfile 并安装：

    bundle add google-cloud-bigtable

如需详细了解客户端库，请参阅 google-cloud-bigtable README。

运行示例

此代码示例使用 Ruby 版 Google Cloud 客户端库的适用于 Bigtable 的 Ruby 客户端库软件包与 Bigtable 通信。

要运行此示例程序，请按照 GitHub 上的相应示例说明执行操作。

将 Cloud 客户端库与 Bigtable 搭配使用

示例应用会连接到 Bigtable 并演示一些简单操作。

需要客户端库

该示例需要使用 google/cloud/bigtable，其中提供了 Bigtable 模块。

require "google/cloud/bigtable"

连接到 Bigtable

建立您要在应用中使用的变量，并将“YOUR_PROJECT_ID”替换为有效 Google Cloud 项目的 ID。然后，创建一个新的 Bigtable 对象，您将使用此对象连接到 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

创建表

检查您的表是否已存在。如果不存在，请调用 create_table() 方法来创建一个 Table 对象。该表有一个列族，其中保留了每个值的一个版本。

# 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

将行写入表

接下来，使用由问候语组成的字符串数组来为表创建一些新行。对于每条问候语，使用表的 new_mutation_entry() 方法创建一个条目。然后，使用条目的 set_cell() 方法为该条目分配列族、列限定符、问候语和时间戳。最后，使用表的 mutate_row() 方法将该条目写入表中。

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

创建过滤条件

在读取您写入的数据之前，请创建过滤条件，以限制 Bigtable 返回的数据。此过滤条件指示 Bigtable 仅返回每个值的最新版本，即使该表包含尚未被垃圾回收的旧版本。

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

按行键读取行

创建一个行对象，然后调用 read_row() 方法并传入过滤条件，以获取该行中每个值的一个版本。

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}"

扫描所有表行

调用 read_rows() 方法并传入过滤条件，以获取表中的所有行。由于您传入了过滤条件，因此 Bigtable 仅会返回每个值的一个版本。

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

删除表

使用表的 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

综合应用

以下为不包含注释的完整代码示例。

# 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