Udostępnij za pośrednictwem

Programowe zarządzanie skoroszytami

  • Artykuł

Właściciele zasobów mogą programowo tworzyć skoroszyty i zarządzać nimi za pomocą szablonów usługi Azure Resource Manager (szablonów usługi ARM).

Ta funkcja może być przydatna w scenariuszach, takich jak:

  • Wdrażanie raportów analitycznych specyficznych dla organizacji lub domeny wraz z wdrożeniami zasobów. Można na przykład wdrożyć skoroszyty wydajności i awarii specyficzne dla organizacji dla nowych aplikacji lub maszyn wirtualnych.
  • Wdrażanie standardowych raportów lub pulpitów nawigacyjnych przy użyciu skoroszytów dla istniejących zasobów.

Skoroszyt zostanie utworzony w żądanej podgrupie/grupie zasobów i zawartości określonej w szablonach usługi ARM.

Dwa typy zasobów skoroszytu można zarządzać programowo:

Szablon usługi ARM do wdrażania szablonu skoroszytu

  1. Otwórz skoroszyt, który chcesz wdrożyć programowo.

  2. Przełącz skoroszyt do trybu edycji, wybierając pozycję Edytuj.

  3. Otwórz Edytor zaawansowany przy użyciu< przycisku /> na pasku narzędzi.

  4. Upewnij się, że jesteś na karcie Szablon galerii.

    Screenshot that shows the Gallery Template tab.

  5. Skopiuj kod JSON w szablonie galerii do schowka.

  6. Poniższy przykładowy szablon usługi ARM wdraża szablon skoroszytu w galerii skoroszytów usługi Azure Monitor. Wklej skopiowany kod JSON zamiast .<PASTE-COPIED-WORKBOOK_TEMPLATE_HERE> Aby zapoznać się z szablonem usługi ARM, który tworzy szablon skoroszytu, zobacz to repozytorium GitHub.

    {
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "resourceName": {
            "type": "string",
            "defaultValue": "my-workbook-template",
            "metadata": {
                "description": "The unique name for this workbook template instance"
            }
        }
    },
    "resources": [
        {
            "name": "[parameters('resourceName')]",
            "type": "microsoft.insights/workbooktemplates",
            "location": "[resourceGroup().location]",
            "apiVersion": "2019-10-17-preview",
            "dependsOn": [],
            "properties": {
                "galleries": [
                    {
                        "name": "A Workbook Template",
                        "category": "Deployed Templates",
                        "order": 100,
                        "type": "workbook",
                        "resourceType": "Azure Monitor"
                    }
                ],
                "templateData": <PASTE-COPIED-WORKBOOK_TEMPLATE_HERE>
            }
        }
    ]
}

  7. galleries W obiekcie wypełnij name wartości i category . Dowiedz się więcej o parametrach w następnej sekcji.

  8. Wdróż ten szablon usługi ARM przy użyciu witryny Azure Portal, interfejsu wiersza polecenia lub programu PowerShell.

  9. Otwórz witrynę Azure Portal i przejdź do galerii skoroszytów wybranej w szablonie usługi ARM. W przykładowym szablonie przejdź do galerii skoroszytów usługi Azure Monitor:

    1. Otwórz witrynę Azure Portal i przejdź do usługi Azure Monitor.
    2. Otwórz Workbooks z spisu treści.
    3. Znajdź szablon w galerii w kategorii Deployed Templates. (Będzie to jeden z fioletowych elementów).

Parametry

Parametry Wyjaśnienie
name Nazwa zasobu szablonu skoroszytu w usłudze Azure Resource Manager.
type Zawsze microsoft.insights/workbooktemplates.
location Lokalizacja platformy Azure, w której zostanie utworzony skoroszyt.
apiVersion Wersja zapoznawcza 2019-10-17.
type Zawsze microsoft.insights/workbooktemplates.
galleries Zestaw galerii, w których ma być wyświetlany ten szablon skoroszytu.
gallery.name Przyjazna nazwa szablonu skoroszytu w galerii.
gallery.category Grupa w galerii, w której ma być umieszczany szablon.
gallery.order Liczba, która decyduje o zamówieniu wyświetlania szablonu w kategorii w galerii. Niższa kolejność oznacza wyższy priorytet.
gallery.resourceType Typ zasobu odpowiadający galerii. Ten typ jest zazwyczaj ciągiem typu zasobu odpowiadającym zasobowi (na przykład microsoft.operationalinsights/workspaces).
gallery.type Określany jako typ skoroszytu. Ten unikatowy klucz rozróżnia galerię w obrębie typu zasobu. Na przykład Szczegółowe informacje aplikacji mają typy workbook i tsg odpowiadają różnym galeriom skoroszytów.

Galerie

Galeria Typ zasobu Typ skoroszytu
Skoroszyty w usłudze Azure Monitor Azure Monitor workbook
Szczegółowe informacje maszyny wirtualnej w usłudze Azure Monitor Azure Monitor vm-insights
Skoroszyty w obszarze roboczym usługi Log Analytics microsoft.operationalinsights/workspaces workbook
Skoroszyty w Szczegółowe informacje aplikacji microsoft.insights/components workbook
Przewodniki rozwiązywania problemów w usłudze Application Szczegółowe informacje microsoft.insights/components tsg
Użycie w Szczegółowe informacje aplikacji microsoft.insights/components usage
Skoroszyty w usłudze Kubernetes Microsoft.ContainerService/managedClusters workbook
Skoroszyty w grupach zasobów microsoft.resources/subscriptions/resourcegroups workbook
Skoroszyty w identyfikatorze Entra firmy Microsoft microsoft.aadiam/tenant workbook
Szczegółowe informacje maszyn wirtualnych na maszynach wirtualnych microsoft.compute/virtualmachines insights
Szczegółowe informacje maszyn wirtualnych w zestawach skalowania maszyn wirtualnych microsoft.compute/virtualmachinescalesets insights

Szablon usługi ARM do wdrażania wystąpienia skoroszytu

  1. Otwórz skoroszyt, który chcesz wdrożyć programowo.
  2. Przełącz skoroszyt do trybu edycji, wybierając pozycję Edytuj.
  3. Otwórz Edytor zaawansowany, wybierając< pozycję />.
  4. W edytorze przełącz typ szablonu na szablon usługi ARM.
  5. Szablon usługi ARM do tworzenia jest wyświetlany w edytorze. Skopiuj zawartość i użyj wartości as-is lub scal ją z większym szablonem, który również wdraża zasób docelowy. Screenshot that shows how to get the ARM template from within the workbook UI.

Przykładowy szablon ARM

W tym szablonie pokazano, jak wdrożyć skoroszyt, który wyświetla Hello World!element .

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "workbookDisplayName":  {             
            "type":"string",
            "defaultValue": "My Workbook",
            "metadata": {
                "description": "The friendly name for the workbook that is used in the Gallery or Saved List. Needs to be unique in the scope of the resource group and source" 
            }
        },
        "workbookType":  {             
            "type":"string",
            "defaultValue": "tsg",
            "metadata": {
                "description": "The gallery that the workbook will be shown under. Supported values include workbook, `tsg`, Azure Monitor, etc." 
            }
        },
        "workbookSourceId":  {             
            "type":"string",
            "defaultValue": "<insert-your-resource-id-here>",
            "metadata": {
                "description": "The id of resource instance to which the workbook will be associated" 
            }
        },
        "workbookId": {
            "type":"string",
            "defaultValue": "[newGuid()]",
            "metadata": {
                "description": "The unique guid for this workbook instance" 
            }
        }
    },    
    "resources": [
        {
            "name": "[parameters('workbookId')]",
            "type": "Microsoft.Insights/workbooks",
            "location": "[resourceGroup().location]",
            "kind": "shared",
            "apiVersion": "2018-06-17-preview",
            "dependsOn": [],
            "properties": {
                "displayName": "[parameters('workbookDisplayName')]",
                "serializedData": "{\"version\":\"Notebook/1.0\",\"items\":[{\"type\":1,\"content\":\"{\\\"json\\\":\\\"Hello World!\\\"}\",\"conditionalVisibility\":null}],\"isLocked\":false}",
                "version": "1.0",
                "sourceId": "[parameters('workbookSourceId')]",
                "category": "[parameters('workbookType')]"
            }
        }
    ],
    "outputs": {
        "workbookId": {
            "type": "string",
            "value": "[resourceId( 'Microsoft.Insights/workbooks', parameters('workbookId'))]"
        }
    }
}

Parametry szablonu

Parametr Opis
workbookDisplayName Przyjazna nazwa skoroszytu używanego w galerii lub zapisanej liście. Musi być unikatowa w zakresie grupy zasobów i źródła.
workbookType Galeria, w której jest wyświetlany skoroszyt. Obsługiwane wartości obejmują skoroszyt, tsgi usługę Azure Monitor.
workbookSourceId Identyfikator wystąpienia zasobu, z którym zostanie skojarzony skoroszyt. Nowy skoroszyt zostanie wyświetlony w związku z tym wystąpieniem zasobu, na przykład w spisie treści zasobu w obszarze Skoroszyt. Jeśli chcesz, aby skoroszyt był wyświetlany w galerii Skoroszyty w usłudze Azure Monitor, użyj ciągu Azure Monitor zamiast identyfikatora zasobu.
workbookId Unikatowy identyfikator GUID dla tego wystąpienia skoroszytu. Użyj [newGuid()] polecenia , aby automatycznie utworzyć nowy identyfikator GUID.
kind Służy do określania, czy utworzony skoroszyt jest udostępniony. Wszystkie nowe skoroszyty będą używać wartości udostępnionej.
location Lokalizacja platformy Azure, w której zostanie utworzony skoroszyt. Użyj [resourceGroup().location] polecenia , aby utworzyć ją w tej samej lokalizacji co grupa zasobów.
serializedData Zawiera zawartość lub ładunek do użycia w skoroszycie. Użyj szablonu usługi ARM z interfejsu użytkownika skoroszytów, aby uzyskać wartość.

Typy skoroszytów

Typy skoroszytów określają typ galerii skoroszytów, w którym pojawia się nowe wystąpienie skoroszytu. Dostępne opcje:

Typ Lokalizacja galerii
workbook Wartość domyślna używana w większości raportów, w tym galeria skoroszytów aplikacji Szczegółowe informacje i usługi Azure Monitor.
tsg Galeria Przewodników rozwiązywania problemów w aplikacji Szczegółowe informacje.
usage Galeria Więcej w obszarze Użycie w aplikacji Szczegółowe informacje.

Praca z danymi skoroszytu sformatowanymi w formacie JSON w parametrze szablonu serializedData

Podczas eksportowania szablonu usługi ARM dla skoroszytu platformy Azure często istnieją stałe linki zasobów osadzone w wyeksportowanym serializedData parametrze szablonu. Te linki obejmują potencjalnie poufne wartości, takie jak identyfikator subskrypcji i nazwa grupy zasobów oraz inne typy identyfikatorów zasobów.

W poniższym przykładzie pokazano dostosowywanie wyeksportowanego szablonu usługi ARM skoroszytu bez uciekania się do manipulowania ciągami. Wzorzec pokazany w tym przykładzie jest przeznaczony do pracy z niezmierzonym danymi wyeksportowanymi z witryny Azure Portal. Najlepszym rozwiązaniem jest również zamaskowywanie wszelkich osadzonych wartości poufnych podczas programowego zarządzania skoroszytami. Z tego powodu identyfikator subskrypcji i grupa zasobów zostały tutaj zamaskowane. Żadne inne modyfikacje nie zostały wprowadzone do nieprzetworzonej wartości przychodzącej serializedData .

{
  "contentVersion": "1.0.0.0",
  "parameters": {
    "workbookDisplayName": {
      "type": "string"
    },
    "workbookSourceId": {
      "type": "string",
      "defaultValue": "[resourceGroup().id]"
    },
    "workbookId": {
      "type": "string",
      "defaultValue": "[newGuid()]"
    }
  },
  "variables": {
    // serializedData from original exported Azure Resource Manager template
    "serializedData": "{\"version\":\"Notebook/1.0\",\"items\":[{\"type\":1,\"content\":{\"json\":\"Replace with Title\"},\"name\":\"text - 0\"},{\"type\":3,\"content\":{\"version\":\"KqlItem/1.0\",\"query\":\"{\\\"version\\\":\\\"ARMEndpoint/1.0\\\",\\\"data\\\":null,\\\"headers\\\":[],\\\"method\\\":\\\"GET\\\",\\\"path\\\":\\\"/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/resourceGroups\\\",\\\"urlParams\\\":[{\\\"key\\\":\\\"api-version\\\",\\\"value\\\":\\\"2019-06-01\\\"}],\\\"batchDisabled\\\":false,\\\"transformers\\\":[{\\\"type\\\":\\\"jsonpath\\\",\\\"settings\\\":{\\\"tablePath\\\":\\\"$..*\\\",\\\"columns\\\":[]}}]}\",\"size\":0,\"queryType\":12,\"visualization\":\"map\",\"tileSettings\":{\"showBorder\":false},\"graphSettings\":{\"type\":0},\"mapSettings\":{\"locInfo\":\"AzureLoc\",\"locInfoColumn\":\"location\",\"sizeSettings\":\"location\",\"sizeAggregation\":\"Count\",\"opacity\":0.5,\"legendAggregation\":\"Count\",\"itemColorSettings\":null}},\"name\":\"query - 1\"}],\"isLocked\":false,\"fallbackResourceIds\":[\"/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/resourceGroups/XXXXXXX\"]}",

    // parse the original into a JSON object, so that it can be manipulated
    "parsedData": "[json(variables('serializedData'))]",

    // create new JSON objects that represent only the items/properties to be modified
    "updatedTitle": {
      "content":{
        "json": "[concat('Resource Group Regions in subscription \"', subscription().displayName, '\"')]"
      }
    },
    "updatedMap": {
      "content": {
        "path": "[concat('/subscriptions/', subscription().subscriptionId, '/resourceGroups')]"
      }
    },

    // the union function applies the updates to the original data
    "updatedItems": [
      "[union(variables('parsedData')['items'][0], variables('updatedTitle'))]",
      "[union(variables('parsedData')['items'][1], variables('updatedMap'))]"
    ],

    // copy to a new workbook object, with the updated items
    "updatedWorkbookData": {
      "version": "[variables('parsedData')['version']]",
      "items": "[variables('updatedItems')]",
      "isLocked": "[variables('parsedData')['isLocked']]",
      "fallbackResourceIds": ["[parameters('workbookSourceId')]"]
    },

    // convert back to an encoded string
    "reserializedData": "[string(variables('updatedWorkbookData'))]"
  },
  "resources": [
    {
      "name": "[parameters('workbookId')]",
      "type": "microsoft.insights/workbooks",
      "location": "[resourceGroup().location]",
      "apiVersion": "2018-06-17-preview",
      "dependsOn": [],
      "kind": "shared",
      "properties": {
        "displayName": "[parameters('workbookDisplayName')]",
        "serializedData": "[variables('reserializedData')]",
        "version": "1.0",
        "sourceId": "[parameters('workbookSourceId')]",
        "category": "workbook"
      }
    }
  ],
  "outputs": {
    "workbookId": {
      "type": "string",
      "value": "[resourceId( 'microsoft.insights/workbooks', parameters('workbookId'))]"
    }
  },
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#"
}

W tym przykładzie następujące kroki ułatwiają dostosowanie wyeksportowanego szablonu usługi ARM:

  1. Wyeksportuj skoroszyt jako szablon usługi ARM, jak wyjaśniono w poprzedniej sekcji.
  2. W sekcji szablonu variables :
    1. serializedData Przeanalizuj wartość w zmiennej obiektu JSON, która tworzy strukturę JSON, w tym tablicę elementów reprezentujących zawartość skoroszytu.
    2. Utwórz nowe obiekty JSON reprezentujące tylko elementy/właściwości do zmodyfikowania.
    3. Projektuj nowy zestaw elementów zawartości JSON (updatedItems) przy użyciu union() funkcji , aby zastosować modyfikacje do oryginalnych elementów JSON.
    4. Utwórz nowy obiekt skoroszytu , updatedWorkbookDatazawierający updatedItems iisLockedversion/dane z oryginalnych analizowanych danych oraz poprawiony zestaw .fallbackResourceIds
    5. Serializuj nową zawartość JSON z powrotem do nowej zmiennej ciągu, reserializedData.
  3. Użyj nowej reserializedData zmiennej zamiast oryginalnej serializedData właściwości.
  4. Wdróż nowy zasób skoroszytu przy użyciu zaktualizowanego szablonu usługi ARM.

Następne kroki

Dowiedz się, jak skoroszyty są używane do obsługi nowego środowiska szczegółowych informacji usługi Storage.