Merge pull request #106024 from HeidiSteen/heidist-master

Jak-MS · web-flow · commit 07c8982736a4 · 2020-02-28T14:36:41.000-06:00
Standardized steps for Azure SQL DB tutorial
diff --git a/articles/search/search-indexer-tutorial.md b/articles/search/search-indexer-tutorial.md
@@ -12,15 +12,15 @@ ms.date: 02/28/2020
 #Customer intent: As a developer, I want an introduction the indexing Azure SQL data for Azure Cognitive Search.
 ---
 
-# Tutorial: Index data from Azure SQL databases in C#
+# Tutorial: Use C# to index data from SQL databases in Azure Cognitive Search
 
-Configure an [indexer](search-indexer-overview.md) programmatically to extract searchable data from Azure SQL database and sends it to a search index in Azure Cognitive Search. 
+Configure an [indexer](search-indexer-overview.md) to extract searchable data from Azure SQL database, sending it to a search index in Azure Cognitive Search. 
 
 This tutorial uses C# and the [.NET SDK](https://aka.ms/search-sdk) to perform the following tasks:
 
 > [!div class="checklist"]
 > * Create a data source that connects to Azure SQL Database
-> * Configure an indexer
+> * Create an indexer
 > * Run an indexer to load data into an index
 > * Query an index as a verification step
 
@@ -39,35 +39,13 @@ If you don't have an Azure subscription, create a [free account](https://azure.m
 
 Source code for this tutorial is in the [DotNetHowToIndexer](https://github.com/Azure-Samples/search-dotnet-getting-started/tree/master/DotNetHowToIndexers) folder in the [Azure-Samples/search-dotnet-getting-started](https://github.com/Azure-Samples/search-dotnet-getting-started) GitHub repository.
 
-## Get a key and URL
+## 1 - Create services
 
-API calls require the service URL and an access key. A search service is created with both, so if you added Azure Cognitive Search to your subscription, follow these steps to get the necessary information:
-
-1. [Sign in to the Azure portal](https://portal.azure.com/), and in your search service **Overview** page, get the URL. An example endpoint might look like `https://mydemo.search.windows.net`.
-
-1. In **Settings** > **Keys**, get an admin key for full rights on the service. There are two interchangeable admin keys, provided for business continuity in case you need to roll one over. You can use either the primary or secondary key on requests for adding, modifying, and deleting objects.
-
-   ![Get an HTTP endpoint and access key](media/search-get-started-postman/get-url-key.png "Get an HTTP endpoint and access key")
-
-## Set up connections
+This tutorial uses Azure Cognitive Search for indexing and queries, and Azure SQL Database as an external data source. If possible, create both services in the same region and resource group for proximity and manageability. In practice, Azure SQL Database can be in any region.
 
-1. Start Visual Studio and open **DotNetHowToIndexers.sln**.
+### Start with Azure SQL Database
 
-1. In Solution Explorer, open **appsettings.json** and replace placeholder values with connection information to your search service. If the full URL is "https://my-demo-service.search.windows.net", the service name to provide is "my-demo-service".
-
-    ```json
-    {
-      "SearchServiceName": "Put your search service name here",
-      "SearchServiceAdminApiKey": "Put your primary or secondary API key here",
-      "AzureSqlConnectionString": "Put your Azure SQL database connection string here",
-    }
-    ```
-
-The last entry requires an existing database. You'll create it in the next step.
-
-## Prepare sample data
-
-In this step, create an external data source on Azure SQL Database that an indexer can crawl. You can use the Azure portal and the *hotels.sql* file from the sample to create the dataset in Azure SQL Database. Azure Cognitive Search consumes flattened rowsets, such as one generated from a view or query. The SQL file in the sample solution creates and populates a single table.
+In this step, create an external data source on Azure SQL Database that an indexer can crawl. You can use the Azure portal and the *hotels.sql* file from the sample download to create the dataset in Azure SQL Database. Azure Cognitive Search consumes flattened rowsets, such as one generated from a view or query. The SQL file in the sample solution creates and populates a single table.
 
 If you have an existing Azure SQL Database resource, you can add the hotels table to it, starting at step 4.
 
@@ -103,59 +81,45 @@ If you have an existing Azure SQL Database resource, you can add the hotels tabl
     Server=tcp:{your_dbname}.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID={your_username};Password={your_password};MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;
     ```
 
-1. Paste the connection string into "AzureSqlConnectionString" as the third entry in **appsettings.json** file in Visual Studio.
-
-    ```json
-    {
-      "SearchServiceName": "<placeholder-Azure-Search-service-name>",
-      "SearchServiceAdminApiKey": "<placeholder-admin-key-for-Azure-Search>",
-      "AzureSqlConnectionString": "Server=tcp:{your_dbname}.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID={your_username};Password={your_password};MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;",
-    }
-    ```
-
-1. Enter your password into the connection string in the **appsettings.json** file. Database and user names will copy over in your connection string, but the password must be entered manually.
-
-## Build the solution
-
-Press F5 to build the solution. The program executes in debug mode. A console window reports the status of each operation.
-
-   ![Console output](./media/search-indexer-tutorial/console-output.png "Console output")
-
-Your code runs locally in Visual Studio, connecting to your search service on Azure, which in turn connects to Azure SQL Database and retrieves the dataset. With this many operations, there are several potential points of failure. If you get an error, check the following conditions first:
+You will need this connection string in the next exercise, setting up your environment.
 
-+ Search service connection information that you provide is limited to the service name in this tutorial. If you entered the full URL, operations stop at index creation, with a failure to connect error.
+### Azure Cognitive Search
 
-+ Database connection information in **appsettings.json**. It should be the ADO.NET connection string obtained from the portal, modified to include a username and password that are valid for your database. The user account must have permission to retrieve data. Your local client IP address must be allowed access.
+The next component is Azure Cognitive Search, which you can [create in the portal](search-create-service-portal.md). You can use the Free tier to complete this walkthrough. 
 
-+ Resource limits. Recall that the Free tier has limits of 3 indexes, indexers, and data sources. A service at the maximum limit cannot create new objects.
+### Get an admin api-key and URL for Azure Cognitive Search
 
-## Check results
+API calls require the service URL and an access key. A search service is created with both, so if you added Azure Cognitive Search to your subscription, follow these steps to get the necessary information:
 
-Use Azure portal to verify object creation, and then use **Search explorer** to query the index.
+1. [Sign in to the Azure portal](https://portal.azure.com/), and in your search service **Overview** page, get the URL. An example endpoint might look like `https://mydemo.search.windows.net`.
 
-1. [Sign in to the Azure portal](https://portal.azure.com/), and in your search service **Overview** page, open each list in turn to verify the object is created. **Indexes**, **Indexers**, and **Data Sources** will have "hotels", "azure-sql-indexer", and "azure-sql", respectively.
+1. In **Settings** > **Keys**, get an admin key for full rights on the service. There are two interchangeable admin keys, provided for business continuity in case you need to roll one over. You can use either the primary or secondary key on requests for adding, modifying, and deleting objects.
 
-   ![Indexer and data source tiles](./media/search-indexer-tutorial/tiles-portal.png)
+   ![Get an HTTP endpoint and access key](media/search-get-started-postman/get-url-key.png "Get an HTTP endpoint and access key")
 
-1. Select the hotels index. On the hotels page, **Search explorer** is the first tab. 
+## 2 - Set up your environment
 
-1. Click **Search** to issue an empty query. 
+1. Start Visual Studio and open **DotNetHowToIndexers.sln**.
 
-   The three entries in your index are returned as JSON documents. Search explorer returns documents in JSON so that you can view the entire structure.
+1. In Solution Explorer, open **appsettings.json** to provide connection information.
 
-   ![Query an index](./media/search-indexer-tutorial/portal-search.png "Query an index")
-   
-1. Next, enter a search string: `search=river&$count=true`. 
+1. For `searchServiceName`, if the full URL is "https://my-demo-service.search.windows.net", the service name to provide is "my-demo-service".
 
-   This query invokes full text search on the term `river`, and the result includes a count of the matching documents. Returning the count of matching documents is helpful in testing scenarios when you have a large index with thousands or millions of documents. In this case, only one document matches the query.
+1. For `AzureSqlConnectionString`, the string format is similar to this: `"Server=tcp:{your_dbname}.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID={your_username};Password={your_password};MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"`
 
-1. Lastly, enter a search string that limits the JSON output to fields of interest: `search=river&$count=true&$select=hotelId, baseRate, description`. 
+    ```json
+    {
+      "SearchServiceName": "<placeholder-Azure-Search-service-name>",
+      "SearchServiceAdminApiKey": "<placeholder-admin-key-for-Azure-Search>",
+      "AzureSqlConnectionString": "<placeholder-ADO.NET-connection-string",
+    }
+    ```
 
-   The query response is reduced to selected fields, resulting in more concise output.
+1. In the connection string, make sure the connection string contains a valid password. While the database and user names will copy over, the password must be entered manually.
 
-## Explore the code
+## 3 - Create the pipeline
 
-Now that you understand what the sample code creates, let's return to the solution to review the code. Relevant code is in two files:
+Indexers require a data source object and an index. Relevant code is in two files:
 
   + **hotel.cs**, containing a schema that defines the index
   + **Program.cs**, containing functions for creating and managing structures in your service
@@ -229,6 +193,44 @@ An indexer object is platform-agnostic, where  configuration, scheduling, and in
   }
   ```
 
+## 4 - Build the solution
+
+Press F5 to build and run the solution. The program executes in debug mode. A console window reports the status of each operation.
+
+   ![Console output](./media/search-indexer-tutorial/console-output.png "Console output")
+
+Your code runs locally in Visual Studio, connecting to your search service on Azure, which in turn connects to Azure SQL Database and retrieves the dataset. With this many operations, there are several potential points of failure. If you get an error, check the following conditions first:
+
++ Search service connection information that you provide is limited to the service name in this tutorial. If you entered the full URL, operations stop at index creation, with a failure to connect error.
+
++ Database connection information in **appsettings.json**. It should be the ADO.NET connection string obtained from the portal, modified to include a username and password that are valid for your database. The user account must have permission to retrieve data. Your local client IP address must be allowed access.
+
++ Resource limits. Recall that the Free tier has limits of 3 indexes, indexers, and data sources. A service at the maximum limit cannot create new objects.
+
+## 5 - Search
+
+Use Azure portal to verify object creation, and then use **Search explorer** to query the index.
+
+1. [Sign in to the Azure portal](https://portal.azure.com/), and in your search service **Overview** page, open each list in turn to verify the object is created. **Indexes**, **Indexers**, and **Data Sources** will have "hotels", "azure-sql-indexer", and "azure-sql", respectively.
+
+   ![Indexer and data source tiles](./media/search-indexer-tutorial/tiles-portal.png)
+
+1. Select the hotels index. On the hotels page, **Search explorer** is the first tab. 
+
+1. Click **Search** to issue an empty query. 
+
+   The three entries in your index are returned as JSON documents. Search explorer returns documents in JSON so that you can view the entire structure.
+
+   ![Query an index](./media/search-indexer-tutorial/portal-search.png "Query an index")
+   
+1. Next, enter a search string: `search=river&$count=true`. 
+
+   This query invokes full text search on the term `river`, and the result includes a count of the matching documents. Returning the count of matching documents is helpful in testing scenarios when you have a large index with thousands or millions of documents. In this case, only one document matches the query.
+
+1. Lastly, enter a search string that limits the JSON output to fields of interest: `search=river&$count=true&$select=hotelId, baseRate, description`. 
+
+   The query response is reduced to selected fields, resulting in more concise output.
+
 ## Reset and rerun
 
 In the early experimental stages of development, the most practical approach for design iteration is to delete the objects from Azure Cognitive Search and allow your code to rebuild them. Resource names are unique. Deleting an object lets you recreate it using the same name.
