google-cloud-bigtable 1.0.2 → 1.3.0

data/lib/google/cloud/bigtable/service.rb

@@ -640,6 +640,58 @@ module Google
           end
         end
 
+        ##
+        # Gets the access control policy for an table resource. Returns an empty
+        # policy if an table exists but does not have a policy set.
+        #
+        # @param table_id [String]
+        #   Unique ID of the table for which the policy is being requested.
+        # @return [Google::Iam::V1::Policy]
+        #
+        def get_table_policy instance_id, table_id
+          execute do
+            tables.get_iam_policy table_path(instance_id, table_id)
+          end
+        end
+
+        ##
+        # Sets the access control policy on an table resource. Replaces any
+        # existing policy.
+        #
+        # @param table_id [String]
+        #   Unique ID of the table the policy is for.
+        # @param policy [Google::Iam::V1::Policy | Hash]
+        #   REQUIRED: The complete policy to be applied to the +resource+. The size of
+        #   the policy is limited to a few 10s of KB. An empty policy is valid
+        #   for Cloud Bigtable, but certain Cloud Platform services (such as Projects)
+        #   might reject an empty policy.
+        #   Alternatively, provide a hash similar to `Google::Iam::V1::Policy`.
+        # @return [Google::Iam::V1::Policy]
+        #
+        def set_table_policy instance_id, table_id, policy
+          execute do
+            tables.set_iam_policy table_path(instance_id, table_id), policy
+          end
+        end
+
+        ##
+        # Returns permissions that the caller has for the specified table resource.
+        #
+        # @param table_id [String]
+        #   The table ID that the policy detail is being requested for.
+        # @param permissions [Array<String>]
+        #   The set of permissions to check for the +resource+. Permissions with
+        #   wildcards (such as '*' or 'storage.*') are not allowed. For more
+        #   information see
+        #   [IAM Overview](https://cloud.google.com/iam/docs/overview#permissions).
+        # @return [Google::Iam::V1::TestIamPermissionsResponse]
+        #
+        def test_table_permissions instance_id, table_id, permissions
+          execute do
+            tables.test_iam_permissions table_path(instance_id, table_id), permissions
+          end
+        end
+
         def read_rows instance_id, table_id, app_profile_id: nil, rows: nil, filter: nil, rows_limit: nil
           # execute is not used because error handling is in ReadOperations#read_rows
           client.read_rows table_path(instance_id, table_id),
@@ -682,6 +734,75 @@ module Google
           end
         end
 
+        ##
+        # Starts creating a new backup. The underlying Google::Longrunning::Operation tracks creation of the backup.
+        #
+        # @return [Google::Gax::Operation]
+        #
+        def create_backup instance_id:, cluster_id:, backup_id:, source_table_id:, expire_time:
+          backup = Google::Bigtable::Admin::V2::Backup.new source_table: table_path(instance_id, source_table_id),
+                                                           expire_time:  expire_time
+          execute do
+            tables.create_backup cluster_path(instance_id, cluster_id), backup_id, backup
+          end
+        end
+
+        ##
+        # @return [Google::Bigtable::Admin::V2::Backup]
+        #
+        def get_backup instance_id, cluster_id, backup_id
+          execute do
+            tables.get_backup backup_path(instance_id, cluster_id, backup_id)
+          end
+        end
+
+        ##
+        # @return [Google::Gax::PagedEnumerable<Google::Bigtable::Admin::V2::Backup>]
+        #
+        def list_backups instance_id, cluster_id
+          execute do
+            tables.list_backups cluster_path(instance_id, cluster_id)
+          end
+        end
+
+        ##
+        # @param backup [Google::Bigtable::Admin::V2::Backup | Hash]
+        # @param fields [Array(String|Symbol)] the paths of fields to be updated
+        #
+        def update_backup backup, fields
+          mask = Google::Protobuf::FieldMask.new paths: fields.map(&:to_s)
+          execute do
+            tables.update_backup backup, mask
+          end
+        end
+
+        def delete_backup instance_id, cluster_id, backup_id
+          execute do
+            tables.delete_backup backup_path(instance_id, cluster_id, backup_id)
+          end
+        end
+
+        ##
+        # Create a new table by restoring from a completed backup.
+        #
+        # @param table_id [String] The table ID for the new table. This table must not yet exist.
+        # @param instance_id [String] The instance ID for the source backup. The table will be created in this instance.
+        # @param cluster_id [String] The cluster ID for the source backup.
+        # @param backup_id [String] The backup ID for the source backup.
+        #
+        # @return [Google::Gax::Operation] The {Google::Longrunning::Operation#metadata metadata} field type is
+        #   {Google::Bigtable::Admin::RestoreTableMetadata RestoreTableMetadata}. The
+        #   {Google::Longrunning::Operation#response response} type is {Google::Bigtable::Admin::V2::Table Table}, if
+        #   successful.
+        #
+        def restore_table table_id, instance_id, cluster_id, backup_id
+          execute do
+            tables.restore_table instance_path(instance_id),
+                                 table_id: table_id,
+                                 backup:   backup_path(instance_id, cluster_id, backup_id)
+          end
+        end
+
         ##
         # Executes the API call and wrap errors to {Google::Cloud::Error}.
         #
@@ -769,6 +890,16 @@ module Google
           Admin::V2::BigtableInstanceAdminClient.app_profile_path project_id, instance_id, app_profile_id
         end
 
+        ##
+        # Creates a formatted backup path.
+        #
+        # @return [String] Formatted backup path
+        #   `projects/<project>/instances/<instance>/clusters/<cluster>/backups/<backup>`
+        #
+        def backup_path instance_id, cluster_id, backup_id
+          Admin::V2::BigtableTableAdminClient.backup_path project_id, instance_id, cluster_id, backup_id
+        end
+
         ##
         # Inspects the service object.
         # @return [String]

data/lib/google/cloud/bigtable/table.rb

@@ -20,6 +20,7 @@ require "google/cloud/bigtable/table/cluster_state"
 require "google/cloud/bigtable/column_family_map"
 require "google/cloud/bigtable/gc_rule"
 require "google/cloud/bigtable/mutation_operations"
+require "google/cloud/bigtable/policy"
 require "google/cloud/bigtable/read_operations"
 
 module Google
@@ -239,6 +240,117 @@ module Google
           granularity == :MILLIS
         end
 
+        ##
+        # Gets the [Cloud IAM](https://cloud.google.com/iam/) access control
+        # policy for the table.
+        #
+        # @see https://cloud.google.com/bigtable/docs/access-control
+        #
+        # @yield [policy] A block for updating the policy. The latest policy
+        #   will be read from the Bigtable service and passed to the block. After
+        #   the block completes, the modified policy will be written to the
+        #   service.
+        # @yieldparam [Policy] policy the current Cloud IAM Policy for this
+        #   table.
+        #
+        # @return [Policy] The current Cloud IAM Policy for the table.
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.table("my-instance", "my-table", perform_lookup: true)
+        #   policy = table.policy
+        #
+        # @example Update the policy by passing a block.
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.table("my-instance", "my-table", perform_lookup: true)
+        #
+        #   table.policy do |p|
+        #     p.add("roles/owner", "user:owner@example.com")
+        #   end # 2 API calls
+        #
+        def policy
+          ensure_service!
+          grpc = service.get_table_policy instance_id, name
+          policy = Policy.from_grpc grpc
+          return policy unless block_given?
+          yield policy
+          update_policy policy
+        end
+
+        ##
+        # Updates the [Cloud IAM](https://cloud.google.com/iam/) access control
+        # policy for the table. The policy should be read from {#policy}.
+        # See {Google::Cloud::Bigtable::Policy} for an explanation of the policy
+        # `etag` property and how to modify policies.
+        #
+        # You can also update the policy by passing a block to {#policy}, which
+        # will call this method internally after the block completes.
+        #
+        # @param new_policy [Policy] a new or modified Cloud IAM Policy for this
+        #   table
+        #
+        # @return [Policy] The policy returned by the API update operation.
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.table("my-instance", "my-table", perform_lookup: true)
+        #
+        #   policy = table.policy
+        #   policy.add("roles/owner", "user:owner@example.com")
+        #   updated_policy = table.update_policy(policy)
+        #
+        #   puts updated_policy.roles
+        #
+        def update_policy new_policy
+          ensure_service!
+          grpc = service.set_table_policy instance_id, name, new_policy.to_grpc
+          Policy.from_grpc grpc
+        end
+        alias policy= update_policy
+
+        ##
+        # Tests the specified permissions against the [Cloud
+        # IAM](https://cloud.google.com/iam/) access control policy.
+        #
+        # @see https://cloud.google.com/iam/docs/managing-policies Managing Policies
+        # @see https://cloud.google.com/bigtable/docs/access-control Access Control
+        #
+        # @param permissions [String, Array<String>] permissions The set of permissions to
+        #   check access for. Permissions with wildcards (such as `*` or
+        #   `bigtable.*`) are not allowed.
+        #   See [Access Control](https://cloud.google.com/bigtable/docs/access-control).
+        #
+        # @return [Array<String>] The permissions that are configured for the policy.
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.table("my-instance", "my-table", perform_lookup: true)
+        #
+        #   permissions = table.test_iam_permissions(
+        #     "bigtable.tables.delete",
+        #     "bigtable.tables.get"
+        #   )
+        #   permissions.include? "bigtable.tables.delete" #=> false
+        #   permissions.include? "bigtable.tables.get" #=> true
+        #
+        def test_iam_permissions *permissions
+          ensure_service!
+          grpc = service.test_table_permissions instance_id, name, permissions.flatten
+          grpc.permissions.to_a
+        end
+
         ##
         # Permanently deletes the table from a instance.
         #

data/lib/google/cloud/bigtable/table/cluster_state.rb

@@ -21,6 +21,8 @@ module Google
       class Table
         ##
         # Table::ClusterState is the state of a table's data in a particular cluster.
+        #
+        # @attr [String] cluster_name The name of the cluster.
         class ClusterState
           attr_reader :cluster_name
 
@@ -39,6 +41,10 @@ module Google
           #   * `:PLANNED_MAINTENANCE` - The table is temporarily unable to serve.
           #   * `:UNPLANNED_MAINTENANCE` - The table is temporarily unable to serve.
           #   * `:READY` - The table can serve.
+          #   * `:READY_OPTIMIZING` - The table is fully created and ready for use
+          #     after a restore, and is being optimized for performance. When
+          #     optimizations are complete, the table will transition to `READY`
+          #     state.
           #
           # @return [Symbol] The state of replication.
           #
@@ -51,7 +57,7 @@ module Google
           # over pre-existing data from other clusters before it can begin
           # receiving live replication updates and serving.
           #
-          # @return [Boolean] `true` if the cluster is initializing.
+          # @return [Boolean] `true` if the table in this cluster is initializing.
           #
           def initializing?
             replication_state == :INITIALIZING
@@ -61,7 +67,8 @@ module Google
           # The table is temporarily unable to serve
           # requests from this cluster due to planned internal maintenance.
           #
-          # @return [Boolean] `true` if the cluster is in planned maintenance.
+          # @return [Boolean] `true` if the table in this cluster is in planned
+          #   maintenance.
           #
           def planned_maintenance?
             replication_state == :PLANNED_MAINTENANCE
@@ -71,7 +78,8 @@ module Google
           # The table is temporarily unable to serve requests from this
           # cluster due to unplanned or emergency maintenance.
           #
-          # @return [Boolean] `true` if the cluster is in unplanned maintenance.
+          # @return [Boolean] `true` if the table in this cluster is in unplanned
+          #   maintenance.
           #
           def unplanned_maintenance?
             replication_state == :UNPLANNED_MAINTENANCE
@@ -82,12 +90,25 @@ module Google
           # Depending on replication delay, reads may not immediately
           # reflect the state of the table in other clusters.
           #
-          # @return [Boolean] `true` if the cluster is ready.
+          # @return [Boolean] `true` if the table in this cluster is ready.
           #
           def ready?
             replication_state == :READY
           end
 
+          ##
+          # The table is fully created and ready for use after a
+          # restore, and is being optimized for performance. When
+          # optimizations are complete, the table will transition to `READY`
+          # state.
+          #
+          # @return [Boolean] `true` if the table in this cluster is being
+          #   optimized.
+          #
+          def ready_optimizing?
+            replication_state == :READY_OPTIMIZING
+          end
+
           # @private
           # New Table::ClusterState from a Google::Bigtable::Admin::V2::Table::ClusterState object.
           # @param grpc [Google::Bigtable::Admin::V2::Table::ClusterState]

data/lib/google/cloud/bigtable/table/list.rb

@@ -94,7 +94,7 @@ module Google
           # @yield [table] The block for accessing each table instance.
           # @yieldparam [Table] table The table instance object.
           #
-          # @return [Enumerator]
+          # @return [Enumerator,nil] An enumerator is returned if no block is given, otherwise `nil`.
           #
           # @example Iterating each table by passing a block:
           #   require "google/cloud/bigtable"

data/lib/google/cloud/bigtable/table/restore_job.rb

@@ -0,0 +1,117 @@
+# Copyright 2020 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
+#
+#     https://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.
+
+
+module Google
+  module Cloud
+    module Bigtable
+      class Table
+        ##
+        # # RestoreJob
+        #
+        # A resource representing the long-running, asynchronous processing of a backup restore operation. The
+        # job can be refreshed to retrieve the table object once the operation has been completed.
+        #
+        # See {Backup#restore}.
+        #
+        # @see https://cloud.google.com/bigtable/docs/reference/admin/rpc/google.longrunning#google.longrunning.Operation
+        #   Long-running Operation
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   instance = bigtable.instance("my-instance")
+        #   cluster = instance.cluster("my-cluster")
+        #
+        #   backup = cluster.backup("my-backup")
+        #
+        #   job = backup.restore("my-new-table")
+        #
+        #   job.wait_until_done!
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     table = job.table
+        #     optimized = job.optimize_table_operation_name
+        #   end
+        #
+        class RestoreJob < LongrunningJob
+          ##
+          # The optimize table operation name from operation metadata.
+          #
+          # @return [String, nil] The optimize table operation name, or `nil` if the optimize table operation is not
+          #   complete.
+          #
+          # @example
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #   instance = bigtable.instance("my-instance")
+          #   cluster = instance.cluster("my-cluster")
+          #
+          #   backup = cluster.backup("my-backup")
+          #
+          #   job = backup.restore("my-new-table")
+          #
+          #   job.wait_until_done!
+          #   job.done? #=> true
+          #
+          #   if job.error?
+          #     status = job.error
+          #   else
+          #     table = job.table
+          #     optimized = job.optimize_table_operation_name
+          #   end
+          #
+          def optimize_table_operation_name
+            metadata.optimize_table_operation_name
+          end
+
+          ##
+          # Gets the table object from operation results.
+          #
+          # @return [Google::Cloud::Bigtable::Table, nil] The table instance, or `nil` if the operation is not complete.
+          #
+          # @example
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #   instance = bigtable.instance("my-instance")
+          #   cluster = instance.cluster("my-cluster")
+          #
+          #   backup = cluster.backup("my-backup")
+          #
+          #   job = backup.restore("my-new-table")
+          #
+          #   job.wait_until_done!
+          #   job.done? #=> true
+          #
+          #   if job.error?
+          #     status = job.error
+          #   else
+          #     table = job.table
+          #     optimized = job.optimize_table_operation_name
+          #   end
+          #
+          def table
+            Table.from_grpc results, service if results
+          end
+        end
+      end
+    end
+  end
+end