Guest Nithya Sivam Posted May 27 Posted May 27 Today, Azure customers navigate across multiple tools, portals and knowledge bases to troubleshoot Azure incidents. Azure is now introducing Help API, an offering that streamlines and simplifies troubleshooting steps by returning relevant solutions associated with the problem, wherever you need them! Help API empowers you and/or your users to access rich, Azure curated self-help solutions, diagnostics and troubleshooters from your preferred interface, without the need to create a support case, thereby putting the power of troubleshooting issues in your own hands, within minutes from when the issue occurs! In this blogpost we will explore key features of Azure Help API from the command line. [HEADING=1]Key features[/HEADING] Whether you are a direct consumer of Azure services or a reseller supporting your end users by troubleshooting issues with Azure resources, you can customize your troubleshooting experience suited to your specific needs, by integrating with Help API. Azure offers a wide range of high-quality solutions that are today only exposed via Azure portal Support + Troubleshooting experiences. Using Help API involves a two-step process. Discovery Solution: This is the first point of entry which returns a set of relevant solutions associated with your problem. This version of Help API does not support natural language functionality (currently in development); hence you can pre-classify your problem with the problem classification API, prior to solutions discovery. Solution execution: Invokes the specific solution to help you resolve the issue. This blogpost specifically focuses, but not limited to 3 most impactful solution offerings: Diagnostics, Azure Solutions and Troubleshooters. [HEADING=1]Setting Up the Environment[/HEADING] [HEADING=3]Prerequisites[/HEADING] Azure CLI: How to install the Azure CLI | Microsoft Learn Azure Subscription Authorization requirements: For diagnostics, you must have reader access role for the resource on which the diagnostics is executed to invoke the diagnostics for that resourceAzure [HEADING=3]Install SelfHelp Extension[/HEADING] Install this extension using the below CLI command. For details on each command, use -h or –help. Az extension add –name self-help [HEADING=1]Exploring Key Features of Self-Help CLI Extension[/HEADING] [HEADING=3]A. Discovery Solutions[/HEADING] DiscoverySolution is the initial entry point within Help API, which returns relevant solutions associated with the problem. Prior to using Discovery Solutions, you must classify your problem using problemclassification API. Discovery Solutions returns a list of relevant diagnostics and solutions using the input parameters : problemclassificationId AND resourceUri or resourceType. The resourceType/resourceUri is optional for discovery solutions, although recommended for targeted solutions. Request Example: # Gets list of solution metadata for an azure resource. az self-help discovery-solution list --filter "ProblemClassificationId eq '00000000-0000-0000-0000-000000000000'" --scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read' Response Example: The discovery solutions response consists of the following properties: Property Definition SolutionId /articleId Unique Identifier of solution/article solutionType Type of Azure solution, example ‘diagnostics’., ‘solutions’, etc description The Azure issue that the solution solves for [HEADING=3]B. Diagnostics[/HEADING] Diagnostics are a powerful solution type that access product resources or other relevant data and provide the root cause of the issue and the steps to address the issue. Diagnostics are invoked using Help API in 2 steps. Step 1: ‘Create diagnostics’ creates a diagnostic for a specific resource using solutionId from discovery solutions Example: # Creates a diagnostic for a resource az self-help diagnostic create –diagnostic-name diagnostic-name –insights [{solutionId:demo2InsightV2}] –scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read' Step 2: ‘Get diagnostics’ gets the diagnostics using the ‘diagnosticsResourceName’ chosen while creating the diagnostic Example: az self-help diagnostic show --diagnostic-name diagnostic-name --scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read' [HEADING=3]C. Solutions[/HEADING] Azure solutions comprise a comprehensive library of self-help resources that have been thoughtfully curated by Azure engineers to enable customers troubleshoot any Azure issue related to their subscription or resource . Azure solutions are a rich library of one or more other impactful solution components such as troubleshooters, diagnostics, data visualizations, video tutorials, diagrams, images, graphs , troubleshooting textual instructions, etc. The unique aspect about ‘solutions’ is that it is a one stop shop for all relevant content associated with your problem and/or resource. To invoke ‘solutions’ you follow 3 steps: Step 1: ‘Create Solution’ creates a solution for the specific Azure resource or subscription using the inputs ‘solutionId’ from discovery solutions Example: # Creates a solution for a resource az self-help solution create --solution-name solution-name --trigger-criteria [{name:solutionid,value:Demo2InsightV2}] --parameters {} --scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/mythe resourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read' Step 2: ‘Get Solution’ gets the solution using the applicable solutionResourceName Example: # Creates a solution for a resource az self-help solution show –solution-name solution-name --scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read' Step 3: ‘Update solution’ updates additional information needed to execute the solution Example: # Updates solution for a resource. az self-help solution update --solution-name solution-name --trigger-criteria [{name:ReplacementKey,value:<!--56ee7509-92e1-4b9e-97c2-dda53065294c-->}] --parameters {SearchText:CanNotRDP,SymptomId:KeyVaultVaultNotFoundInsight} --scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read' [HEADING=3]D. Troubleshooter[/HEADING] Troubleshooters is a type of Azure solutions that dynamically guides you through your troubleshooting steps using a combination of backend resource signals and user inputs through step by step workflows. There are 5 steps to invoke troubleshooters: Step 1: ‘Create Troubleshooter’ creates the specific troubleshooter action under a resource using the ‘solutionId’ as trigger Example: # Creates a troubleshooter for a resource az self-help troubleshooter create –troubleshooter-name 12345678-BBBb-cCCCC-0000-123456789012 --solution-id e104dbdf-9e14-4c9f-bc78-21ac90382231 --parameters {ResourceUri:'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read'} --scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read' Step 2 : ‘Get Troubleshooter’ gets the troubleshooter instance which includes the result of the troubleshooter being executed Example: # Gets a troubleshooter for a resource az self-help troubleshooter show --troubleshooter-name 12345678-BBBb-cCCCC-0000-123456789012 --scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read' Step 3: ‘Restart Troubleshooter’ restarts the troubleshooter API using applicable troubleshooter resource name as the input Example: # Restarts troubleshooter for a resource az self-help troubleshooter restart --troubleshooter-name 12345678-BBBb-cCCCC-0000-123456789012 --scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read' Step 4: ‘End Troubleshooter’ ends the troubleshooter action Example: # Ends a troubleshooter instance az self-help troubleshooter end --troubleshooter-name 12345678-BBBb-cCCCC-0000-123456789012 --scope 'subscriptions/0d0fcd2e-c4fd-4349-8497-200edb3923c6/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read' Step 5: ‘Continue Troubleshooter’ uses ‘stepId’ and ‘responses’ as trigger to continue the troubleshooting steps for the respective troubleshooter Example: # Continues troubleshooter for a resource. az self-help troubleshooter continue --troubleshooter-name 12345678-BBBb-cCCCC-0000-123456789012 --step-id step-id --responses [] --scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read' [HEADING=3]E. CheckNameAvailability[/HEADING] This API is used to check the uniqueness of a resource name used for a diagnostic, troubleshooter or solutions. Example: # Check resource uniqueness Az self-help check-name-availability --scope subscriptions/00000000-0000-0000-0000-000000000000 --name diagnostic-name --type 'Microsoft.Help/diagnostics' az self-help check-name-availability --scope subscriptions/00000000-0000-0000-0000-000000000000 --name solution-name --type 'Microsoft.Help/solutions' az self-help check-name-availability --scope subscriptions/00000000-0000-0000-0000-000000000000 --name 12345678-BBBb-cCCCC-0000-123456789012 --type 'Microsoft.Help/troubleshooters' [HEADING=1]Best Practices[/HEADING] To get relevant solutions always use DiscoverySolutions first, followed by execution of solutions or diagnostics problemclassificationId AND resourceUri will fetch more targeted solutions via DiscoverySolutions Use checknameavailability feature to check for resource name uniqueness, and finally use the solution id found in the response that fits the most of your diagnostics scenario to invoke any of our 3 solution types: diagnostics, solutions, and troubleshooters. [HEADING=1]Send us your feedback[/HEADING] Thank you for exploring the key features of Azure Help API CLI Extension with us. We value your feedback in helping us scale and improve your troubleshooting experience with Help API. If you have feedback or suggestions while using Help API CLI extension, please share your thoughts with us using the following channels. Email: helpapi@microsoft.com Yammer Github The post Self-help support for Azure using Help API : CLI Extension appeared first on Windows Command Line. Continue reading... Quote
Recommended Posts
Join the conversation
You can post now and register later. If you have an account, sign in now to post with your account.