power-bi 2.2.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5aaadec6cec57b22f4780dd2e1f4c64c55872d49f5a17a59326fcff099844dd
-  data.tar.gz: 1a6bf8c48a1d17333f58519c5ee23ee9a85025c63110c6cc2f2fe9243566f7ca
+  metadata.gz: 90d415a89ed5860c82824f7e152e4c58d42054bc293f5534f6669774682a1ffe
+  data.tar.gz: 536d4c7cea48c859c7b780db751da15375b060a45c59946a2335887d8e948494
 SHA512:
-  metadata.gz: 570af0ad49001778d237e4ce712a8120d879cc83d53a9b4a877d2d51ee6fcc3dde4e913cc8a3c42273ce5de45d31d7922308fee03c895fb6fcbce46332b06288
-  data.tar.gz: 760813b41e3318fc52871f3adc61f4efcf518f9333f93fcf9295c15b9e61d094518cbd3adbbf7fec0c3c7921239d2082460099fc2adffcd4b60c15067e5946e1
+  metadata.gz: d31db71feb4b03d7810d5805b3d48016e89ead1782bfae66269aa2a0c55340e6cf21031525ffa6d5b917cdc36041670ef52c1ccff499ebdfc7d0051d8005b6a8
+  data.tar.gz: 1ea49ae1a15e45b16c21b9da86c8ac20abb9e96a6eb63e6a0ed9a7dfcbca25dfff8431896703f2d55736a148668cf4b85ac591eb20c68bf1b2d9f6baee455e3a

data/README.md

@@ -10,6 +10,62 @@ The Power BI API does not handle the authorization part. It requires the user to
 pbi = PowerBI::Tenant.new(->{token = get_token(client, token) ; token.token})
 ```
 
+## Authentication & authorization towards the Power BI API
+
+Currently (april 2024), there are basically 3 ways to authenticate to the Power BI API.
+
+### 1 - Master User
+
+A master user is a classic Microsoft 365 user that you assign a Power BI Pro license.  In order to allow the user to execute actions on the Power BI API you need to create an app registration in Azure AD.  In the associated Enterprise application (gets created when you create the app registration), you need to add the permissions to use the Power BI service.
+
+The resulting authentication looks like this:
+
+```
+TENANT = "53c835d6-6841-4d58-948a-55117409e1d8"
+CLIENT_ID = '6fc64675-bee3-49a7-70d8-b3301a51a88d'
+CLIENT_SECRET = 'sI/@ncYe=eVt7.XfZ7tsPU1aPbxm0V_H'
+USERNAME = 'company_0001@example.com'
+PASSWORD = 'mLXv5A1jrIb8dHopur7y'
+
+client = OAuth2::Client.new(CLIENT_ID, CLIENT_SECRET, site: 'https://login.microsoftonline.com', token_url: "#{TENANT}/oauth2/token")
+
+token = client.password.get_token(USERNAME, PASSWORD, scope: 'openid', resource: 'https://analysis.windows.net/powerbi/api')
+```
+
+Note that in this case the legacy (and slightly unsafe) Resource Owner Password Credentials (ROPC) OAuth flow is used.
+
+### 2 - Service principal
+
+A service principal is a fancy word for a machine user with a secret (eg. id + key) in Azure AD.  You create them by creating an app registration and adding a secret on it.  You need to allow service principals in your Power BI admin settings. But once you allow that, the setup is very easy.  No need to configure anything special in AD.
+
+The resulting authentication looks like this:
+
+```
+TENANT = "53c835d6-6841-4d58-948a-55117409e1d8"
+CLIENT_ID = '6fc64675-bee3-49a7-70d8-b3301a51a88d'
+CLIENT_SECRET = 'sI/@ncYe=eVt7.XfZ7tsPU1aPbxm0V_H'
+
+client = OAuth2::Client.new(CLIENT_ID, CLIENT_SECRET, site: 'https://login.microsoftonline.com', token_url: "#{TENANT}/oauth2/token")
+
+token = client.client_credentials.get_token(resource: 'https://analysis.windows.net/powerbi/api')
+```
+
+Note that in this case the Client Credentials OAuth flow is used.
+
+### 3 - Service principal profiles
+
+Service principal profiles is a Power-BI-only concept.  Towards AD, it looks exactly the same as generic service principal.  Hence the authenication looks exactly as in way 2.
+
+Once authenticated, you can set profiles like this:
+
+```
+pbi.profile = profile
+```
+
+Every action executed after setting the profile, will be executed _through the eyes of the profile_.  This way, you can create an isolated multi-tenant setup.  Using profiles, simplifies the internal organization of Power BI and allows faster interaction with Power BI.  This also lifts the 1000-workspaces limit that is imposed on Master Users and Service Principals
+
+Note: when working with Service principal profiles (SPP), you need to add the SPP to the gateway datasource before binding the gateway datasource to the dataset.
+
 # Supported endpoints
 
 Note: where possible we use _lazy evaluation_: we only call the REST API endpoint when really needed. For examples `pbi.workspaces` won't trigger a call, while `pbi.workspaces.count` will trigger a call.  And `pbi.workspace('123')` won't trigger a call, while `pbi.workspace('123').name` will trigger a call.
@@ -68,6 +124,11 @@ Note 2: to limit the number of API calls, it is best to directly use the _getter
 * Create a new gateway datasource: `gateway.gateway_datasource.create(name, credentials, db_server, db_name)`
 * Delete a new gateway datasource: `gateway_datasource.delete`
 
+## Gateway datasource users
+
+* List datasource users in a gateway datasource: `gateway_datasource.gateway_datasource_users`
+* Add a Service principal profile to a gateway datasource: `gateway_datasource.add_service_principal_profile_user(profile_id, principal_object_id)`
+
 ## Capacities
 
 Note: Capacities are Azure creatures, you can't create them in Power BI.
@@ -75,6 +136,13 @@ Note: Capacities are Azure creatures, you can't create them in Power BI.
 * List capacities: `pbi.capacities`
 * Get a capacity: `pbi.capacity(id)`
 
+## Profiles
+
+* List profiles: `pbi.profiles`
+* Get a profile: `pbi.profile(id)`
+* Create a profile: `pbi.profiles.create`
+* Delete a profile: `profile.delete`
+
 # Note about gateway credentials
 
 Power BI uses an obscure mechanism to encrypt credential exchange between the service and the gateway.  The encryption must be done outside this module on a Windows machine based on th public key of the gateway.  This is an example C# script:

data/lib/power-bi/gateway.rb

@@ -8,7 +8,7 @@ module PowerBI
     end
 
     def get_data(id)
-      @tenant.get("/gateways/#{id}")
+      @tenant.get("/gateways/#{id}", use_profile: false)
     end
 
     def data_to_attributes(data)
@@ -32,7 +32,7 @@ module PowerBI
     end
 
     def get_data
-      @tenant.get("/gateways")[:value]
+      @tenant.get("/gateways", use_profile: false)[:value]
     end
   end
 end

data/lib/power-bi/gateway_datasource.rb

@@ -1,14 +1,15 @@
 module PowerBI
   class GatewayDatasource < Object
-    attr_reader :gateway
+    attr_reader :gateway, :gateway_datasource_users
 
     def initialize(tenant, parent, id = nil)
       super(tenant, id)
       @gateway = parent
+      @gateway_datasource_users = GatewayDatasourceUserArray.new(@tenant, self)
     end
 
     def get_data(id)
-      @tenant.get("/gateways/#{@gateway.id}/datasources/#{id}")
+      @tenant.get("/gateways/#{@gateway.id}/datasources/#{id}", use_profile: false)
     end
 
     def data_to_attributes(data)
@@ -24,7 +25,7 @@ module PowerBI
     end
 
     def update_credentials(encrypted_credentials)
-      @tenant.patch("/gateways/#{gateway.id}/datasources/#{id}") do |req|
+      @tenant.patch("/gateways/#{gateway.id}/datasources/#{id}", use_profile: false) do |req|
         req.body = {
           credentialDetails: {
             credentialType: "Basic",
@@ -41,7 +42,7 @@ module PowerBI
     end
 
     def delete
-      @tenant.delete("/gateways/#{gateway.id}/datasources/#{id}")
+      @tenant.delete("/gateways/#{gateway.id}/datasources/#{id}", use_profile: false)
       @gateway.gateway_datasources.reload
       true
     end
@@ -61,7 +62,7 @@ module PowerBI
 
     # only MySQL type is currently supported
     def create(name, encrypted_credentials, db_server, db_name)
-      data = @tenant.post("/gateways/#{@gateway.id}/datasources",) do |req|
+      data = @tenant.post("/gateways/#{@gateway.id}/datasources", use_profile: false) do |req|
         req.body = {
           connectionDetails: {server: db_server, database: db_name}.to_json,
           credentialDetails: {
@@ -82,7 +83,7 @@ module PowerBI
     end
 
     def get_data
-      @tenant.get("/gateways/#{@gateway.id}/datasources")[:value]
+      @tenant.get("/gateways/#{@gateway.id}/datasources", use_profile: false)[:value]
     end
   end
 end

data/lib/power-bi/gateway_datasource_user.rb

@@ -0,0 +1,51 @@
+module PowerBI
+  class GatewayDatasourceUser < Object
+    attr_reader :gateway_datasource
+
+    def initialize(tenant, parent, id = nil)
+      super(tenant, id)
+      @gateway_datasource = parent
+    end
+
+    def data_to_attributes(data)
+      {
+        datasource_access_right: data[:datasourceAccessRight],
+        display_name: data[:displayName],
+        email_address: data[:emailAddress],
+        identifier: data[:identifier],
+        principal_type: data[:principalType],
+        profile: data[:profile],
+      }
+    end
+
+  end
+
+  class GatewayDatasourceUserArray < Array
+
+    def initialize(tenant, gateway_datasource)
+      super(tenant, gateway_datasource)
+      @gateway_datasource = gateway_datasource
+    end
+
+    def self.get_class
+      GatewayDatasourceUser
+    end
+
+    # service principal object ID: https://learn.microsoft.com/en-us/power-bi/developer/embedded/embedded-troubleshoot#what-is-the-difference-between-application-object-id-and-principal-object-id
+    def add_service_principal_profile_user(profile_id, principal_object_id, datasource_access_right: "Read")
+      @tenant.post("/gateways/#{@gateway_datasource.gateway.id}/datasources/#{@gateway_datasource.id}/users", use_profile: false) do |req|
+        req.body = {
+          datasourceAccessRight: datasource_access_right,
+          identifier: principal_object_id,
+          principalType: "App",
+          profile: {id: profile_id},
+        }.to_json
+      end
+      self.reload
+    end
+
+    def get_data
+      @tenant.get("/gateways/#{@gateway_datasource.gateway.id}/datasources/#{@gateway_datasource.id}/users", use_profile: false)[:value]
+    end
+  end
+end

data/lib/power-bi/profile.rb

@@ -0,0 +1,44 @@
+module PowerBI
+  class Profile < Object
+
+    def initialize(tenant, parent, id = nil)
+      super(tenant, id)
+    end
+
+    def get_data(id)
+      @tenant.get("/profiles/#{id}", use_profile: false)
+    end
+
+    def data_to_attributes(data)
+      {
+        id: data[:id],
+        display_name: data[:displayName],
+      }
+    end
+
+    def delete
+      @tenant.delete("/profiles/#{@id}", use_profile: false)
+      @tenant.profiles.reload
+      true
+    end
+
+  end
+
+  class ProfileArray < Array
+    def self.get_class
+      Profile
+    end
+
+    def create(name)
+      data = @tenant.post("/profiles", use_profile: false) do |req|
+        req.body = {displayName: name}.to_json
+      end
+      self.reload
+      Profile.instantiate_from_data(@tenant, nil, data)
+    end
+
+    def get_data
+      @tenant.get("/profiles", use_profile: false)[:value]
+    end
+  end
+end

data/lib/power-bi/tenant.rb

@@ -1,13 +1,15 @@
 module PowerBI
   class Tenant
-    attr_reader :workspaces, :gateways, :capacities
+    attr_reader :workspaces, :gateways, :capacities, :profiles, :profile_id
 
     def initialize(token_generator, retries: 5, logger: nil)
       @token_generator = token_generator
       @workspaces = WorkspaceArray.new(self)
       @gateways = GatewayArray.new(self)
       @capacities = CapacityArray.new(self)
+      @profiles = ProfileArray.new(self)
       @logger = logger
+      @profile_id = nil
 
       ## WHY RETRIES? ##
       # It is noticed that once in a while (~0.1% API calls), the Power BI server returns a 500 (internal server error) without apparent reason, just retrying works :-)
@@ -42,7 +44,16 @@ module PowerBI
       Capacity.new(self, nil, id)
     end
 
-    def get(url, params = {})
+    def profile(id)
+      Profile.new(self, nil, id)
+    end
+
+    def profile=(profile)
+      @profile_id = profile.is_a?(String) ? profile : profile&.id
+      @workspaces.reload # we need to reload the workspaces because we look through the eyes of the profile
+    end
+
+    def get(url, params = {}, use_profile: true)
       t0 = Time.now
       conn = Faraday.new do |f|
         f.request :retry, @retry_options
@@ -51,6 +62,9 @@ module PowerBI
         req.params = params
         req.headers['Accept'] = 'application/json'
         req.headers['authorization'] = "Bearer #{token}"
+        if use_profile
+          add_spp_header(req)
+        end
         yield req if block_given?
       end
       if response.status == 400
@@ -65,7 +79,7 @@ module PowerBI
       end
     end
 
-    def get_raw(url, params = {})
+    def get_raw(url, params = {}, use_profile: true)
       t0 = Time.now
       conn = Faraday.new do |f|
         f.request :retry, @retry_options
@@ -73,6 +87,9 @@ module PowerBI
       response = conn.get(PowerBI::BASE_URL + url) do |req|
         req.params = params
         req.headers['authorization'] = "Bearer #{token}"
+        if use_profile
+          add_spp_header(req)
+        end
         yield req if block_given?
       end
       log "Calling (GET - raw) #{response.env.url.to_s} - took #{((Time.now - t0) * 1000).to_i} ms"
@@ -82,7 +99,7 @@ module PowerBI
       response.body
     end
 
-    def post(url, params = {})
+    def post(url, params = {}, use_profile: true)
       t0 = Time.now
       conn = Faraday.new do |f|
         f.request :retry, @retry_options
@@ -92,6 +109,9 @@ module PowerBI
         req.headers['Accept'] = 'application/json'
         req.headers['Content-Type'] = 'application/json'
         req.headers['authorization'] = "Bearer #{token}"
+        if use_profile
+          add_spp_header(req)
+        end
         yield req if block_given?
       end
       log "Calling (POST) #{response.env.url.to_s} - took #{((Time.now - t0) * 1000).to_i} ms"
@@ -103,7 +123,7 @@ module PowerBI
       end
     end
 
-    def patch(url, params = {})
+    def patch(url, params = {}, use_profile: true)
       t0 = Time.now
       conn = Faraday.new do |f|
         f.request :retry, @retry_options
@@ -113,6 +133,9 @@ module PowerBI
         req.headers['Accept'] = 'application/json'
         req.headers['Content-Type'] = 'application/json'
         req.headers['authorization'] = "Bearer #{token}"
+        if use_profile
+          add_spp_header(req)
+        end
         yield req if block_given?
       end
       log "Calling (PATCH) #{response.env.url.to_s} - took #{((Time.now - t0) * 1000).to_i} ms"
@@ -124,7 +147,7 @@ module PowerBI
       end
     end
 
-    def delete(url, params = {})
+    def delete(url, params = {}, use_profile: true)
       t0 = Time.now
       conn = Faraday.new do |f|
         f.request :retry, @retry_options
@@ -133,6 +156,9 @@ module PowerBI
         req.params = params
         req.headers['Accept'] = 'application/json'
         req.headers['authorization'] = "Bearer #{token}"
+        if use_profile
+          add_spp_header(req)
+        end
         yield req if block_given?
       end
       log "Calling (DELETE) #{response.env.url.to_s} - took #{((Time.now - t0) * 1000).to_i} ms"
@@ -147,7 +173,7 @@ module PowerBI
       end
     end
 
-    def post_file(url, file, params = {})
+    def post_file(url, file, params = {}, use_profile: true)
       t0 = Time.now
       conn = Faraday.new do |f|
         f.request :multipart
@@ -158,6 +184,9 @@ module PowerBI
         req.headers['Accept'] = 'application/json'
         req.headers['Content-Type'] = 'multipart/form-data'
         req.headers['authorization'] = "Bearer #{token}"
+        if use_profile
+          add_spp_header(req)
+        end
         req.body = {value: Faraday::UploadIO.new(file, 'application/octet-stream')}
         req.options.timeout = 120  # default is 60 seconds Net::ReadTimeout
       end
@@ -170,6 +199,12 @@ module PowerBI
 
     private
 
+    def add_spp_header(req)
+      if @profile_id
+        req.headers['X-PowerBI-Profile-Id'] = @profile_id
+      end
+    end
+
     def token
       @token_generator.call
     end

data/lib/power-bi.rb

@@ -22,6 +22,8 @@ require_relative "power-bi/parameter"
 require_relative "power-bi/refresh"
 require_relative "power-bi/gateway"
 require_relative "power-bi/gateway_datasource"
+require_relative "power-bi/gateway_datasource_user"
 require_relative "power-bi/page"
 require_relative "power-bi/user"
-require_relative "power-bi/capacity"
+require_relative "power-bi/capacity"
+require_relative "power-bi/profile"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: power-bi
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.4.0
 platform: ruby
 authors:
 - Lode Cools
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-08-04 00:00:00.000000000 Z
+date: 2024-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -95,9 +95,11 @@ files:
 - lib/power-bi/datasource.rb
 - lib/power-bi/gateway.rb
 - lib/power-bi/gateway_datasource.rb
+- lib/power-bi/gateway_datasource_user.rb
 - lib/power-bi/object.rb
 - lib/power-bi/page.rb
 - lib/power-bi/parameter.rb
+- lib/power-bi/profile.rb
 - lib/power-bi/refresh.rb
 - lib/power-bi/report.rb
 - lib/power-bi/tenant.rb