{"id":9403,"date":"2024-01-12T20:31:44","date_gmt":"2024-01-13T04:31:44","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/commandline\/?p=9403"},"modified":"2024-01-12T20:31:44","modified_gmt":"2024-01-13T04:31:44","slug":"self-help-support-for-azure-using-help-api-cli-extension","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/commandline\/self-help-support-for-azure-using-help-api-cli-extension\/","title":{"rendered":"Self-help support for Azure using Help API : CLI Extension"},"content":{"rendered":"<p>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.<\/p>\n<h2>Key features<\/h2>\n<p>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.<\/p>\n<ol>\n<li><strong>Discovery Solution:<\/strong> 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 <a href=\"https:\/\/learn.microsoft.com\/en-us\/cli\/azure\/support\/services\/problem-classifications?view=azure-cli-latest\" rel=\"noopener\" target=\"_blank\">problem classification API<\/a>, prior to solutions discovery. <\/li>\n<li><strong>Solution execution:<\/strong> Invokes the specific solution to help you resolve the issue. <\/li>\n<\/ol>\n<p>This blogpost specifically focuses, but not limited to 3 most impactful solution offerings: Diagnostics, Azure Solutions and Troubleshooters.<\/p>\n<h2>Setting Up the Environment<\/h2>\n<h5>Prerequisites<\/h5>\n<ul>\n<li>Azure CLI: <a href=\"https:\/\/learn.microsoft.com\/en-us\/cli\/azure\/install-azure-cli\" rel=\"noopener\" target=\"_blank\">How to install the Azure CLI | Microsoft Learn<\/a><\/li>\n<li><a href=\"https:\/\/azure.microsoft.com\/en-us\/free\/\" rel=\"noopener\" target=\"_blank\">Azure Subscription<\/a><\/li>\n<li>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 <\/li>\n<\/ul>\n<h5>Install SelfHelp Extension<\/h5>\n<p>Install this extension using the below CLI command. For details on each command, use -h or &#8211;help.<\/p>\n<pre><code class=\"sh\">Az extension add \u2013name self-help\n<\/code><\/pre>\n<h2>Exploring Key Features of Self-Help CLI Extension<\/h2>\n<h5>A. Discovery Solutions<\/h5>\n<p>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 <a href=\"https:\/\/learn.microsoft.com\/en-us\/cli\/azure\/support\/services\/problem-classifications?view=azure-cli-latest\" rel=\"noopener\" target=\"_blank\">problemclassification API<\/a>. 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.<\/p>\n<p>Request Example:<\/p>\n<pre><code class=\"sh\"># Gets list of solution metadata for an azure resource.\naz 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'\n<\/code><\/pre>\n<p>Response Example:<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/commandline\/wp-content\/uploads\/sites\/33\/2024\/01\/Picture1.png\"><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/commandline\/wp-content\/uploads\/sites\/33\/2024\/01\/Picture1-300x124.png\" alt=\"Image Picture1\" width=\"300\" height=\"124\" class=\"alignnone size-medium wp-image-9459\" srcset=\"https:\/\/devblogs.microsoft.com\/commandline\/wp-content\/uploads\/sites\/33\/2024\/01\/Picture1-300x124.png 300w, https:\/\/devblogs.microsoft.com\/commandline\/wp-content\/uploads\/sites\/33\/2024\/01\/Picture1-1024x423.png 1024w, https:\/\/devblogs.microsoft.com\/commandline\/wp-content\/uploads\/sites\/33\/2024\/01\/Picture1-768x317.png 768w, https:\/\/devblogs.microsoft.com\/commandline\/wp-content\/uploads\/sites\/33\/2024\/01\/Picture1-1536x635.png 1536w, https:\/\/devblogs.microsoft.com\/commandline\/wp-content\/uploads\/sites\/33\/2024\/01\/Picture1.png 1628w\" sizes=\"(max-width: 300px) 100vw, 300px\" \/><\/a><\/p>\n<p>The discovery solutions response consists of the following properties:<\/p>\n<table>\n<thead>\n<tr>\n<th>Property<\/th>\n<th>Definition<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>SolutionId \/articleId<\/td>\n<td>Unique Identifier of solution\/article<\/td>\n<\/tr>\n<tr>\n<td>solutionType<\/td>\n<td>Type of Azure solution, example \u2018diagnostics\u2019., \u2018solutions\u2019, etc<\/td>\n<\/tr>\n<tr>\n<td>description<\/td>\n<td>The Azure issue that the solution solves for<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h5>B. Diagnostics<\/h5>\n<p>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.<\/p>\n<p><strong>Step 1: \u2018Create diagnostics\u2019 creates a diagnostic for a specific resource using solutionId from discovery solutions<\/strong><\/p>\n<p>Example:<\/p>\n<pre><code class=\"sh\"># Creates a diagnostic for a resource\n\naz self-help diagnostic create \u2013diagnostic-name diagnostic-name \u2013insights [{solutionId:demo2InsightV2}] \u2013scope 'subscriptions\/00000000-0000-0000-0000-000000000000\/resourceGroups\/myresourceGroup\/providers\/Microsoft.KeyVault\/vaults\/test-keyvault-non-read'\n<\/code><\/pre>\n<p><strong>Step 2: \u2018Get diagnostics\u2019 gets the diagnostics using the \u2018diagnosticsResourceName\u2019 chosen while creating the diagnostic<\/strong><\/p>\n<p>Example:<\/p>\n<pre><code class=\"sh\">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'\n<\/code><\/pre>\n<h5>C. Solutions<\/h5>\n<p>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 \u2018solutions\u2019 is that it is a one stop shop for all relevant content associated with your problem and\/or resource. To invoke \u2018solutions\u2019 you follow 3 steps:<\/p>\n<p><strong>Step 1: \u2018Create Solution\u2019 creates a solution for the specific Azure resource or subscription using the inputs \u2018solutionId\u2019 from discovery solutions<\/strong><\/p>\n<p>Example:<\/p>\n<pre><code class=\"sh\"># Creates a solution for a resource\n\naz 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'\n<\/code><\/pre>\n<p><strong>Step 2: \u2018Get Solution\u2019 gets the solution using the applicable solutionResourceName<\/strong><\/p>\n<p>Example:<\/p>\n<pre><code class=\"sh\"># Creates a solution for a resource\n\naz self-help solution show \u2013solution-name solution-name --scope 'subscriptions\/00000000-0000-0000-0000-000000000000\/resourceGroups\/myresourceGroup\/providers\/Microsoft.KeyVault\/vaults\/test-keyvault-non-read'\n<\/code><\/pre>\n<p><strong>Step 3: \u2018Update solution\u2019 updates additional information needed to execute the solution<\/strong><\/p>\n<p>Example:<\/p>\n<pre><code class=\"sh\"># Updates solution for a resource.\n\naz self-help solution update --solution-name solution-name --trigger-criteria [{name:ReplacementKey,value:&lt;!--56ee7509-92e1-4b9e-97c2-dda53065294c--&gt;}] --parameters {SearchText:CanNotRDP,SymptomId:KeyVaultVaultNotFoundInsight} --scope 'subscriptions\/00000000-0000-0000-0000-000000000000\/resourceGroups\/myresourceGroup\/providers\/Microsoft.KeyVault\/vaults\/test-keyvault-non-read'\n<\/code><\/pre>\n<h5>D. Troubleshooter<\/h5>\n<p>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:<\/p>\n<p><strong>Step 1: \u2018Create Troubleshooter\u2019 creates the specific troubleshooter action under a resource using the \u2018solutionId&#8217; as trigger<\/strong><\/p>\n<p>Example:<\/p>\n<pre><code class=\"sh\"># Creates a troubleshooter for a resource\n\naz self-help troubleshooter create \u2013troubleshooter-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'\n<\/code><\/pre>\n<p><strong>Step 2 : \u2018Get Troubleshooter\u2019 gets the troubleshooter instance which includes the result of the troubleshooter being executed<\/strong><\/p>\n<p>Example:<\/p>\n<pre><code class=\"sh\"># Gets a troubleshooter for a resource\naz 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'\n<\/code><\/pre>\n<p><strong>Step 3: \u2018Restart Troubleshooter\u2019 restarts the troubleshooter API using applicable troubleshooter resource name as the input<\/strong><\/p>\n<p>Example:<\/p>\n<pre><code class=\"sh\"># Restarts troubleshooter for a resource\n\naz 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'\n<\/code><\/pre>\n<p><strong>Step 4: \u2018End Troubleshooter\u2019 ends the troubleshooter action<\/strong><\/p>\n<p>Example:<\/p>\n<pre><code class=\"sh\"># Ends a troubleshooter instance\n\naz 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'\n<\/code><\/pre>\n<p><strong>Step 5: \u2018Continue Troubleshooter\u2019 uses \u2018stepId\u2019 and \u2018responses\u2019 as trigger to continue the troubleshooting steps for the respective troubleshooter<\/strong><\/p>\n<p>Example:<\/p>\n<pre><code class=\"sh\"># Continues troubleshooter for a resource.\n\naz 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'\n<\/code><\/pre>\n<h5>E. CheckNameAvailability<\/h5>\n<p>This API is used to check the uniqueness of a resource name used for a diagnostic, troubleshooter or solutions.<\/p>\n<p>Example:<\/p>\n<pre><code class=\"sh\"># Check resource uniqueness\n\nAz 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' <\/code><\/pre>\n<h2>Best Practices<\/h2>\n<ul>\n<li>To get relevant solutions always use DiscoverySolutions first, followed by execution of solutions or diagnostics <\/li>\n<li>problemclassificationId AND resourceUri will fetch more targeted solutions via DiscoverySolutions <\/li>\n<li>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.<\/li>\n<\/ul>\n<h2>Send us your feedback<\/h2>\n<p>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.<\/p>\n<ul>\n<li>Email: helpapi@microsoft.com<\/li>\n<li><a href=\"https:\/\/web.yammer.com\/main\/org\/microsoft.com\/groups\/eyJfdHlwZSI6Ikdyb3VwIiwiaWQiOiIxMTY0NzkwOTg4ODAifQ\/all\">Yammer<\/a> <\/li>\n<li><a href=\"https:\/\/github.com\/Azure\/azure-rest-api-specs\/issues\">Github<\/a><\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"<p>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, [&hellip;]<\/p>\n","protected":false},"author":122054,"featured_media":4568,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[],"class_list":["post-9403","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-commandline"],"acf":[],"blog_post_summary":"<p>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, [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/commandline\/wp-json\/wp\/v2\/posts\/9403","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/commandline\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/commandline\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/commandline\/wp-json\/wp\/v2\/users\/122054"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/commandline\/wp-json\/wp\/v2\/comments?post=9403"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/commandline\/wp-json\/wp\/v2\/posts\/9403\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/commandline\/wp-json\/wp\/v2\/media\/4568"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/commandline\/wp-json\/wp\/v2\/media?parent=9403"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/commandline\/wp-json\/wp\/v2\/categories?post=9403"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/commandline\/wp-json\/wp\/v2\/tags?post=9403"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}