folderUid fix for deprecated api

Author: Alan Zhang

src/amg/HISTORY.rst

@@ -172,3 +172,8 @@ Release History
 3.1.0
 ++++++
 * Support dynamic dashboards schema
+
+3.1.1
+++++++
+* `az grafana dashboard`, `az grafana restore`, `az grafana migrate`: use folder UIDs instead of numeric IDs to preserve dashboard and library panel folder placement
+* `az grafana restore`, `az grafana migrate`: preserve library panel folders when overwriting existing panels

src/amg/azext_amg/custom.py

@@ -22,7 +22,8 @@
 from ._client_factory import cf_amg
 from .utils import get_yes_or_no_option, search_folders
 from .dashboard_v2 import (is_v2_dashboard_definition, require_dashboard_v2_api_version,
-                           create_dashboard_v2, resolve_dashboard_v2_api_version, read_dashboard)
+                           create_dashboard_v2, resolve_dashboard_v2_api_version, read_dashboard,
+                           dashboard_folder_uid)
 
 logger = get_logger(__name__)
 
@@ -384,8 +385,11 @@ def _create_dashboard(cmd, grafana_name, definition, title=None, folder_uid=None
     if title:
         payload['dashboard']['title'] = title
 
-    if folder_uid:
+    if folder_uid is not None:
         payload['folderUid'] = folder_uid
+    elif 'folderId' in payload:
+        payload['folderUid'] = dashboard_folder_uid(payload)
+    payload.pop('folderId', None)
 
     payload['overwrite'] = overwrite or False
 
@@ -435,8 +439,12 @@ def import_dashboard(cmd, grafana_name, definition, folder=None, resource_group_
         payload['dashboard'] = data
 
     if folder:
-        folder = _find_folder(cmd, resource_group_name, grafana_name, folder)
-        payload['folderId'] = folder['id']
+        folder = _find_folder(cmd, resource_group_name, grafana_name, folder,
+                              api_key_or_token=api_key_or_token)
+        payload['folderUid'] = folder['uid']
+    elif 'folderId' in payload:
+        payload['folderUid'] = dashboard_folder_uid(payload)
+    payload.pop('folderId', None)
 
     payload['overwrite'] = overwrite or False
     payload['inputs'] = []

src/amg/azext_amg/dashboard_v2.py

@@ -10,6 +10,8 @@
 
 import copy
 import json
+import re
+from urllib.parse import urlsplit
 
 import requests
 
@@ -177,10 +179,43 @@ def dashboard_identity(content):
 
 
 def dashboard_folder_uid(content):
-    # Return the folder uid for either a classic {meta, dashboard} object or a v2 resource.
+    # Older backups identify folders by URL; newer dashboards and library panels expose a UID.
     if is_v2_dashboard_definition(content):
         return content.get("metadata", {}).get("annotations", {}).get("grafana.app/folder", "")
-    return content.get("meta", {}).get("folderUid", "")
+
+    meta = content.get("meta", {})
+    if not isinstance(meta, dict):
+        raise ArgumentUsageError("The definition's 'meta' field must be an object.")
+
+    folder_uid = content.get("folderUid")
+    if folder_uid is None:
+        folder_uid = meta.get("folderUid")
+    if folder_uid is not None:
+        if not isinstance(folder_uid, str):
+            raise ArgumentUsageError("The definition's 'folderUid' field must be a string.")
+        return "" if folder_uid == "general" else folder_uid
+
+    folder_url = meta.get("folderUrl")
+    if folder_url is not None and not isinstance(folder_url, str):
+        raise ArgumentUsageError("The definition's 'folderUrl' field must be a string.")
+    if folder_url:
+        try:
+            folder_path = urlsplit(folder_url).path
+        except ValueError as ex:
+            raise ArgumentUsageError("The definition's 'folderUrl' field must be a valid URL.") from ex
+        match = re.search(r"(?:^|/)dashboards/f/([^/]+)(?:/|$)", folder_path)
+        if match:
+            folder_uid = match.group(1)
+            return "" if folder_uid == "general" else folder_uid
+        if folder_path.rstrip("/").split("/")[-1] == "dashboards":
+            return ""
+        raise ArgumentUsageError("The definition's 'folderUrl' does not identify a Grafana folder. "
+                                 "Supply 'folderUid' instead.")
+
+    if content.get("folderId", meta.get("folderId")):
+        raise ArgumentUsageError("The definition has a numeric 'folderId' but no folder UID. "
+                                 "Supply 'folderUid' instead.")
+    return ""
 
 
 def remap_v2_datasource_uids(node, uid_mapping):

src/amg/azext_amg/migrate.py

@@ -59,8 +59,7 @@ def migrate(backup_url, backup_headers, restore_url, restore_headers, dry_run,
     if 'general' in folders_to_include_set or 'general' not in folders_to_exclude_set:
         valid_folder_uids.add('')
 
-    # needs to be meta since in Grafana 8, the folderUid is in the meta.
-    all_lib_panels_filtered = [p for p in all_source_lib_panels if p['meta']['folderUid'] in valid_folder_uids]
+    all_lib_panels_filtered = [p for p in all_source_lib_panels if dashboard_folder_uid(p) in valid_folder_uids]
     (library_panels_created_summary,
      library_panels_overwrote_summary,
      dashboards_created_summary,

src/amg/azext_amg/restore.py

@@ -15,11 +15,11 @@
 from azure.cli.core.style import print_styled_text, Style
 from knack.log import get_logger
 
-from .utils import (get_folder_id, send_grafana_post, send_grafana_patch, send_grafana_put, send_grafana_delete,
+from .utils import (send_grafana_post, send_grafana_patch, send_grafana_put, send_grafana_delete,
                     send_grafana_get, create_datasource_mapping, remap_datasource_uids, get_snapshot,
                     search_annotations)
 from .dashboard_v2 import (is_v2_dashboard_definition, require_dashboard_v2_api_version,
-                           create_dashboard_v2, remap_v2_datasource_uids)
+                           create_dashboard_v2, remap_v2_datasource_uids, dashboard_folder_uid)
 
 logger = get_logger(__name__)
 
@@ -102,7 +102,7 @@ def create_dashboard(grafana_url, content, http_headers, overwrite):
 
     payload = {
         'dashboard': content['dashboard'],
-        'folderId': get_folder_id(content, grafana_url, http_post_headers=http_headers),
+        'folderUid': dashboard_folder_uid(content),
         'overwrite': overwrite
     }
 
@@ -166,8 +166,8 @@ def _load_and_create_library_panel(grafana_url, file_path, http_headers):
 
 
 def create_library_panel(grafana_url, payload, http_headers, overwrite):
-    # set the folder id of the library panel
-    payload['folderId'] = get_folder_id(payload, grafana_url, http_post_headers=http_headers)
+    payload['folderUid'] = dashboard_folder_uid(payload)
+    payload.pop('folderId', None)
 
     datasources_missed = set()
     remap_datasource_uids(payload, uid_mapping, datasources_missed)
@@ -186,7 +186,8 @@ def create_library_panel(grafana_url, payload, http_headers, overwrite):
                     'name': panel_name,
                     'model': payload['model'],
                     'version': content['result']['version'],
-                    'kind': payload['kind']
+                    'kind': payload['kind'],
+                    'folderUid': payload['folderUid']
                 }
                 (status, content) = send_grafana_patch(f'{grafana_url}/api/library-elements/{uid}',
                                                        json.dumps(patch_payload), http_headers)