Programowe zarządzanie skoroszytami

Artykuł
11/05/2024

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:

Szablony skoroszytów
Wystąpienia skoroszytu

Szablon usługi ARM do wdrażania szablonu skoroszytu

Otwórz skoroszyt, który chcesz wdrożyć programowo.
Przełącz skoroszyt do trybu edycji, wybierając pozycję Edytuj.
Otwórz Edytor zaawansowany przy użyciu< przycisku /> na pasku narzędzi.
Upewnij się, że jesteś na karcie Szablon galerii.
Skopiuj kod JSON w szablonie galerii do schowka.

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>
            }
        }
    ]
}

galleries W obiekcie wypełnij name wartości i category . Dowiedz się więcej o parametrach w następnej sekcji.
Wdróż ten szablon usługi ARM przy użyciu witryny Azure Portal, interfejsu wiersza polecenia lub programu PowerShell.
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. Usługa Application Insights zawiera na przykład 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 o maszynach wirtualnych w usłudze Azure Monitor	`Azure Monitor`	`vm-insights`
Skoroszyty w obszarze roboczym usługi Log Analytics	`microsoft.operationalinsights/workspaces`	`workbook`
Skoroszyty w usłudze Application Insights	`microsoft.insights/components`	`workbook`
Przewodniki rozwiązywania problemów w usłudze Application Insights	`microsoft.insights/components`	`tsg`
Użycie w usłudze Application Insights	`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 o maszynach wirtualnych	`microsoft.compute/virtualmachines`	`insights`
Usługa VM Insights w zestawach skalowania maszyn wirtualnych	`microsoft.compute/virtualmachinescalesets`	`insights`

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

Otwórz skoroszyt, który chcesz wdrożyć programowo.
Przełącz skoroszyt do trybu edycji, wybierając pozycję Edytuj.
Otwórz Edytor zaawansowany, wybierając< pozycję />.
W edytorze przełącz typ szablonu na szablon usługi ARM.
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.

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, `tsg`i 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 usługi Application Insights i usługi Azure Monitor.
`tsg`	Galeria Przewodników rozwiązywania problemów w usłudze Application Insights.
`usage`	Galeria Więcej w obszarze Użycie w usłudze Application Insights.

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:

Wyeksportuj skoroszyt jako szablon usługi ARM, jak wyjaśniono w poprzedniej sekcji.
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 iisLocked version/dane z oryginalnych analizowanych danych oraz poprawiony zestaw .fallbackResourceIds
5. Serializuj nową zawartość JSON z powrotem do nowej zmiennej ciągu, reserializedData.
Użyj nowej reserializedData zmiennej zamiast oryginalnej serializedData właściwości.
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.

Udostępnij za pośrednictwem