google-cloud-bigquery 1.12.0 → 1.38.1

data/lib/google/cloud/bigquery/dataset/access.rb

@@ -35,7 +35,7 @@ module Google
         #     access.add_owner_group "owners@example.com"
         #     access.add_writer_user "writer@example.com"
         #     access.remove_writer_user "readers@example.com"
-        #     access.add_reader_special :all
+        #     access.add_reader_special :all_users
         #   end
         #
         class Access
@@ -48,16 +48,19 @@ module Google
 
           # @private
           SCOPES = {
-            "user"           => :user_by_email,
-            "user_by_email"  => :user_by_email,
-            "userByEmail"    => :user_by_email,
+            "domain"         => :domain,
             "group"          => :group_by_email,
             "group_by_email" => :group_by_email,
             "groupByEmail"   => :group_by_email,
-            "domain"         => :domain,
+            "iam_member"     => :iam_member,
+            "iamMember"      => :iam_member,
+            "routine"        => :routine,
             "special"        => :special_group,
             "special_group"  => :special_group,
             "specialGroup"   => :special_group,
+            "user"           => :user_by_email,
+            "user_by_email"  => :user_by_email,
+            "userByEmail"    => :user_by_email,
             "view"           => :view
           }.freeze
 
@@ -74,7 +77,9 @@ module Google
             "projectWriters"          => "projectWriters",
             "all"                     => "allAuthenticatedUsers",
             "all_authenticated_users" => "allAuthenticatedUsers",
-            "allAuthenticatedUsers"   => "allAuthenticatedUsers"
+            "allAuthenticatedUsers"   => "allAuthenticatedUsers",
+            "all_users"               => "allUsers",
+            "allUsers"                => "allUsers"
           }.freeze
 
           ##
@@ -148,6 +153,26 @@ module Google
             add_access_role_scope_value :reader, :group, email
           end
 
+          ##
+          # Add reader access to some other type of member that appears in the IAM
+          # Policy but isn't a user, group, domain, or special group.
+          #
+          # @param [String] identity The identity reference.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #
+          #   dataset.access do |access|
+          #     access.add_reader_iam_member "entity@example.com"
+          #   end
+          #
+          def add_reader_iam_member identity
+            add_access_role_scope_value :reader, :iam_member, identity
+          end
+
           ##
           # Add reader access to a domain.
           #
@@ -172,7 +197,7 @@ module Google
           # Add reader access to a special group.
           #
           # @param [String] group Accepted values are `owners`, `writers`,
-          #   `readers`, and `all`.
+          #   `readers`, `all_authenticated_users`, and `all_users`.
           #
           # @example
           #   require "google/cloud/bigquery"
@@ -181,13 +206,40 @@ module Google
           #   dataset = bigquery.dataset "my_dataset"
           #
           #   dataset.access do |access|
-          #     access.add_reader_special :all
+          #     access.add_reader_special :all_users
           #   end
           #
           def add_reader_special group
             add_access_role_scope_value :reader, :special, group
           end
 
+          ##
+          # Add access to a routine from a different dataset. Queries executed
+          # against that routine will have read access to views/tables/routines
+          # in this dataset. Only UDF is supported for now. The role field is
+          # not required when this field is set. If that routine is updated by
+          # any user, access to the routine needs to be granted again via an
+          # update operation.
+          #
+          # @param [Google::Cloud::Bigquery::Routine] routine A routine object.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #   other_dataset = bigquery.dataset "my_other_dataset", skip_lookup: true
+          #
+          #   routine = other_dataset.routine "my_routine"
+          #
+          #   dataset.access do |access|
+          #     access.add_reader_routine routine
+          #   end
+          #
+          def add_reader_routine routine
+            add_access_routine routine
+          end
+
           ##
           # Add reader access to a view.
           #
@@ -203,9 +255,9 @@ module Google
           #
           #   bigquery = Google::Cloud::Bigquery.new
           #   dataset = bigquery.dataset "my_dataset"
-          #   other_dataset = bigquery.dataset "my_other_dataset"
+          #   other_dataset = bigquery.dataset "my_other_dataset", skip_lookup: true
           #
-          #   view = other_dataset.table "my_view"
+          #   view = other_dataset.table "my_view", skip_lookup: true
           #
           #   dataset.access do |access|
           #     access.add_reader_view view
@@ -253,6 +305,26 @@ module Google
             add_access_role_scope_value :writer, :group, email
           end
 
+          ##
+          # Add writer access to some other type of member that appears in the IAM
+          # Policy but isn't a user, group, domain, or special group.
+          #
+          # @param [String] identity The identity reference.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #
+          #   dataset.access do |access|
+          #     access.add_writer_iam_member "entity@example.com"
+          #   end
+          #
+          def add_writer_iam_member identity
+            add_access_role_scope_value :writer, :iam_member, identity
+          end
+
           ##
           # Add writer access to a domain.
           #
@@ -277,7 +349,7 @@ module Google
           # Add writer access to a special group.
           #
           # @param [String] group Accepted values are `owners`, `writers`,
-          #   `readers`, and `all`.
+          #   `readers`, `all_authenticated_users`, and `all_users`.
           #
           # @example
           #   require "google/cloud/bigquery"
@@ -286,7 +358,7 @@ module Google
           #   dataset = bigquery.dataset "my_dataset"
           #
           #   dataset.access do |access|
-          #     access.add_writer_special :all
+          #     access.add_writer_special :all_users
           #   end
           #
           def add_writer_special group
@@ -331,6 +403,26 @@ module Google
             add_access_role_scope_value :owner, :group, email
           end
 
+          ##
+          # Add owner access to some other type of member that appears in the IAM
+          # Policy but isn't a user, group, domain, or special group.
+          #
+          # @param [String] identity The identity reference.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #
+          #   dataset.access do |access|
+          #     access.add_owner_iam_member "entity@example.com"
+          #   end
+          #
+          def add_owner_iam_member identity
+            add_access_role_scope_value :owner, :iam_member, identity
+          end
+
           ##
           # Add owner access to a domain.
           #
@@ -355,7 +447,7 @@ module Google
           # Add owner access to a special group.
           #
           # @param [String] group Accepted values are `owners`, `writers`,
-          #   `readers`, and `all`.
+          #   `readers`, `all_authenticated_users`, and `all_users`.
           #
           # @example
           #   require "google/cloud/bigquery"
@@ -364,7 +456,7 @@ module Google
           #   dataset = bigquery.dataset "my_dataset"
           #
           #   dataset.access do |access|
-          #     access.add_owner_special :all
+          #     access.add_owner_special :all_users
           #   end
           #
           def add_owner_special group
@@ -409,6 +501,26 @@ module Google
             remove_access_role_scope_value :reader, :group, email
           end
 
+          ##
+          # Remove reader access from some other type of member that appears in the IAM
+          # Policy but isn't a user, group, domain, or special group.
+          #
+          # @param [String] identity The identity reference.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #
+          #   dataset.access do |access|
+          #     access.remove_reader_iam_member "entity@example.com"
+          #   end
+          #
+          def remove_reader_iam_member identity
+            remove_access_role_scope_value :reader, :iam_member, identity
+          end
+
           ##
           # Remove reader access from a domain.
           #
@@ -433,7 +545,7 @@ module Google
           # Remove reader access from a special group.
           #
           # @param [String] group Accepted values are `owners`, `writers`,
-          #   `readers`, and `all`.
+          #   `readers`, `all_authenticated_users`, and `all_users`.
           #
           # @example
           #   require "google/cloud/bigquery"
@@ -442,13 +554,35 @@ module Google
           #   dataset = bigquery.dataset "my_dataset"
           #
           #   dataset.access do |access|
-          #     access.remove_reader_special :all
+          #     access.remove_reader_special :all_users
           #   end
           #
           def remove_reader_special group
             remove_access_role_scope_value :reader, :special, group
           end
 
+          ##
+          # Remove reader access from a routine from a different dataset.
+          #
+          # @param [Google::Cloud::Bigquery::Routine] routine A routine object.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #   other_dataset = bigquery.dataset "my_other_dataset", skip_lookup: true
+          #
+          #   routine = other_dataset.routine "my_routine", skip_lookup: true
+          #
+          #   dataset.access do |access|
+          #     access.remove_reader_routine routine
+          #   end
+          #
+          def remove_reader_routine routine
+            remove_access_routine routine
+          end
+
           ##
           # Remove reader access from a view.
           #
@@ -464,9 +598,9 @@ module Google
           #
           #   bigquery = Google::Cloud::Bigquery.new
           #   dataset = bigquery.dataset "my_dataset"
-          #   other_dataset = bigquery.dataset "my_other_dataset"
+          #   other_dataset = bigquery.dataset "my_other_dataset", skip_lookup: true
           #
-          #   view = other_dataset.table "my_view"
+          #   view = other_dataset.table "my_view", skip_lookup: true
           #
           #   dataset.access do |access|
           #     access.remove_reader_view view
@@ -514,6 +648,26 @@ module Google
             remove_access_role_scope_value :writer, :group, email
           end
 
+          ##
+          # Remove writer access from some other type of member that appears in the IAM
+          # Policy but isn't a user, group, domain, or special group.
+          #
+          # @param [String] identity The identity reference.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #
+          #   dataset.access do |access|
+          #     access.remove_writer_iam_member "entity@example.com"
+          #   end
+          #
+          def remove_writer_iam_member identity
+            remove_access_role_scope_value :writer, :iam_member, identity
+          end
+
           ##
           # Remove writer access from a domain.
           #
@@ -538,7 +692,7 @@ module Google
           # Remove writer access from a special group.
           #
           # @param [String] group Accepted values are `owners`, `writers`,
-          #   `readers`, and `all`.
+          #   `readers`, `all_authenticated_users`, and `all_users`.
           #
           # @example
           #   require "google/cloud/bigquery"
@@ -547,7 +701,7 @@ module Google
           #   dataset = bigquery.dataset "my_dataset"
           #
           #   dataset.access do |access|
-          #     access.remove_writer_special :all
+          #     access.remove_writer_special :all_users
           #   end
           #
           def remove_writer_special group
@@ -592,6 +746,26 @@ module Google
             remove_access_role_scope_value :owner, :group, email
           end
 
+          ##
+          # Remove owner access from some other type of member that appears in the IAM
+          # Policy but isn't a user, group, domain, or special group.
+          #
+          # @param [String] identity The identity reference.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #
+          #   dataset.access do |access|
+          #     access.remove_owner_iam_member "entity@example.com"
+          #   end
+          #
+          def remove_owner_iam_member identity
+            remove_access_role_scope_value :owner, :iam_member, identity
+          end
+
           ##
           # Remove owner access from a domain.
           #
@@ -616,7 +790,7 @@ module Google
           # Remove owner access from a special group.
           #
           # @param [String] group Accepted values are `owners`, `writers`,
-          #   `readers`, and `all`.
+          #   `readers`, `all_authenticated_users`, and `all_users`.
           #
           # @example
           #   require "google/cloud/bigquery"
@@ -625,7 +799,7 @@ module Google
           #   dataset = bigquery.dataset "my_dataset"
           #
           #   dataset.access do |access|
-          #     access.remove_owner_special :all
+          #     access.remove_owner_special :all_users
           #   end
           #
           def remove_owner_special group
@@ -668,6 +842,25 @@ module Google
             lookup_access_role_scope_value :reader, :group, email
           end
 
+          ##
+          # Checks reader access for some other type of member that appears in the IAM
+          # Policy but isn't a user, group, domain, or special group.
+          #
+          # @param [String] identity The identity reference.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #
+          #   access = dataset.access
+          #   access.reader_iam_member? "entity@example.com" #=> false
+          #
+          def reader_iam_member? identity
+            lookup_access_role_scope_value :reader, :iam_member, identity
+          end
+
           ##
           # Checks reader access for a domain.
           #
@@ -691,7 +884,7 @@ module Google
           # Checks reader access for a special group.
           #
           # @param [String] group Accepted values are `owners`, `writers`,
-          #   `readers`, and `all`.
+          #   `readers`, `all_authenticated_users`, and `all_users`.
           #
           # @example
           #   require "google/cloud/bigquery"
@@ -700,12 +893,38 @@ module Google
           #   dataset = bigquery.dataset "my_dataset"
           #
           #   access = dataset.access
-          #   access.reader_special? :all #=> false
+          #   access.reader_special? :all_users #=> false
           #
           def reader_special? group
             lookup_access_role_scope_value :reader, :special, group
           end
 
+          ##
+          # Checks access for a routine from a different dataset. Queries executed
+          # against that routine will have read access to views/tables/routines
+          # in this dataset. Only UDF is supported for now. The role field is
+          # not required when this field is set. If that routine is updated by
+          # any user, access to the routine needs to be granted again via an
+          # update operation.
+          #
+          # @param [Google::Cloud::Bigquery::Routine] routine A routine object.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #   other_dataset = bigquery.dataset "my_other_dataset", skip_lookup: true
+          #
+          #   routine = other_dataset.routine "my_routine", skip_lookup: true
+          #
+          #   access = dataset.access
+          #   access.reader_routine? routine #=> false
+          #
+          def reader_routine? routine
+            lookup_access_routine routine
+          end
+
           ##
           # Checks reader access for a view.
           #
@@ -721,9 +940,9 @@ module Google
           #
           #   bigquery = Google::Cloud::Bigquery.new
           #   dataset = bigquery.dataset "my_dataset"
-          #   other_dataset = bigquery.dataset "my_other_dataset"
+          #   other_dataset = bigquery.dataset "my_other_dataset", skip_lookup: true
           #
-          #   view = other_dataset.table "my_view"
+          #   view = other_dataset.table "my_view", skip_lookup: true
           #
           #   access = dataset.access
           #   access.reader_view? view #=> false
@@ -768,6 +987,25 @@ module Google
             lookup_access_role_scope_value :writer, :group, email
           end
 
+          ##
+          # Checks writer access for some other type of member that appears in the IAM
+          # Policy but isn't a user, group, domain, or special group.
+          #
+          # @param [String] identity The identity reference.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #
+          #   access = dataset.access
+          #   access.writer_iam_member? "entity@example.com" #=> false
+          #
+          def writer_iam_member? identity
+            lookup_access_role_scope_value :writer, :iam_member, identity
+          end
+
           ##
           # Checks writer access for a domain.
           #
@@ -791,7 +1029,7 @@ module Google
           # Checks writer access for a special group.
           #
           # @param [String] group Accepted values are `owners`, `writers`,
-          #   `readers`, and `all`.
+          #   `readers`, `all_authenticated_users`, and `all_users`.
           #
           # @example
           #   require "google/cloud/bigquery"
@@ -800,7 +1038,7 @@ module Google
           #   dataset = bigquery.dataset "my_dataset"
           #
           #   access = dataset.access
-          #   access.writer_special? :all #=> false
+          #   access.writer_special? :all_users #=> false
           #
           def writer_special? group
             lookup_access_role_scope_value :writer, :special, group
@@ -842,6 +1080,25 @@ module Google
             lookup_access_role_scope_value :owner, :group, email
           end
 
+          ##
+          # Checks owner access for some other type of member that appears in the IAM
+          # Policy but isn't a user, group, domain, or special group.
+          #
+          # @param [String] identity The identity reference.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #
+          #   access = dataset.access
+          #   access.owner_iam_member? "entity@example.com" #=> false
+          #
+          def owner_iam_member? identity
+            lookup_access_role_scope_value :owner, :iam_member, identity
+          end
+
           ##
           # Checks owner access for a domain.
           #
@@ -865,7 +1122,7 @@ module Google
           # Checks owner access for a special group.
           #
           # @param [String] group Accepted values are `owners`, `writers`,
-          #   `readers`, and `all`.
+          #   `readers`, `all_authenticated_users`, and `all_users`.
           #
           # @example
           #   require "google/cloud/bigquery"
@@ -874,7 +1131,7 @@ module Google
           #   dataset = bigquery.dataset "my_dataset"
           #
           #   access = dataset.access
-          #   access.owner_special? :all #=> false
+          #   access.owner_special? :all_users #=> false
           #
           def owner_special? group
             lookup_access_role_scope_value :owner, :special, group
@@ -885,10 +1142,8 @@ module Google
             rules = Array gapi.access
             new.tap do |s|
               s.instance_variable_set :@rules, rules
-              s.instance_variable_set :@original_rules_hashes,
-                                      rules.map(&:to_h)
-              s.instance_variable_set :@dataset_reference,
-                                      gapi.dataset_reference
+              s.instance_variable_set :@original_rules_hashes, rules.map(&:to_h)
+              s.instance_variable_set :@dataset_reference, gapi.dataset_reference
             end
           end
 
@@ -902,18 +1157,14 @@ module Google
           # @private
           def validate_role role
             good_role = ROLES[role.to_s]
-            if good_role.nil?
-              raise ArgumentError "Unable to determine role for #{role}"
-            end
+            raise ArgumentError "Unable to determine role for #{role}" if good_role.nil?
             good_role
           end
 
           # @private
           def validate_scope scope
             good_scope = SCOPES[scope.to_s]
-            if good_scope.nil?
-              raise ArgumentError "Unable to determine scope for #{scope}"
-            end
+            raise ArgumentError "Unable to determine scope for #{scope}" if good_scope.nil?
             good_scope
           end
 
@@ -943,7 +1194,17 @@ module Google
             @rules.reject!(&find_by_scope_and_value(scope, value))
             # Add new rule for this role, scope, and value
             opts = { role: role, scope => value }
-            @rules << Google::Apis::BigqueryV2::Dataset::Access.new(opts)
+            @rules << Google::Apis::BigqueryV2::Dataset::Access.new(**opts)
+          end
+
+          # @private
+          def add_access_routine routine
+            value = routine.routine_ref
+            # Remove existing routine rule, if any
+            @rules.reject!(&find_by_scope_and_resource_ref(:routine, value))
+            # Add new rule for this role, scope, and value
+            opts = { routine: value }
+            @rules << Google::Apis::BigqueryV2::Dataset::Access.new(**opts)
           end
 
           # @private
@@ -951,10 +1212,10 @@ module Google
             # scope is view, make sure value is in the right format
             value = validate_view value
             # Remove existing view rule, if any
-            @rules.reject!(&find_view(value))
+            @rules.reject!(&find_by_scope_and_resource_ref(:view, value))
             # Add new rule for this role, scope, and value
             opts = { view: value }
-            @rules << Google::Apis::BigqueryV2::Dataset::Access.new(opts)
+            @rules << Google::Apis::BigqueryV2::Dataset::Access.new(**opts)
           end
 
           # @private
@@ -969,12 +1230,18 @@ module Google
             )
           end
 
+          # @private
+          def remove_access_routine routine
+            # Remove existing routine rule, if any
+            @rules.reject!(&find_by_scope_and_resource_ref(:routine, routine.routine_ref))
+          end
+
           # @private
           def remove_access_view value
             # scope is view, make sure value is in the right format
             value = validate_view value
             # Remove existing view rule, if any
-            @rules.reject!(&find_view(value))
+            @rules.reject!(&find_by_scope_and_resource_ref(:view, value))
           end
 
           # @private
@@ -984,9 +1251,13 @@ module Google
             # If scope is special group, make sure value is in the list
             value = validate_special_group value if scope == :special_group
             # Detect any rules of this role, scope, and value
-            !(!@rules.detect(
-              &find_by_role_and_scope_and_value(role, scope, value)
-            ))
+            !(!@rules.detect(&find_by_role_and_scope_and_value(role, scope, value)))
+          end
+
+          # @private
+          def lookup_access_routine routine
+            # Detect routine rule, if any
+            !(!@rules.detect(&find_by_scope_and_resource_ref(:routine, routine.routine_ref)))
           end
 
           # @private
@@ -994,7 +1265,7 @@ module Google
             # scope is view, make sure value is in the right format
             value = validate_view value
             # Detect view rule, if any
-            !(!@rules.detect(&find_view(value)))
+            !(!@rules.detect(&find_by_scope_and_resource_ref(:view, value)))
           end
 
           # @private
@@ -1013,11 +1284,11 @@ module Google
             end
           end
 
-          # @private
-          def find_view value
+          # @private Compare hash representations to find table_ref, routine_ref.
+          def find_by_scope_and_resource_ref scope, value
             lambda do |a|
               h = a.to_h
-              h[:view].to_h == value.to_h
+              h[scope].to_h == value.to_h
             end
           end
         end