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.
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.
This blogpost specifically focuses, but not limited to 3 most impactful solution offerings: Diagnostics, Azure Solutions and Troubleshooters.
Install this extension using the below CLI command. For details on each command, use -h or –help.
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:
Response Example:
The discovery solutions response consists of the following properties:
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:
Step 2: ‘Get diagnostics’ gets the diagnostics using the ‘diagnosticsResourceName’ chosen while creating the diagnostic
Example:
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:
Step 2: ‘Get Solution’ gets the solution using the applicable solutionResourceName
Example:
Step 3: ‘Update solution’ updates additional information needed to execute the solution
Example:
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:
Step 2 : ‘Get Troubleshooter’ gets the troubleshooter instance which includes the result of the troubleshooter being executed
Example:
Step 3: ‘Restart Troubleshooter’ restarts the troubleshooter API using applicable troubleshooter resource name as the input
Example:
Step 4: ‘End Troubleshooter’ ends the troubleshooter action
Example:
Step 5: ‘Continue Troubleshooter’ uses ‘stepId’ and ‘responses’ as trigger to continue the troubleshooting steps for the respective troubleshooter
Example:
This API is used to check the uniqueness of a resource name used for a diagnostic, troubleshooter or solutions.
Example:
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.
The post Self-help support for Azure using Help API : CLI Extension appeared first on Windows Command Line.
Continue reading...
Key features
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.
Setting Up the Environment
Prerequisites
- 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
Install SelfHelp Extension
Install this extension using the below CLI command. For details on each command, use -h or –help.
Code:
Az extension add –name self-help
Exploring Key Features of Self-Help CLI Extension
A. Discovery Solutions
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:
Code:
# 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 |
B. Diagnostics
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:
Code:
# 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:
Code:
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'
C. Solutions
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:
Code:
# 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:
Code:
# 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:
Code:
# 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'
D. Troubleshooter
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:
Code:
# 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:
Code:
# 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:
Code:
# 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:
Code:
# 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:
Code:
# 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'
E. CheckNameAvailability
This API is used to check the uniqueness of a resource name used for a diagnostic, troubleshooter or solutions.
Example:
Code:
# 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'
Best Practices
- 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.
Send us your feedback
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...