grafana 0.9.0 → 0.10.1

data/lib/grafana/dashboard.rb

@@ -2,12 +2,36 @@
 module Grafana
 
   # http://docs.grafana.org/http_api/dashboard/
+
+  # The identifier (id) of a dashboard is an auto-incrementing numeric value and is only unique per Grafana install.
+  #
+  # The unique identifier (uid) of a dashboard can be used for uniquely identify a dashboard between multiple Grafana installs.
+  # It's automatically generated if not provided when creating a dashboard. The uid allows having consistent URL's for
+  # accessing dashboards and when syncing dashboards between multiple Grafana installs, see dashboard provisioning for
+  # more information. This means that changing the title of a dashboard will not break any bookmarked links to that dashboard.
+  #
+  # The uid can have a maximum length of 40 characters.
+  #
+  # Deprecated resources
+  #  Please note that these resource have been deprecated and will be removed in a future release.
+  #
+  #  - Get dashboard by slug
+  #  - Delete dashboard by slug
+  #
+  #
   #
   module Dashboard
 
-
+    # http://docs.grafana.org/http_api/dashboard/#get-dashboard-by-slug
+    #  - Deprecated starting from Grafana v5.0.
+    #    Please update to use the new Get dashboard by uid resource instead
+    #
     # Get dashboard
     #
+    # Will return the dashboard given the dashboard slug.
+    # Slug is the url friendly version of the dashboard title.
+    # If there exists multiple dashboards with the same slug, one of them will be returned in the response.
+    #
     # @example
     #    dashboard('dashboard for many foo')
     #
@@ -18,23 +42,71 @@ module Grafana
       raise ArgumentError.new(format('wrong type. \'name\' must be an String, given \'%s\'', name.class.to_s)) unless( name.is_a?(String) )
       raise ArgumentError.new('missing name') if( name.size.zero? )
 
+#       v, mv = version.values
+#
+#       if( mv == 5)
+#         puts 'DEPRICATION WARNING'
+#         puts 'Grafana v5.0 use a new interal id/uid handling'
+#         puts 'This function works well with Grafana v4.x'
+#       end
+
       endpoint = format( '/api/dashboards/db/%s', slug(name) )
+      @logger.debug( "Attempting to get dashboard (GET #{endpoint})" ) if @debug
+
+      get( endpoint )
+    end
+
+    # http://docs.grafana.org/http_api/dashboard/#get-dashboard-by-uid
+    #
+    # GET /api/dashboards/uid/:uid
+    # Will return the dashboard given the dashboard unique identifier (uid).
+    #
+    # Get dashboard
+    #
+    # Will return the dashboard given the dashboard unique identifier (uid).
+    #
+    # @example
+    #    dashboard('L42r6NWiz')
+    #
+    # @return [String]
+    #
+    def dashboard_by_uid( uid )
+
+      if( uid.is_a?(String) && uid.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. dashboard \'uid\' must be an String (for an title name) or an Integer (for an Datasource Id), given \'%s\'', uid.class.to_s))
+      end
+      raise ArgumentError.new('missing \'uid\'') if( uid.size.zero? )
 
-      @logger.debug( "Attempting to get dashboard (GET /api/dashboards/db/#{name})" ) if @debug
+      v, mv = version.values
+      return { 'status' => 404, 'message' => format( 'only Grafana 5 has uid support. you use version %s', v) } if(mv != 5)
+
+      return { 'status' => 404, 'message' => format( 'The uid can have a maximum length of 40 characters. \'%s\' given', uid.length) } if( uid.length > 40 )
+
+      endpoint = format( '/api/dashboards/uid/%s', uid )
+      @logger.debug( "Attempting to get dashboard (GET #{endpoint})" ) if @debug
 
       get( endpoint )
     end
 
+
     # Create / Update dashboard
     #
+    # Creates a new dashboard or updates an existing dashboard.
+    #
     # @param [Hash] params
-    # @option params [Hash] dashboard
+    # @option params [Hash] dashboard The complete dashboard model
+    #  - dashboard.id - id = null to create a new dashboard.
+    #  - dashboard.uid - Optional unique identifier when creating a dashboard. uid = null will generate a new uid.
+    #  - folderId - The id of the folder to save the dashboard in.
+    #  - overwrite - Set to true if you want to overwrite existing dashboard with newer version, same dashboard title in folder or same dashboard uid.
+    #  - message - Set a commit message for the version history.
     # @option params [Boolean] overwrite (true)
     #
     # @example
     #    params = {
     #      dashboard: {
     #        id: null,
+    #        uid: null,
     #        title: 'Production Overview',
     #        tags: [ 'templated' ],
     #        timezone": 'browser',
@@ -45,7 +117,9 @@ module Grafana
     #        'schemaVersion': 6,
     #        'version': 0
     #      },
-    #      overwrite: false
+    #      folderId: 0,
+    #      overwrite: false,
+    #      message: 'created by foo'
     #    }
     #    create_dashboard( params )
     #
@@ -57,11 +131,20 @@ module Grafana
       raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
       raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
 
-      dashboard = validate( params, required: true, var: 'dashboard', type: Hash )
+      dashboard = validate( params, required: true , var: 'dashboard', type: Hash )
       overwrite = validate( params, required: false, var: 'overwrite', type: Boolean ) || true
+      folder_id = validate( params, required: false, var: 'folderId' )
+      message   = validate( params, required: false, var: 'message', type: String )
 
       dashboard = regenerate_template_ids( dashboard )
 
+      unless(folder_id.nil?)
+        f_folder = folder(folder_id)
+        return { 'status' => 404, 'message' => format( 'No Folder \'%s\' found', folder_id) } if( f_folder.dig('status') != 200 )
+
+        folder_id = f_folder.dig('id')
+      end
+
       db = JSON.parse( dashboard ) if( dashboard.is_a?(String) )
       title = db.dig('dashboard','title')
 
@@ -69,7 +152,9 @@ module Grafana
 
       payload = {
         dashboard: db.dig('dashboard'),
-        overwrite: overwrite
+        overwrite: overwrite,
+        folderId: folder_id,
+        message: message
       }
       payload.reject!{ |_k, v| v.nil? }
 
@@ -78,7 +163,12 @@ module Grafana
       post( endpoint, payload.to_json )
     end
 
+    # http://docs.grafana.org/http_api/dashboard/#delete-dashboard-by-slug
+    #  - Deprecated starting from Grafana v5.0.
+    #    Please update to use the new Get dashboard by uid resource instead
+    #
     # Delete dashboard
+    # Will delete the dashboard given the specified slug. Slug is the url friendly version of the dashboard title.
     #
     # @example
     #    delete_dashboard('dashboard for many foo')

data/lib/grafana/dashboard_permissions.rb

@@ -0,0 +1,132 @@
+
+module Grafana
+
+  # http://docs.grafana.org/http_api/dashboard_permissions/#dashboard-permissions-api
+  #
+  # This API can be used to update/get the permissions for a dashboard.
+  # Permissions with dashboardId=-1 are the default permissions for users with the Viewer and Editor roles.
+  # Permissions can be set for a user, a team or a role (Viewer or Editor).
+  # Permissions cannot be set for Admins - they always have access to everything.
+  #
+  # The permission levels for the permission field:
+  #
+  #  1 = View
+  #  2 = Edit
+  #  4 = Admin
+  #
+  module DashboardPermissions
+
+    # http://docs.grafana.org/http_api/dashboard_permissions/#get-permissions-for-a-dashboard
+    #
+    # GET /api/dashboards/id/:dashboardId/permissions
+    #
+    # Gets all existing permissions for the dashboard with the given dashboardId.
+    #
+    def dashboard_permissions(uid)
+
+      if( uid.is_a?(String) && uid.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. dashboard \'uid\' must be an String (for an title name) or an Integer (for an Datasource Id), given \'%s\'', uid.class.to_s))
+      end
+      raise ArgumentError.new('missing \'uid\'') if( uid.size.zero? )
+
+      endpoint = format( '/api/dashboards/id/%s/permissions', uid )
+      @logger.debug( "Attempting to get dashboard permissions (GET #{endpoint})" ) if @debug
+
+      r = get( endpoint )
+      r['message'] = format('dashboard \'%s\' not found', uid) if(r.dig('status') == 404)
+      r
+    end
+
+    # http://docs.grafana.org/http_api/dashboard_permissions/#update-permissions-for-a-dashboard
+    #
+    # POST /api/dashboards/id/:dashboardId/permissions
+    #
+    # Updates permissions for a dashboard.
+    # This operation will remove existing permissions if they're not included in the request.
+    #
+    #
+    def update_dashboad_permissions(params)
+
+      raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+      raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
+
+      v, mv = version.values
+      return { 'status' => 404, 'message' => format( 'only Grafana 5 has folder support. you use version %s', v) } if(mv != 5)
+
+      dashboard_id = validate( params, required: true, var: 'dashboard_id', type: Integer )
+      permissions  = validate( params, required: true, var: 'permissions' , type: Hash )
+
+      return { 'status' => 404, 'message' => 'no permissions given' } if( permissions.size.zero? )
+
+      valid_roles = %w[View Edit Admin]
+
+      c_team = permissions.dig('team')
+      c_user = permissions.dig('user')
+      team   = []
+      user   = []
+
+      unless(c_team.nil?)
+        check_keys = []
+
+        c_team.uniq.each do |x|
+          k = x.keys.first
+          v = x.values.first
+          r = validate_hash( v, valid_roles )
+
+          f_team = team(k)
+          team_id = f_team.dig('id')
+
+          next unless(( f_team.dig('status') == 200) && !check_keys.include?(team_id) && r == true )
+
+          check_keys << team_id
+
+          role_id = valid_roles.index(v)
+          role_id += 1
+          role_id += 1 if(v == 'Admin')
+
+          team << {
+            teamId: team_id,
+            permission: role_id
+          }
+        end
+      end
+
+      unless(c_user.nil?)
+        check_keys = []
+
+        c_user.uniq.each do |x|
+          k = x.keys.first
+          v = x.values.first
+          r = validate_hash( v, valid_roles )
+
+          f_user = user(k)
+          user_id = f_user.dig('id')
+
+          next unless(( f_user.dig('status') == 200) && !check_keys.include?(user_id) && r == true )
+
+          check_keys << user_id
+
+          role_id = valid_roles.index(v)
+          role_id += 1
+          role_id += 1 if(v == 'Admin')
+
+          user << {
+            userId: user_id,
+            permission: role_id
+          }
+        end
+      end
+
+      payload = {
+        items: team + user
+      }
+      payload.reject!{ |_, y| y.nil? }
+
+
+      endpoint = format('/api/dashboards/id/%s/permissions', dashboard_id)
+      post(endpoint, payload.to_json)
+    end
+
+  end
+
+end

data/lib/grafana/dashboard_versions.rb

@@ -1,29 +1,125 @@
 
 module Grafana
 
-  # http://docs.grafana.org/http_api/annotations/
+  # http://docs.grafana.org/http_api/dashboard_versions
   #
   module DashboardVersions
 
     # Get all dashboard versions
     # http://docs.grafana.org/http_api/dashboard_versions/#get-all-dashboard-versions
     # GET /api/dashboards/id/:dashboardId/versions
-    def dashboard_all_versions( params ); end
+    #
+    #
+    #
+    #
+    #
+    #
+    def dashboard_all_versions( params )
+
+      raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+      raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
+
+#      v, mv = version.values
+#      return { 'status' => 404, 'message' => format( 'only Grafana 5 has dashboard version support. you use version %s', v) } if(mv != 5)
+
+      dashboard_id  = validate( params, required: true , var: 'dashboard_id', type: Integer )
+      start         = validate( params, required: false, var: 'start'       , type: Integer )
+      limit         = validate( params, required: false, var: 'limit'       , type: Integer )
+
+      api     = []
+      api << format( 'start=%s', start ) unless( start.nil? )
+      api << format( 'limit=%s', limit ) unless( limit.nil? )
+      api = api.join( '&' )
+
+      endpoint = format('/api/dashboards/id/%s/versions?%s', dashboard_id, api)
+      get(endpoint)
+    end
 
     # Get dashboard version
     # http://docs.grafana.org/http_api/dashboard_versions/#get-dashboard-version
     # GET /api/dashboards/id/:dashboardId/versions/:id
-    def dashboard_version( params ); end
+    def dashboard_version( params )
+
+      raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+      raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
+
+      v, mv = version.values
+      return { 'status' => 404, 'message' => format( 'only Grafana 5 has folder support. you use version %s', v) } if(mv != 5)
+
+      dashboard_id  = validate( params, required: true, var: 'dashboard_id', type: Integer )
+      version       = validate( params, required: true, var: 'version'     , type: Integer )
+
+      endpoint = format('/api/dashboards/id/%s/versions/%s', dashboard_id, version)
+
+      r = get(endpoint)
+
+      r['message'] = format('no dashboard version \'%s\' for dashboard \'%s\' found', version, dashboard_id) if(r.dig('status') == 404)
+      r['message'] = format('no dashboard version \'%s\' for dashboard \'%s\' found', version, dashboard_id) if(r.dig('status') == 500)
+      r
+    end
 
     # Restore dashboard
     # http://docs.grafana.org/http_api/dashboard_versions/#restore-dashboard
     # POST /api/dashboards/id/:dashboardId/restore
-    def restore_dashboard( params ); end
+    def restore_dashboard( params )
+
+      raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+      raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
+
+#      v, mv = version.values
+#      return { 'status' => 404, 'message' => format( 'only Grafana 5 has folder support. you use version %s', v) } if(mv != 5)
+
+      dashboard_id  = validate( params, required: true, var: 'dashboard_id', type: Integer )
+      version       = validate( params, required: true, var: 'version'    , type: Integer )
+
+      endpoint = format('/api/dashboards/id/%s/restore', dashboard_id)
+
+      payload = {
+        version: version
+      }
+
+      post(endpoint, payload.to_json)
+    end
 
     # Compare dashboard versions
     # http://docs.grafana.org/http_api/dashboard_versions/#compare-dashboard-versions
     # POST /api/dashboards/calculate-diff
-    def compare_dashboard_version( params ); end
+    def compare_dashboard_version( params )
+
+      raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+      raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
+
+      base      = validate( params, required: true , var: 'base'     , type: Hash )
+      new       = validate( params, required: true , var: 'new'      , type: Hash )
+      diff_type = validate( params, required: false, var: 'diff_type', type: String ) || 'json'
+
+      base_dashboard_id      = validate( base, required: true , var: 'dashboard_id', type: Integer )
+      base_dashboard_version = validate( base, required: true , var: 'version'     , type: Integer )
+      new_dashboard_id       = validate( new , required: true , var: 'dashboard_id', type: Integer )
+      new_dashboard_version  = validate( new , required: true , var: 'version'     , type: Integer )
+
+      valid_diff_type = %w[json basic]
+
+      r = validate_hash(diff_type, valid_diff_type)
+
+      return r unless(r == true)
+
+      payload = {
+        base: {
+          dashboardId: base_dashboard_id,
+          version: base_dashboard_version
+        },
+        new: {
+          dashboardId: new_dashboard_id,
+          version: new_dashboard_version
+        },
+        diffType: diff_type
+      }
+
+      endpoint = '/api/dashboards/calculate-diff'
+
+      post(endpoint, payload.to_json)
+    end
 
   end
 

data/lib/grafana/datasource.rb

@@ -44,7 +44,9 @@ module Grafana
     #
     def datasource( datasource_id )
 
-      raise ArgumentError.new(format('wrong type. user \'datasource_id\' must be an String (for an Datasource name) or an Integer (for an Datasource Id), given \'%s\'', datasource_id.class.to_s)) if( datasource_id.is_a?(String) && datasource_id.is_a?(Integer) )
+      if( datasource_id.is_a?(String) && datasource_id.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. \'datasource_id\' must be an String (for an Datasource name) or an Integer (for an Datasource Id), given \'%s\'', datasource_id.class.to_s))
+      end
       raise ArgumentError.new('missing \'datasource_id\'') if( datasource_id.size.zero? )
 
       if(datasource_id.is_a?(String))
@@ -105,27 +107,31 @@ module Grafana
       raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
       raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
 
-      name = validate( params, required: true, var: 'name' )
-      organisation  = validate( params, required: false, var: 'organisation' )
-      type          = validate( params, required: false, var: 'type', type: String )
-      new_name      = validate( params, required: false, var: 'new_name', type: String )
-      database    = validate( params, required: false, var: 'database', type: String )
-      access      = validate( params, required: false, var: 'access', type: String ) || 'proxy'
-      default     = validate( params, required: false, var: 'default', type: Boolean ) || false
-      user        = validate( params, required: false, var: 'user', type: String )
-      password    = validate( params, required: false, var: 'password', type: String )
-      url         = validate( params, required: false, var: 'url', type: String )
-      json_data   = validate( params, required: false, var: 'json_data', type: Hash )
-      ba_user     = validate( params, required: false, var: 'basic_user', type: String )
-      ba_password = validate( params, required: false, var: 'basic_password', type: String )
-      basic_auth  = false
-      basic_auth  = true unless( ba_user.nil? && ba_password.nil? )
-      org_id      = nil
-
-      raise ArgumentError.new(format('wrong type. user \'name\' must be an String (for an Datasource name) or an Integer (for an Datasource Id), given \'%s\'', name.class.to_s)) if( name.is_a?(String) && name.is_a?(Integer) )
-
+      name         = validate( params, required: true , var: 'name' )
+      organisation = validate( params, required: false, var: 'organisation' )
+      type         = validate( params, required: false, var: 'type', type: String )
+      new_name     = validate( params, required: false, var: 'new_name', type: String )
+      database     = validate( params, required: false, var: 'database', type: String )
+      access       = validate( params, required: false, var: 'access', type: String ) || 'proxy'
+      default      = validate( params, required: false, var: 'default', type: Boolean ) || false
+      user         = validate( params, required: false, var: 'user', type: String )
+      password     = validate( params, required: false, var: 'password', type: String )
+      url          = validate( params, required: false, var: 'url', type: String )
+      json_data    = validate( params, required: false, var: 'json_data', type: Hash )
+      ba_user      = validate( params, required: false, var: 'basic_user', type: String )
+      ba_password  = validate( params, required: false, var: 'basic_password', type: String )
+      basic_auth   = false
+      basic_auth   = true unless( ba_user.nil? && ba_password.nil? )
+      org_id       = nil
+
+      if( name.is_a?(String) && name.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. \'name\' must be an String (for an Datasource name) or an Integer (for an Datasource Id), given \'%s\'', name.class.to_s))
+      end
       if( organisation )
-        raise ArgumentError.new(format('wrong type. user \'organisation\' must be an String (for an Organisation name) or an Integer (for an Organisation Id), given \'%s\'', organisation.class.to_s)) if( organisation.is_a?(String) && organisation.is_a?(Integer) )
+        if( organisation.is_a?(String) && organisation.is_a?(Integer) )
+          raise ArgumentError.new(format('wrong type. \'organisation\' must be an String (for an Organisation name) or an Integer (for an Organisation Id), given \'%s\'', organisation.class.to_s))
+        end
+
         org    = organization( organisation )
         org_id = org.dig('id')
 
@@ -170,7 +176,7 @@ module Grafana
       endpoint = format('/api/datasources/%d', datasource_id )
 
       @logger.debug("Updating data source Id #{datasource_id} (GET #{endpoint})") if  @debug
-      logger.debug(payload.to_json) if(@debug)
+#       logger.debug(payload.to_json) if(@debug)
 
       put( endpoint, payload.to_json )
     end
@@ -180,10 +186,8 @@ module Grafana
     # @param [Hash] params
     # @option params [String] type Datasource Type - (required) (grafana graphite cloudwatch elasticsearch prometheus influxdb mysql opentsdb postgres)
     # @option params [String] name  Datasource Name - (required)
-    # @option params [String] database  Datasource Database - (required)
     # @option params [String] access (proxy) Acess Type - (required) (proxy or direct)
     # @option params [Boolean] default (false)
-    # @option params [String] password
     # @option params [String] url Datasource URL - (required)
     # @option params [Hash] json_data
     # @option params [Hash] json_secure
@@ -194,7 +198,6 @@ module Grafana
     #    params = {
     #      name: 'graphite',
     #      type: 'graphite',
-    #      database: 'graphite',
     #      url: 'http://localhost:8080'
     #    }
     #    create_datasource(params)
@@ -202,7 +205,6 @@ module Grafana
     #    params = {
     #      name: 'graphite',
     #      type: 'graphite',
-    #      database: 'graphite',
     #      default: true,
     #      url: 'http://localhost:8080',
     #      json_data: { graphiteVersion: '1.1' }
@@ -231,13 +233,11 @@ module Grafana
       raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
       raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
 
-      type        = validate( params, required: true, var: 'type', type: String )
-      name        = validate( params, required: true, var: 'name', type: String )
-      database    = validate( params, required: true, var: 'database', type: String )
+      type        = validate( params, required: true , var: 'type', type: String )
+      name        = validate( params, required: true , var: 'name', type: String )
       access      = validate( params, required: false, var: 'access', type: String ) || 'proxy'
       default     = validate( params, required: false, var: 'default', type: Boolean ) || false
-      password    = validate( params, required: false, var: 'password', type: String )
-      url         = validate( params, required: true, var: 'url', type: String )
+      url         = validate( params, required: true , var: 'url', type: String )
       json_data   = validate( params, required: false, var: 'json_data', type: Hash )
       json_secure = validate( params, required: false, var: 'json_secure', type: Hash )
       ba_user     = validate( params, required: false, var: 'basic_user', type: String )
@@ -262,14 +262,8 @@ module Grafana
         jsonData: json_data,
         secureJsonData: json_secure
       }
-
       payload.reject!{ |_k, v| v.nil? }
 
-      if( @debug )
-        logger.debug("Creating data source: #{name} (database: #{database})")
-        logger.debug( payload.to_json )
-      end
-
       endpoint = '/api/datasources'
       post(endpoint, payload.to_json)
     end
@@ -286,7 +280,9 @@ module Grafana
     #
     def delete_datasource( datasource_id )
 
-      raise ArgumentError.new(format('wrong type. user \'datasource_id\' must be an String (for an Datasource name) or an Integer (for an Datasource Id), given \'%s\'', datasource_id.class.to_s)) if( datasource_id.is_a?(String) && datasource_id.is_a?(Integer) )
+      if( datasource_id.is_a?(String) && datasource_id.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. \'datasource_id\' must be an String (for an Datasource name) or an Integer (for an Datasource Id), given \'%s\'', datasource_id.class.to_s))
+      end
       raise ArgumentError.new('missing \'datasource_id\'') if( datasource_id.size.zero? )
 
       if(datasource_id.is_a?(String))