Merge pull request #280092 from HeidiSteen/heidist-june28

prmerger-automator[bot] · web-flow · commit 89cf63fd9143 · 2024-07-04T16:12:21.000Z
[azure search] misc edits
diff --git a/articles/search/search-get-started-rest.md b/articles/search/search-get-started-rest.md
@@ -160,7 +160,7 @@ Add a second request to your `.rest` file. [Create Index (REST)](/rest/api/searc
     ### Create a new index
     POST {{baseUrl}}/indexes?api-version=2023-11-01  HTTP/1.1
       Content-Type: application/json
-      api-key: {{apiKey}}
+      Authorization: Bearer {{token}}
     
         {
             "name": "hotels-quickstart",  
@@ -237,7 +237,7 @@ The URI is extended to include the `docs` collections and `index` operation.
     ### Upload documents
     POST {{baseUrl}}/indexes/hotels-quickstart/docs/index?api-version=2023-11-01  HTTP/1.1
       Content-Type: application/json
-      api-key: {{apiKey}}
+      Authorization: Bearer {{token}}
     
         {
             "value": [
@@ -336,15 +336,15 @@ The URI is extended to include a query expression, which is specified by using t
     ```http
     ### Run a query
     POST {{baseUrl}}/indexes/hotels-quickstart/docs/search?api-version=2023-11-01  HTTP/1.1
-        Content-Type: application/json
-        api-key: {{apiKey}}
-        
-        {
-            "search": "lake view",
-            "select": "HotelId, HotelName, Tags, Description",
-            "searchFields": "Description, Tags",
-            "count": true
-        }
+      Content-Type: application/json
+      Authorization: Bearer {{token}}
+      
+      {
+          "search": "lake view",
+          "select": "HotelId, HotelName, Tags, Description",
+          "searchFields": "Description, Tags",
+          "count": true
+      }
     ```
 
 1. Review the response in the adjacent pane. You should have a count that indicates the number of matches found in the index, a search score that indicates relevance, and values for each field listed in the `select` statement.
@@ -379,7 +379,7 @@ You can also use [Get Statistics](/rest/api/searchservice/indexes/get-statistics
     ### Get index statistics
     GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2023-11-01  HTTP/1.1
       Content-Type: application/json
-      api-key: {{apiKey}}
+      Authorization: Bearer {{token}}
     ```
 
 1. Review the response. This operation is an easy way to get details about index storage.
diff --git a/articles/search/search-get-started-vector.md b/articles/search/search-get-started-vector.md
@@ -8,7 +8,7 @@ ms.service: cognitive-search
 ms.custom:
   - ignite-2023
 ms.topic: quickstart
-ms.date: 03/14/2024
+ms.date: 07/04/2024
 ---
 
 # Quickstart: Vector search by using REST
@@ -25,11 +25,13 @@ If you don't have an Azure subscription, create a [free account](https://azure.m
 ## Prerequisites
 
 - [Visual Studio Code](https://code.visualstudio.com/download) with a [REST client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client). If you need help with getting started, see [Quickstart: Text search using REST](search-get-started-rest.md).
+
 - [Azure AI Search](search-what-is-azure-search.md), in any region and on any tier. You can use the Free tier for this quickstart, but Basic or higher is recommended for larger data files. [Create](search-create-service-portal.md) or [find an existing Azure AI Search resource](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices) under your current subscription.
 
   Most existing services support vector search. For a small subset of services created prior to January 2019, an index that contains vector fields fails on creation. In this situation, a new service must be created.
 
 - Optionally, to run the query example that invokes [semantic reranking](semantic-search-overview.md), your search service must be the Basic tier or higher, with [semantic ranking enabled](semantic-how-to-enable-disable.md).
+
 - Optionally, an [Azure OpenAI](https://aka.ms/oai/access) resource with a deployment of `text-embedding-ada-002`. The source `.rest` file includes an optional step for generating new text embeddings, but we provide pregenerated embeddings so that you can omit this dependency.
 
 ## Download files
@@ -38,15 +40,76 @@ If you don't have an Azure subscription, create a [free account](https://azure.m
 
 You can also start a new file on your local system and create requests manually by using the instructions in this article.
 
-## Copy a search service key and URL
+## Get a search service endpoint
+
+You can find the search service endpoint in the Azure portal.
+
+1. Sign in to the [Azure portal](https://portal.azure.com) and [find your search service](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices).
+
+1. On the **Overview** home page, find the URL. An example endpoint might look like `https://mydemo.search.windows.net`. 
+
+   :::image type="content" source="media/search-get-started-rest/get-endpoint.png" lightbox="media/search-get-started-rest/get-endpoint.png" alt-text="Screenshot of the URL property on the overview page.":::
+
+You're pasting this endpoint into the `.rest` or `.http` file in a later step.
+
+## Configure access
+
+Requests to the search endpoint must be authenticated and authorized. You can use API keys or roles for this task. Keys are easier to start with, but roles are more secure.
+
+For a role-based connection, the following instructions have you connecting to Azure AI Search under your identity, not the identity of a client app.
+
+### Option 1: Use keys
+
+Select **Settings** > **Keys** and then copy an admin key. Admin keys are used to add, modify, and delete objects. There are two interchangeable admin keys. Copy either one. For more information, see [Connect to Azure AI Search using key authentication](search-security-api-keys.md).
+
+:::image type="content" source="media/search-get-started-rest/get-api-key.png" lightbox="media/search-get-started-rest/get-api-key.png" alt-text="Screenshot that shows the API keys in the Azure portal.":::
+
+You're pasting this key into the `.rest` or `.http` file in a later step.
+
+### Option 2: Use roles
+
+Make sure your search service is [configured for role-based access](search-security-enable-roles.md). You must have preconfigured [role-assignments for developer access](search-security-rbac.md#assign-roles-for-development). Your role assignments must grant permission to create, load, and query a search index. 
+
+In this section, obtain your personal identity token using either the Azure CLI, Azure PowerShell, or the Azure portal. 
 
-REST calls require the search service endpoint and an API key on every request. You can get these values from the Azure portal.
+#### [Azure CLI](#tab/azure-cli)
 
-1. Sign in to the [Azure portal](https://portal.azure.com). Go to the **Overview** page and copy the URL. An example endpoint might look like `https://mydemo.search.windows.net`.
+1. Sign in to Azure CLI.
 
-1. Select **Settings** > **Keys** and copy an admin key. Admin keys are used to add, modify, and delete objects. There are two interchangeable admin keys. Copy either one.
+    ```azurecli
+    az login
+    ```
+
+1. Get your personal identity token.
+
+    ```azurecli
+    az account get-access-token --scope https://search.azure.com/.default
+    ```
+
+#### [Azure PowerShell](#tab/azure-powershell)
+
+1. Sign in with PowerShell.
+
+    ```azurepowershell
+    Connect-AzAccount
+    ```
+
+1. Get your personal identity token.
 
-   :::image type="content" source="media/search-get-started-rest/get-url-key.png" alt-text="Screenshot that shows the URL and API keys in the Azure portal.":::
+    ```azurepowershell
+    Get-AzAccessToken -ResourceUrl https://search.azure.com
+    ```
+
+#### [Azure portal](#tab/portal)
+
+Use the steps found here: [find the user object ID](/partner-center/find-ids-and-domain-names#find-the-user-object-id) in the Azure portal.
+
+---
+
+You're pasting your personal identity token into the `.rest` or `.http` file in a later step.
+
+> [!NOTE]
+> This section assumes you're using a local client that connects to Azure AI Search on your behalf. An alternative approach is [getting a token for the client app](/entra/identity-platform/v2-oauth2-client-creds-grant-flow), assuming your application is [registered](/entra/identity-platform/quickstart-register-app) with Microsoft Entra ID.
 
 ## Create a vector index
 
@@ -56,22 +119,22 @@ The index schema is organized around hotel content. Sample data consists of vect
 
 1. Open a new text file in Visual Studio Code.
 
-1. Set variables to the search endpoint and the API key that you collected earlier.
+1. Set variables to the values you collected earlier. This example uses a personal identity token.
 
    ```http
    @baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
-   @apiKey = PUT-YOUR-ADMIN-API-KEY-HERE
+   @token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE
    ```
 
-1. Save the file with a `.rest` file extension.
+1. Save the file with a `.rest` or `.http` file extension.
 
 1. Paste in the following example to create the `hotels-vector-quickstart` index on your search service.
 
     ```http
     ### Create a new index
     POST {{baseUrl}}/indexes?api-version=2023-11-01  HTTP/1.1
         Content-Type: application/json
-        api-key: {{apiKey}}
+        Authorization: Bearer {{token}}
     
     {
         "name": "hotels-vector-quickstart",
@@ -243,7 +306,7 @@ The URI is extended to include the `docs` collection and the `index` operation.
 ### Upload documents
 POST {{baseUrl}}/indexes/hotels-quickstart-vectors/docs/index?api-version=2023-11-01  HTTP/1.1
 Content-Type: application/json
-api-key: {{apiKey}}
+Authorization: Bearer {{token}}
 
 {
     "value": [
@@ -405,7 +468,7 @@ The vector query string is semantically similar to the search string, but it inc
     ### Run a query
     POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version=2023-11-01  HTTP/1.1
         Content-Type: application/json
-        api-key: {{apiKey}}
+        Authorization: Bearer {{token}}
         
         {
             "count": true,
@@ -484,7 +547,7 @@ You can add filters, but the filters are applied to the nonvector content in you
     ### Run a vector query with a filter
     POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version=2023-11-01  HTTP/1.1
         Content-Type: application/json
-        api-key: {{apiKey}}
+        Authorization: Bearer {{token}}
     
         {
             "count": true,
@@ -557,7 +620,7 @@ Hybrid search consists of keyword queries and vector queries in a single search
     ### Run a hybrid query
     POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version=2023-11-01  HTTP/1.1
         Content-Type: application/json
-        api-key: {{apiKey}}
+        Authorization: Bearer {{token}}
         
     {
         "count": true,
@@ -704,7 +767,7 @@ Here's the last query in the collection. This hybrid query with semantic ranking
     ### Run a hybrid query
     POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version=2023-11-01  HTTP/1.1
         Content-Type: application/json
-        api-key: {{apiKey}}
+        Authorization: Bearer {{token}}
 
     {
         "count": true,
@@ -809,7 +872,7 @@ You can also try this `DELETE` command:
 ### Delete an index
 DELETE  {{baseUrl}}/indexes/hotels-vector-quickstart?api-version=2023-11-01 HTTP/1.1
     Content-Type: application/json
-    api-key: {{apiKey}}
+    Authorization: Bearer {{token}}
 ```
 
 ## Next steps
diff --git a/articles/search/search-howto-reindex.md b/articles/search/search-howto-reindex.md
@@ -49,7 +49,7 @@ Queries continue to run, but if you're updating or removing existing fields, you
 
 + To update the contents of simple fields and subfields in complex types, list only the fields you want to change. For example, if you only need to update a description field, the payload should consist of the document key and the modified description. Omitting other fields retains their existing values.
 
-+ To merge the inline changes into string collection, provide the entire value. Recall the `tags` field example from the previous section. New values overwrite the old values, and there's no merging at the field content level.
++ To merge inline changes into string collection, provide the entire value. Recall the `tags` field example from the previous section. New values overwrite the old values for an entire field, and there's no merging within the content of a field.
 
 Here's a [REST API example](search-get-started-rest.md) demonstrating these tips:
 
@@ -59,7 +59,7 @@ GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2023-11-
     Content-Type: application/json
     api-key: {{apiKey}}
 
-### Change the description and city for Secret Point Hotel
+### Change the description, city, and tags for Secret Point Hotel
 POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search.index?api-version=2023-11-01  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}
@@ -69,9 +69,10 @@ POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search.index?api-version=
             {
             "@search.action": "mergeOrUpload",
             "HotelId": "1",
-            "Description": "Change the description and city for Secret Point Hotel. Keep everything else."
+            "Description": "I'm overwriting the description for Secret Point Hotel.",
+            "Tags": ["my old item", "my new item"],
             "Address": {
-                "City": "Miami"
+                "City": "Gotham City"
                 }
             }
         ]
@@ -104,15 +105,15 @@ The order of operations is:
 
 1. [Update index schema](/rest/api/searchservice/indexes/create-or-update) on the search service.
 
-1. [Update index content](#update-content) to match your revised schema if you added a new field. For all other changes, the existing content is used as-is.
+1. [Update index content](#update-content) to match your revised schema if you added a new field. For all other changes, the existing indexed content is used as-is.
 
-When you update the index schema, existing documents in the index are given a null value for the new field. On the next index documents job, values from external source data replace the nulls added by Azure AI Search.
+When you update an index schema to include a new field, existing documents in the index are given a null value for that field. On the next indexing job, values from external source data replace the nulls added by Azure AI Search.
 
-There should be no query disruptions during the updates, but query results will change as the updates take effect.
+There should be no query disruptions during the updates, but query results will vary as the updates take effect.
 
 ## Drop and rebuild an index
 
-Some modifications require an index drop and rebuild.
+Some modifications require an index drop and rebuild, replacing a current index with a new one.
 
 | Action | Description |
 |-----------|-------------|
@@ -125,10 +126,12 @@ Some modifications require an index drop and rebuild.
 
 The order of operations is:
 
-1. [Get an index definition](/rest/api/searchservice/indexes/get) in case you need it for future reference.
+1. [Get an index definition](/rest/api/searchservice/indexes/get) in case you need it for future reference, or to use as the basis for a new version.
 
 1. Consider using a backup and restore solution to preserve a copy of index content. There are solutions in [C#](https://github.com/liamca/azure-search-backup-restore/blob/master/README.md) and in [Python](https://github.com/Azure/azure-search-vector-samples/tree/main/demo-python/code/index-backup-restore). We recommend the Python version because it's more up to date.
 
+   If you have capacity on your search service, keep the existing index while creating and testing the new one.
+
 1. [Drop the existing index](/rest/api/searchservice/indexes/delete). Queries targeting the index are immediately dropped. Remember that deleting an index is irreversible, destroying physical storage for the fields collection and other constructs. 
 
 1. [Post a revised index](/rest/api/searchservice/indexes/create), where the body of the request includes changed or modified field definitions and configurations.
@@ -137,8 +140,6 @@ The order of operations is:
 
 When you create the index, physical storage is allocated for each field in the index schema, with an inverted index created for each searchable field and a vector index created for each vector field. Fields that aren't searchable can be used in filters or expressions, but don't have inverted indexes and aren't full-text or fuzzy searchable. On an index rebuild, these inverted indexes and vector indexes are deleted and recreated based on the index schema you provide.
 
-If your index is in production or under active development, consider pushing, loading, and testing the new index before dropping the old one.
-
 ## Balancing workloads
 
 Indexing doesn't run in the background, but the search service will balance any indexing jobs against ongoing queries. During indexing, you can [monitor query requests](search-monitor-queries.md) in the portal to ensure queries are completing in a timely manner.
