Skip to content

Commit 0827847

Browse files
ShawnJacksonShawnJackson
authored
Merge pull request #269866 from paulth1/search-get-started-articles
[AQ] edit pass: search-get-started-articles
2 parents 3a18735 + c99fd7c commit 0827847

File tree

3 files changed

+139
-149
lines changed

3 files changed

+139
-149
lines changed

‎articles/search/search-get-started-powershell.md

Lines changed: 39 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
title: 'Quickstart: Create a search index in PowerShell using REST APIs'
2+
title: 'Quickstart: Create a search index in PowerShell by using REST APIs'
33
titleSuffix: Azure AI Search
4-
description: In this REST API quickstart, learn how to create an index, load data, and run queries using PowerShell's Invoke-RestMethod and the Azure AI Search REST API.
4+
description: In this REST API quickstart, learn how to create an index, load data, and run queries by using PowerShell's Invoke-RestMethod and the Azure AI Search REST API.
55
manager: nitinme
66
author: HeidiSteen
77
ms.author: heidist
@@ -13,35 +13,34 @@ ms.custom:
1313
- mode-api
1414
- ignite-2023
1515
---
16-
# Quickstart: Create a search index in PowerShell using REST APIs
16+
# Quickstart: Create a search index in PowerShell by using REST APIs
1717

18-
In this Azure AI Search quickstart, learn how to create, load, and query a search index using PowerShell and the [Azure AI Search REST APIs](/rest/api/searchservice/). This article explains how to run PowerShell commands interactively. Alternatively, you can [download and run a PowerShell script](https://github.com/Azure-Samples/azure-search-powershell-samples/tree/main/Quickstart) that performs the same operations.
18+
In this Azure AI Search quickstart, learn how to create, load, and query a search index by using PowerShell and the [Azure AI Search REST APIs](/rest/api/searchservice/). This article explains how to run PowerShell commands interactively. Alternatively, you can [download and run a PowerShell script](https://github.com/Azure-Samples/azure-search-powershell-samples/tree/main/Quickstart) that performs the same operations.
1919

2020
If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
2121

2222
## Prerequisites
2323

24-
The following services and tools are required for this quickstart.
24+
The following services and tools are required for this quickstart:
2525

26-
+ [PowerShell 7.3 or later](https://github.com/PowerShell/PowerShell), using [Invoke-RestMethod](/powershell/module/Microsoft.PowerShell.Utility/Invoke-RestMethod) for sequential and interactive steps.
27-
28-
+ [Create an Azure AI Search service](search-create-service-portal.md) or [find an existing service](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices) under your current subscription. You can use a free service for this quickstart.
26+
- [PowerShell 7.3 or later](https://github.com/PowerShell/PowerShell), using [Invoke-RestMethod](/powershell/module/Microsoft.PowerShell.Utility/Invoke-RestMethod) for sequential and interactive steps.
27+
- [Create an Azure AI Search service](search-create-service-portal.md) or [find an existing service](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices) under your current subscription. You can use a free service for this quickstart.
2928

3029
## Copy a search service key and URL
3130

32-
In this quickstart, REST calls include the service URL and an access key on every request. A search service is created with both, so if you added Azure AI Search to your subscription, follow these steps to get the necessary information:
31+
In this quickstart, REST calls include the service URL and an access key on every request. A search service is created with both, so if you added Azure AI Search to your subscription, follow these steps to get the necessary information.
3332

34-
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`.
33+
1. Sign in to the [Azure portal](https://portal.azure.com). On your search service **Overview** page, get the URL. An example endpoint might look like `https://mydemo.search.windows.net`.
3534

36-
2. 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.
35+
1. Select **Settings** > **Keys** and then get an admin key for full rights on the service. Two interchangeable admin keys are provided for business continuity if you need to roll one over. You can use either the primary or secondary key on requests for adding, modifying, and deleting objects.
3736

38-
![Get an HTTP endpoint and access key](media/search-get-started-rest/get-url-key.png "Get an HTTP endpoint and access key")
37+
![Screenshot that shows getting an HTTP endpoint and access key.](media/search-get-started-rest/get-url-key.png "Get an HTTP endpoint and access key")
3938

40-
All requests require an api-key on every request sent to your service. Having a valid key establishes trust, on a per request basis, between the application sending the request and the service that handles it.
39+
All requests require an API key on every request sent to your service. Having a valid key establishes trust, on a per-request basis, between the application sending the request and the service that handles it.
4140

4241
## Connect to Azure AI Search
4342

44-
1. In PowerShell, create a **$headers** object to store the content-type and API key. Replace the admin API key (YOUR-ADMIN-API-KEY) with a key that is valid for your search service. You only have to set this header once for the duration of the session, but you'll add it to every request.
43+
1. In PowerShell, create a `$headers` object to store the content type and API key. Replace the admin API key (`YOUR-ADMIN-API-KEY`) with a key that's valid for your search service. You only have to set this header once for the duration of the session, but you add it to every request.
4544

4645
```powershell
4746
$headers = @{
@@ -50,13 +49,13 @@ All requests require an api-key on every request sent to your service. Having a
5049
'Accept' = 'application/json' }
5150
```
5251
53-
2. Create a **$url** object that specifies the service's indexes collection. Replace the service name (YOUR-SEARCH-SERVICE-NAME) with a valid search service.
52+
1. Create a `$url` object that specifies the service's indexes collection. Replace the service name (`YOUR-SEARCH-SERVICE-NAME`) with a valid search service.
5453
5554
```powershell
5655
$url = "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes?api-version=2023-11-01&`$select=name"
5756
```
5857
59-
3. Run **Invoke-RestMethod** to send a GET request to the service and verify the connection. Add **ConvertTo-Json** so that you can view the responses sent back from the service.
58+
1. Run `Invoke-RestMethod` to send a GET request to the service and verify the connection. Add `ConvertTo-Json` so that you can view the responses sent back from the service.
6059
6160
```powershell
6261
Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json
@@ -73,15 +72,15 @@ All requests require an api-key on every request sent to your service. Having a
7372
}
7473
```
7574
76-
## 1 - Create an index
75+
## Create an index
7776
7877
Unless you're using the portal, an index must exist on the service before you can load data. This step defines the index and pushes it to the service. The [Create Index REST API](/rest/api/searchservice/create-index) is used for this step.
7978
8079
Required elements of an index include a name and a fields collection. The fields collection defines the structure of a *document*. Each field has a name, type, and attributes that determine how it's used (for example, whether it's full-text searchable, filterable, or retrievable in search results). Within an index, one of the fields of type `Edm.String` must be designated as the *key* for document identity.
8180
82-
This index is named "hotels-quickstart" and has the field definitions you see below. It's a subset of a larger [Hotels index](https://github.com/Azure-Samples/azure-search-sample-data/blob/main/hotels/Hotels_IndexDefinition.JSON) used in other walk-through articles. The field definitions have been trimmed in this quickstart for brevity.
81+
This index is named `hotels-quickstart` and has the field definitions you see in the following code. It's a subset of a larger [Hotels index](https://github.com/Azure-Samples/azure-search-sample-data/blob/main/hotels/Hotels_IndexDefinition.JSON) used in other walkthrough articles. The field definitions are trimmed in this quickstart for brevity.
8382
84-
1. Paste this example into PowerShell to create a **$body** object containing the index schema.
83+
1. Paste this example into PowerShell to create a `$body` object that contains the index schema.
8584
8685
```powershell
8786
$body = @"
@@ -110,19 +109,19 @@ This index is named "hotels-quickstart" and has the field definitions you see be
110109
"@
111110
```
112111
113-
2. Set the URI to the indexes collection on your service and the *hotels-quickstart* index.
112+
1. Set the URI to the indexes collection on your service and the `hotels-quickstart` index.
114113
115114
```powershell
116115
$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart?api-version=2023-11-01"
117116
```
118117
119-
3. Run the command with **$url**, **$headers**, and **$body** to create the index on the service.
118+
1. Run the command with `$url`, `$headers`, and `$body` to create the index on the service.
120119
121120
```powershell
122121
Invoke-RestMethod -Uri $url -Headers $headers -Method Put -Body $body | ConvertTo-Json
123122
```
124123
125-
Results should look similar to this (truncated to the first two fields for brevity):
124+
Results should look similar to this example, which shows only the first two fields for brevity:
126125
127126
```
128127
{
@@ -165,17 +164,17 @@ This index is named "hotels-quickstart" and has the field definitions you see be
165164
```
166165
167166
> [!Tip]
168-
> For verification, you could also check the Indexes list in the portal.
167+
> For verification, you could also check the **Indexes** list in the portal.
169168
170169
<a name="load-documents"></a>
171170
172-
## 2 - Load documents
171+
## Load documents
173172
174173
To push documents, use an HTTP POST request to your index's URL endpoint. The REST API for this task is [Add, Update, or Delete Documents](/rest/api/searchservice/addupdate-or-delete-documents).
175174
176-
1. Paste this example into PowerShell to create a **$body** object containing the documents you want to upload.
175+
1. Paste this example into PowerShell to create a `$body` object that contains the documents you want to upload.
177176
178-
This request includes two full and one partial record. The partial record demonstrates that you can upload incomplete documents. The `@search.action` parameter specifies how indexing is done. Valid values include upload, merge, mergeOrUpload, and delete. The mergeOrUpload behavior either creates a new document for hotelId = 3, or updates the contents if it already exists.
177+
This request includes two full records and one partial record. The partial record demonstrates that you can upload incomplete documents. The `@search.action` parameter specifies how indexing is done. Valid values include `upload`, `merge`, `mergeOrUpload`, and `delete`. The `mergeOrUpload` behavior either creates a new document for `hotelId = 3` or updates the contents if it already exists.
179178
180179
```powershell
181180
$body = @"
@@ -262,13 +261,13 @@ To push documents, use an HTTP POST request to your index's URL endpoint. The RE
262261
"@
263262
```
264263
265-
1. Set the endpoint to the *hotels-quickstart* docs collection and include the index operation (indexes/hotels-quickstart/docs/index).
264+
1. Set the endpoint to the `hotels-quickstart` docs collection and include the index operation (`indexes/hotels-quickstart/docs/index`).
266265
267266
```powershell
268267
$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2023-11-01"
269268
```
270269
271-
1. Run the command with **$url**, **$headers**, and **$body** to load documents into the hotels-quickstart index.
270+
1. Run the command with `$url`, `$headers`, and `$body` to load documents into the `hotels-quickstart` index.
272271
273272
```powershell
274273
Invoke-RestMethod -Uri $url -Headers $headers -Method Post -Body $body | ConvertTo-Json
@@ -307,27 +306,27 @@ To push documents, use an HTTP POST request to your index's URL endpoint. The RE
307306
}
308307
```
309308
310-
## 3 - Search an index
309+
## Search an index
311310
312-
This step shows you how to query an index using the [Search Documents API](/rest/api/searchservice/search-documents).
311+
This step shows you how to query an index by using the [Search Documents API](/rest/api/searchservice/search-documents).
313312
314-
Be sure to use single quotes on search $urls. Query strings include **$** characters, and you can omit having to escape them if the entire string is enclosed in single quotes.
313+
Be sure to use single quotation marks on search `$urls`. Query strings include `$` characters, and you can omit having to escape them if the entire string is enclosed in single quotation marks.
315314
316-
1. Set the endpoint to the *hotels-quickstart* docs collection and add a **search** parameter to pass in a query string.
315+
1. Set the endpoint to the `hotels-quickstart` docs collection and add a `search` parameter to pass in a query string.
317316
318-
This string executes an empty search (search=*), returning an unranked list (search score = 1.0) of arbitrary documents. By default, Azure AI Search returns 50 matches at a time. As structured, this query returns an entire document structure and values. Add **$count=true** to get a count of all documents in the results.
317+
This string executes an empty search (`search=*`), returning an unranked list (search score = 1.0) of arbitrary documents. By default, Azure AI Search returns 50 matches at a time. As structured, this query returns an entire document structure and values. Add `$count=true` to get a count of all documents in the results.
319318
320319
```powershell
321320
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=*&$count=true'
322321
```
323322
324-
1. Run the command to send the **$url** to the service.
323+
1. Run the command to send the `$url` to the service.
325324
326325
```powershell
327326
Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json
328327
```
329328
330-
Results should look similar to the following output.
329+
Results should look similar to the following output:
331330
332331
```
333332
{
@@ -363,7 +362,7 @@ Be sure to use single quotes on search $urls. Query strings include **$** charac
363362
}
364363
```
365364
366-
Try a few other query examples to get a feel for the syntax. You can do a string search, verbatim $filter queries, limit the results set, scope the search to specific fields, and more.
365+
Try a few other query examples to get a feel for the syntax. You can do a string search, verbatim `$filter` queries, limit the results set, scope the search to specific fields, and more.
367366
368367
```powershell
369368
# Query example 1
@@ -390,13 +389,13 @@ $url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quicksta
390389

391390
When you're working in your own subscription, it's a good idea at the end of a project to identify whether you still need the resources you created. Resources left running can cost you money. You can delete resources individually or delete the resource group to delete the entire set of resources.
392391

393-
You can find and manage resources in the portal, using the **All resources** or **Resource groups** link in the left-navigation pane.
392+
You can find and manage resources in the portal by using the **All resources** or **Resource groups** link in the leftmost pane.
394393

395-
If you're using a free service, remember that you're limited to three indexes, indexers, and data sources. You can delete individual items in the portal to stay under the limit.
394+
If you're using a free service, remember that you're limited to three indexes, indexers, and data sources. You can delete individual items in the portal to stay under the limit.
396395

397396
## Next steps
398397

399-
In this quickstart, you used PowerShell to step through the basic workflow for creating and accessing content in Azure AI Search. With the concepts in mind, we recommend moving on to more advanced scenarios, such as indexing from Azure data sources;
398+
In this quickstart, you used PowerShell to step through the basic workflow for creating and accessing content in Azure AI Search. With the concepts in mind, we recommend that you move on to more advanced scenarios, such as indexing from Azure data sources:
400399

401400
> [!div class="nextstepaction"]
402-
> [REST Tutorial: Index and search semi-structured data (JSON blobs) in Azure AI Search](search-semi-structured-data.md)
401+
> [REST tutorial: Index and search semi-structured data (JSON blobs) in Azure AI Search](search-semi-structured-data.md)

0 commit comments

Comments
 (0)