Module: Grafana::Folder

Included in:
Client
Defined in:
lib/grafana/folder.rb

Overview

docs.grafana.org/http_api/folder/#folder-api

Instance Method Summary collapse

Instance Method Details

#create_folder(params) ⇒ Object

Create folder POST /api/folders

Creates a new folder. JSON Body schema:

uid   - Optional unique identifier.
title - The title of the folder.

Raises:

  • (ArgumentError) 


79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/grafana/folder.rb', line 79

def create_folder( 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( 'folder has been supported in Grafana since version 5. you use version %s', v) } if(mv < 5)

  title = validate( params, required: false, var: 'title', type: String )
  uid   = validate( params, required: true , var: 'uid'  , type: String )

  return { 'status' => 404, 'message' => format( 'The uid can have a maximum length of 40 characters. \'%s\' given', uid.length) } if( uid.length > 40 )

  data = {
    uid: uid,
    title: title
  }
  data.reject!{ |_, y| y.nil? }

  payload = data.deep_string_keys

  endpoint = '/api/folders'

  @logger.debug("create folder #{title} (GET #{endpoint})") if  @debug
  logger.debug(payload.to_json) if(@debug)

  post( endpoint, payload.to_json )
end

#delete_folder(folder_uid) ⇒ Object

Delete folder DELETE /api/folders/:uid

Deletes an existing folder identified by uid together with all dashboards stored in the folder, if any. This operation cannot be reverted.

Raises:

  • (ArgumentError) 


164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/grafana/folder.rb', line 164

def delete_folder( folder_uid )

  raise ArgumentError.new(format('wrong type. user \'folder_uid\' must be an String (for an Folder Uid) or an Integer (for an Folder Id), given \'%s\'', folder_uid.class.to_s)) \
      if( folder_uid.is_a?(String) && folder_uid.is_a?(Integer) )
  raise ArgumentError.new('missing \'folder_uid\'') if( folder_uid.size.zero? )

  v, mv = version.values
  return { 'status' => 404, 'message' => format( 'folder has been supported in Grafana since version 5. you use version %s', v) } if(mv < 5)

  if(folder_uid.is_a?(Integer))

    fldrs  = folders

    fldrs  = JSON.parse(fldrs) if(fldrs.is_a?(String))
    status = fldrs.dig('status')

    return fldrs if( status != 200 )

    fldrs.dig('message').each do |d|
      folder_uid = d.dig('uid').to_s
    end
  end

  return { 'status' => 404, 'message' => format( 'No User \'%s\' found', folder_uid) } if( folder_uid.nil? )

  endpoint = format( '/api/folders/%s', folder_uid )

  @logger.debug("deleting folder by uid #{folder_uid} (GET #{endpoint})") if @debug
  delete(endpoint)
end

#folder(folder_uid) ⇒ Object

Get folder by uid GET /api/folders/:uid

Will return the folder given the folder uid.

Get folder by id GET /api/folders/:id

Will return the folder identified by id.

Raises:

  • (ArgumentError) 


35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/grafana/folder.rb', line 35

def folder( folder_uid )

  raise ArgumentError.new(format('wrong type. user \'folder_uid\' must be an String (for an Folder Uid) or an Integer (for an Folder Id), given \'%s\'', folder_uid.class.to_s)) \
      if( folder_uid.is_a?(String) && folder_uid.is_a?(Integer) )
  raise ArgumentError.new('missing \'folder_uid\'') if( folder_uid.size.zero? )

  v, mv = version.values
  return { 'status' => 404, 'message' => format( 'folder has been supported in Grafana since version 5. you use version %s', v) } if(mv < 5)

  if(folder_uid.is_a?(Integer))

    f  = folders
    f  = JSON.parse(f) if(f.is_a?(String))

    status = f.dig('status')
    return f if( status != 200 )

    f = f.dig('message').detect {|x| x['id'] == folder_uid }

    return { 'status' => 404, 'message' => format( 'No Folder \'%s\' found', folder_uid) } if( folder_uid.nil? )

    folder_uid = f.dig('uid') unless(f.nil?)

    return { 'status' => 404, 'message' => format( 'No Folder \'%s\' found', folder_uid) } if( folder_uid.is_a?(Integer) )
  end

  return { 'status' => 404, 'message' => format( 'The uid can have a maximum length of 40 characters, but it is %s characters long', folder_uid.length) } \
      if( folder_uid.is_a?(String) && folder_uid.length > 40 )
  return { 'status' => 404, 'message' => format( 'No Folder \'%s\' found', folder_uid) } if( folder_uid.nil? )

  endpoint = format( '/api/folders/%s', folder_uid )

  @logger.debug("Getting folder by Id #{folder_uid} (GET #{endpoint})") if @debug
  get(endpoint)
end

#folders ⇒ Hash

Get all folders GET /api/folders Returns all folders that the authenticated user has permission to view.

Examples:

folders

Returns:



16
17
18
19
20
21
22
23
24
 
# File 'lib/grafana/folder.rb', line 16

def folders

  v, mv = version.values
  return { 'status' => 404, 'message' => format( 'folder has been supported in Grafana since version 5. you use version %s', v) } if(mv < 5)

  endpoint = '/api/folders'
  @logger.debug("Getting all folders (GET #{endpoint})") if @debug
  get(endpoint)
end

#update_folder(params) ⇒ Object

Update folder PUT /api/folders/:uid

schould be fail, when the version are not incremented overwrite helps

Updates an existing folder identified by uid. JSON Body schema:

- uid - Provide another unique identifier than stored to change the unique identifier.
- title - The title of the folder.
- version - Provide the current version to be able to update the folder. Not needed if overwrite=true.
- overwrite - Set to true if you want to overwrite existing folder with newer version.

Raises:

  • (ArgumentError) 


121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/grafana/folder.rb', line 121

def update_folder( 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( 'folder has been supported in Grafana since version 5. you use version %s', v) } if(mv < 5)

  uid       = validate( params, required: true , var: 'uid'      , type: String )
  title     = validate( params, required: true , var: 'title'    , type: String )
  new_uid   = validate( params, required: false, var: 'new_uid'  , type: String )
  version   = validate( params, required: false, var: 'version'  , type: Integer )
  overwrite = validate( params, required: false, var: 'overwrite', type: Boolean ) || false

  existing_folder = folder( uid )
  return { 'status' => 404, 'message' => format( 'No Folder \'%s\' found', uid) } if( existing_folder.dig('status') != 200 )

  unless( new_uid.nil? )
    existing_folder = folder( new_uid )
    return { 'status' => 404, 'message' => format( 'Folder \'%s\' found', uid) } if( existing_folder.dig('status') == 200 )
  end

  payload = {
    title: title,
    uid: new_uid,
    version: version,
    overwrite: overwrite
  }
  payload.reject!{ |_, y| y.nil? }

  @logger.debug("Updating folder with Uid #{uid}") if @debug

  endpoint = format( '/api/folders/%s', uid )

  put( endpoint, payload.to_json )
end