Merge pull request #94521 from v-rihow/create-share-query

ShawnJackson · web-flow · commit ff0b5dc54235 · 2019-11-04T18:25:46.000-06:00
edit pass: create-share-query
diff --git a/articles/governance/resource-graph/tutorials/create-share-query.md b/articles/governance/resource-graph/tutorials/create-share-query.md
@@ -7,162 +7,173 @@ ms.date: 10/23/2019
 ms.topic: tutorial
 ms.service: resource-graph
 ---
-# Tutorial: Create and share an Azure Resource Graph query in Azure portal
+# Tutorial: Create and share an Azure Resource Graph query in the Azure portal
 
-Azure Resource Graph Explorer lets you save your Resource Graph queries right in Azure portal. There
-are two types of queries, _Private_ and _Shared_. A _Private_ query is saved in your Azure portal
-settings, but a _Shared_ query is a Resource Manager resource that can be managed with role-based
-access controls (RBAC) and protected with resource locks.
+Azure Resource Graph Explorer lets you save your Resource Graph queries directly in the Azure
+portal. There are two types of queries: _Private_ and _Shared_. A Private query is saved in your
+Azure portal settings. Whereas a Shared query is a Resource Manager resource that can be managed
+with role-based access controls (RBAC) and protected with resource locks.
 
-Saving queries in Azure portal saves your time spent looking for your favorite or commonly used
-queries. When sharing queries, you enable your team to be consistent and repeatable. In this
-tutorial, you'll complete these steps:
+By saving queries in the Azure portal, you save the time you might otherwise spend looking for your
+favorite or commonly used queries. When you share queries, you help your team realize goals of
+consistency and efficiency through repetition.
+
+In this tutorial, you'll complete the following tasks:
 
 > [!div class="checklist"]
-> - Create and delete a _Private_ query
-> - Create a _Shared_ query
-> - Discover _Shared_ queries
-> - Delete a _Shared_ query
+> - Create and delete a Private query
+> - Create a Shared query
+> - Discover Shared queries
+> - Delete a Shared query
 
 ## Prerequisites
 
-To complete this tutorial, you need an Azure subscription. If you don't have an Azure subscription,
-create a [free account](https://azure.microsoft.com/free/) before you begin.
+To complete this tutorial, you need an Azure subscription. If you don't have one, create a
+[free account](https://azure.microsoft.com/free/) before you begin.
 
 ## Create and delete a Private query
 
-_Private_ queries are only accessible or visible to the account that creates them. As they're saved
-in an account's Azure portal settings, they can only be created, used, and deleted from inside Azure
-portal. A _Private_ query isn't a Resource Manager resource. Create a new _Private_ query by
-following these steps:
+Private queries are accessible and visible only to the account that creates them. As they're saved
+in an account's Azure portal settings, they can be created, used, and deleted only from inside the
+Azure portal. A Private query isn't a Resource Manager resource. To create a new Private query,
+follow these steps:
 
-1. From the portal menu, select 'All services' or use the Azure search box at the top of all pages.
-   Search for and select 'Resource Graph Explorer'.
+1. From the portal menu, select **All services** or use the Azure search box at the top of all
+   pages. Search for and then select **Resource Graph Explorer**.
 
-1. In the 'Query 1' tab on the Azure Resource Graph Explorer page, enter the following query. For
-   information about this query, see
-   [Samples - Count virtual machines by OS type](../samples/starter.md#count-virtual-machines-by-os-type).
-   Select **Run query** to see the query results in th lower pane.
+1. On the **Query 1** tab on the Azure Resource Graph Explorer page, enter the following query:
 
    ```kusto
    Resources
    | where type =~ 'Microsoft.Compute/virtualMachines'
    | summarize count() by tostring(properties.storageProfile.osDisk.osType)
    ```
 
-1. Select **Save** or **Save as**, enter the _Name_ as 'Count VMs by OS', leave _Type_ as 'Private
-   query', then select **Save** at the bottom of the _Save query_ pane. The title of the tab changes
-   from 'Query 1' to 'Count VMs by OS'.
+    Select **Run query** to see the query results in the bottom pane.
+
+   For more information about this query, see
+   [Samples – Count virtual machines by OS type](../samples/starter.md#count-virtual-machines-by-os-type).
+
 
-1. Browse away from Azure Resource Graph Explorer in Azure portal and then return to it. The saved
-   query is no longer displayed and the 'Query 1' tab has returned.
+1. Select **Save** or **Save as**, enter **Count VMs by OS** as the name, leave the type as
+   **Private query**, and then select **Save** at the bottom of the **Save query** pane. The tab
+   title changes from **Query 1** to **Count VMs by OS**.
 
-1. Select **Open a query**. Check that _Type_ is 'Private query'. The saved 'Count VMs by OS' now
-   appears in the _Query Name_ list. Select the title link of the saved query and it's loaded into a
-   new tab with that queries name.
+1. Move away from Azure Resource Graph Explorer in the Azure portal and then return to it. Notice
+   that the saved query is no longer displayed and the **Query 1** tab has returned.
 
-   > [!NOTE]
-   > When a saved query is open and the tab shows it's _Name_, the **Save** button updates it with
-   > any changes made. To create a new saved query, use **Save as** and follow the steps as if it
-   > was a brand new saved query.
+1. Select **Open a query**. Make sure that the type is **Private query**. The saved name **Count VMs
+   by OS** now appears in the **Query Name** list. When you select the title link of the saved
+   query, it's loaded into a new tab with that query's name.
 
-1. To delete the saved query, select **Open a query** again, and check that _Type_ is 'Private
-   query'. On the row of the saved 'Count VMs by OS' query, select the trash can icon. On the
-   confirmation dialog, select **Yes** to complete the deletion of the query. Then close the _Open a
-   query_ pane.
+   > [!NOTE] 
+   >When a saved query is open and the tab shows its name, selecting the **Save** button
+   > updates it with any changes that have been made. To create a new saved query from this open
+   > query, select **Save as** and proceed as if you were saving a brand new query.
+
+1. To delete the saved query, select **Open a query** again, and verify that the **Type** field is
+   set to **Private query**. On the row of the saved `Count VMs by OS` query, select **Delete**
+   (Recycle bin icon). In the confirmation dialog box, select **Yes** to finish deleting the query.
+   Then, close the **Open a query** pane.
 
 ## Create a Shared query
 
-Unlike a _Private_ query, a _Shared_ query is a Resource Manager resource. This fact means the query
-gets saved to a resource group, can be managed and controlled with RBAC, and even protected with
-resource locks. As a resource, anyone with appropriate permissions can see and use it. Create a new
-_Shared_ query by following these steps:
+Unlike a Private query, a Shared query is a Resource Manager resource. This fact means the query
+gets saved to a resource group, can be managed and controlled with RBAC, and can even be protected
+with resource locks. As a resource, anyone who has the appropriate permissions can see and use it.
+To create a new Shared query, follow these steps:
 
-1. From the portal menu, select 'All services' or use the Azure search box at the top of all pages.
-   Search for and select 'Resource Graph Explorer'.
+1. From the portal menu, select **All services**, or use the Azure search box at the top of all
+   pages to search for and select **Resource Graph Explorer**.
 
-1. In the 'Query 1' tab on the Azure Resource Graph Explorer page, enter the following query. For
-   information about this query, see
-   [Samples - Count virtual machines by OS type](../samples/starter.md#count-virtual-machines-by-os-type).
-   Select **Run query** to see the query results in the lower pane.
+1. On the **Query 1** tab on the Azure Resource Graph Explorer page, enter the following query:
 
    ```kusto
    Resources
    | where type =~ 'Microsoft.Compute/virtualMachines'
    | summarize count() by tostring(properties.storageProfile.osDisk.osType)
    ```
+    
+    Select **Run query** to see the query results in the bottom pane.
+
+    For more information about this query, see
+    [Samples – Count virtual machines by OS type](../samples/starter.md#count-virtual-machines-by-os-type).
 
 1. Select **Save** or **Save as**.
 
+   
    ![Save the new query using the save button](../media/create-share-query/save-shared-query-buttons.png)
 
-1. In the _Save query_ pane, enter the _Name_ as 'Count VMs by OS', change _Type_ to 'Shared query',
-   set _Description_ to 'Count of virtual machines by OS type', and select the _Subscription_ where
-   the query resource gets created. Leave the 'Publish to resource-graph-queries resource group'
-   checkbox checked and the _Resource Group location_ set to '(US) West Central US'. Then select
-   **Save** at the bottom of the _Save query_ pane. The title of the tab changes from 'Query 1' to
-   'Count VMs by OS'. The first time 'resource-graph-queries' resource group is used, the save takes
-   longer as the resource group is created.
-
-   ![Save the new query as a Shared Query](../media/create-share-query/save-shared-query-window.png)
-
-   > [!NOTE]
-   > If desired, remove the check to provide the name of an existing resource group to save the
-   > shared query into. Using the default named resource group for queries makes _Shared_ queries
-   > easier to discover. It also makes more apparent the purpose of that resource group. However,
-   > selecting an existing resource group may be done for security reasons based on existing
-   > permissions.
-
-1. Browse away from Azure Resource Graph Explorer in Azure portal and then return to it. The saved
-   query is no longer displayed and the 'Query 1' tab has returned.
-
-1. Select **Open a query**. Check that _Type_ is 'Shared query' and the combination of
-   _Subscription_ and _Resource group_ match where you saved the query. The saved 'Count VMs by OS'
-   now appears in the _Query Name_ list. Select the title link of the saved query and it's loaded
-   into a new tab with that queries name. As a _Shared_ query, it displays an icon in the tab next
-   to the title denoting it as shared.
+1. In the **Save query** pane, enter **Count VMs by OS** for the name.
+1. Change the type to **Shared query**, set the description to **Count of virtual machines by OS
+   type**, and set **Subscription** to specify where the query resource gets created.
+1. Leave the **Publish to resource-graph-queries resource group** check box selected and the
+   **Resource Group location** set to **(US) West Central US**.
+1. Select **Save** at the bottom of the **Save query** pane. The tab title changes from **Query 1**
+   to **Count VMs by OS**. The first time the **resource-graph-queries** resource group is used, the
+   save takes longer than expected as the resource group gets created.
+
+   
+   ![Save the new query as a Shared query](../media/create-share-query/save-shared-query-window.png)
+
+   > [!NOTE] 
+   >You can clear the **Publish to resource-graph-queries resource group** check box if you
+   > want to provide the name of an existing resource group to save the shared query into. Using the
+   > default named resource group for queries makes Shared queries easier to discover. It also makes
+   > the purpose of that resource group more apparent. However, you might opt to select an existing
+   > resource group for security reasons based on existing permissions.
+
+1. Move away from Azure Resource Graph Explorer in the Azure portal and then return to it. Notice
+   that the saved query is no longer displayed and the **Query 1** tab has returned.
+
+1. Select **Open a query**. Verify that the type is set to **Shared query** and the combination of
+   **Subscription** and **Resource group** match where you saved the query. The saved **Count VMs by
+   OS** item now appears in the **Query Name** list. Select the title link of the saved query to
+   load it into a new tab with that query's name. As a Shared query, it displays an icon in the tab
+   next to the title, denoting it as shared.
 
    ![Show the Shared Query with icon](../media/create-share-query/show-saved-shared-query.png)
 
-   > [!NOTE]
-   > When a saved query is open and the tab shows it's _Name_, the **Save** button updates it with
-   > any changes made. To create a new saved query, use **Save as** and follow the steps as if it
-   > was a brand new saved query.
+   > [!NOTE] 
+   >When a saved query is open and the tab shows its name, the **Save** button updates it
+   > with any changes that have been made. To create a new saved query, select **Save as** and
+   > proceed as if you were saving a brand new query.
 
 ## Discover Shared queries
 
-As a _Shared_ query is a Resource Manager resource, there are several ways to find them:
+Because a Shared query is a Resource Manager resource, there are several ways to find one:
 
-- From Resource Graph Explorer, select **Open a query** and set _Type_ to 'Shared query'
-- The Resource Graph queries portal page
-- The resource group it was saved in
-- With a query to Resource Graph
+- From Resource Graph Explorer, select **Open a query** and set the type to **Shared query**.
+- From the Resource Graph queries portal page.
+- From the resource group that the Shared query was saved in.
+- Through a query to Resource Graph.
 
 ### View Resource Graph queries
 
-In Azure portal, the Resource Graph queries page displays _Shared_ queries that the logged in
-account has access to. This page allows filtering by name, subscription, resource group, and other
-properties of the Resource Graph query. Resource Graph queries can also be tagged, exported, and
-deleted using this interface.
+In the Azure portal, the Resource Graph queries page displays Shared queries that the logged-in
+account has access to. This page enables filtering by name, subscription, resource group, and other
+properties of the Resource Graph query. You can also tag, export, and delete Resource Graph queries
+by using this interface.
 
 Selecting one of the queries opens the Resource Graph query page. Like other Resource Manager
 resources, this page offers an interactive overview along with the Activity log, access control, and
-tags. A resource lock can also be applied directly from this page.
+tags. You can also apply a resource lock directly from this page.
 
-Get to the Resource Graph queries page from the portal menu by selecting 'All services' or using the
-Azure search box at the top of all pages. Search for and select 'Resource Graph Explorer'.
+Get to the Resource Graph queries page from the portal menu by selecting **All services** or by
+using the Azure search box at the top of all pages. Search for and select **Resource Graph
+Explorer**.
 
 ### List Resource groups resources
 
 The Resource Graph query is listed alongside other resources that are part of a resource group.
-Selecting the Resource Graph query opens the page for that query. The ellipsis or right-click
-options work the same as the Resource Graph query page.
+Selecting the Resource Graph query opens the page for that query. The ellipsis and shortcut menu
+options (triggered by right-clicking) work the same as on the Resource Graph query page.
 
 ### Query Resource Graph
 
-As a Resource Manager resource, Resource Graph queries can be found with a query to Resource Graph.
-The following Resource Graph query limits by type `Microsoft.ResourceGraph/queries`, and then uses
-`project` to list only the name, time modified, and the query itself:
+You can find Resource Graph queries through a query to Resource Graph. The following Resource Graph
+query limits by type `Microsoft.ResourceGraph/queries`, and then uses `project` to list only the
+name, time modified, and the query itself:
 
 ```kusto
 Resources
@@ -172,27 +183,27 @@ Resources
 
 ## Delete a Shared query
 
-If a _Shared_ query is no longer needed, delete it. Deleting a _Shared_ query removes the actual
-Resource Manager resource. Any dashboards the results chart was pinned to now display an error
-message. When that error message is displayed, use the **Remove from dashboard** button to clean up
-your dashboard.
+If a Shared query is no longer needed, delete it. By deleting a Shared query, you remove the
+corresponding Resource Manager resource. Any dashboards that the results chart was pinned to now
+display an error message. When that error message is displayed, use the **Remove from dashboard**
+button to clean up your dashboard.
 
-A _Shared_ query can be deleted from the following interfaces:
+You can delete a Shared query through the following interfaces:
 - Resource Graph queries page
 - Resource Graph query page
-- Resource Graph Explorer's Open a query page
+- The **Open a query** page in Resource Graph Explorer
 - Resource groups page
 
 ## Clean up resources
 
-When you're finished with this tutorial, delete the _Private_ and _Shared_ queries you created if
-you no longer want them.
+When you're finished with this tutorial, delete the Private and Shared queries you created if you no
+longer want them.
 
 ## Next steps
 
-- Run your first query with [Azure portal](../first-query-portal.md)
-- Get more information about the [query language](../concepts/query-language.md)
-- Learn to [explore resources](../concepts/explore-resources.md)
-- See samples of [Starter queries](../samples/starter.md)
-- See samples of [Advanced queries](../samples/advanced.md)
-- Provide feedback on [UserVoice](https://feedback.azure.com/forums/915958-azure-governance)
+- Run your first query by using the [Azure portal](../first-query-portal.md).
+- Get more information about the [query language](../concepts/query-language.md).
+- Learn more about how to [explore resources](../concepts/explore-resources.md).
+- See samples of [Starter queries](../samples/starter.md).
+- See samples of [Advanced queries](../samples/advanced.md).
+- Provide feedback on [UserVoice](https://feedback.azure.com/forums/915958-azure-governance).
