快速入门:在 PowerShell 中使用 REST API 创建 Azure 认知搜索索引Quickstart: Create an Azure Cognitive Search index in PowerShell using REST APIs

本文引导你完成使用 PowerShell 和 Azure 认知搜索 REST API 创建、加载和查询 Azure 认知搜索索引的过程。This article walks you through the process of creating, loading, and querying an Azure Cognitive Search index using PowerShell and the Azure Cognitive Search REST APIs. 本文介绍如何以交互方式运行 PowerShell 命令。This article explains how to run PowerShell commands interactively. 你也可以下载并运行一个 PowerShell 脚本来执行相同的操作。Alternatively, you can download and run a PowerShell script that performs the same operations.

如果没有 Azure 订阅,可在开始前创建一个试用帐户If you don't have an Azure subscription, create a trial account before you begin.

先决条件Prerequisites

本快速入门需要以下服务和工具。The following services and tools are required for this quickstart.

获取密钥和 URLGet a key and URL

REST 调用需要在每个请求中使用服务 URL 和访问密钥。REST calls require the service URL and an access key on every request. 搜索服务是使用这二者创建的,因此,如果向订阅添加了 Azure 认知搜索,则请按以下步骤获取必需信息: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. 登录到 Azure 门户,在搜索服务的“概述”页中获取 URL。 Sign in to the Azure portal, and in your search service Overview page, get the URL. 示例终结点可能类似于 https://mydemo.search.azure.cnAn example endpoint might look like https://mydemo.search.azure.cn.

  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.

获取 HTTP 终结点和访问密钥Get an HTTP endpoint and access key

所有请求对发送到服务的每个请求都需要 API 密钥。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.

  1. 在 PowerShell 中,创建一个用于存储内容类型和 API 密钥的 $headers 对象。In PowerShell, create a $headers object to store the content-type and API key. 请将管理 API 密钥 (YOUR-ADMIN-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 will add it to every request.

    $headers = @{
    'api-key' = '<YOUR-ADMIN-API-KEY>'
    'Content-Type' = 'application/json' 
    'Accept' = 'application/json' }
    
  2. 创建用于指定服务索引集合的 $url 对象。Create a $url object that specifies the service's indexes collection. 请将服务名称 (YOUR-SEARCH-SERVICE-NAME) 替换为有效的搜索服务。Replace the service name (YOUR-SEARCH-SERVICE-NAME) with a valid search service.

    $url = "https://<YOUR-SEARCH-SERVICE-NAME>.search.azure.cn/indexes?api-version=2020-06-30&$select=name"
    
  3. 运行 Invoke-RestMethod,将 GET 请求发送到服务并验证连接。Run Invoke-RestMethod to send a GET request to the service and verify the connection. 添加 ConvertTo-Json,以便可以查看服务发回的响应。Add ConvertTo-Json so that you can view the responses sent back from the service.

    Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json
    

    如果服务为空且没有索引,则结果类似于以下示例。If the service is empty and has no indexes, results are similar to the following example. 否则,你将看到索引定义的 JSON 表示形式。Otherwise, you'll see a JSON representation of index definitions.

    {
        "@odata.context":  "https://mydemo.search.azure.cn/$metadata#indexes",
        "value":  [
    
                ]
    }
    

1 - 创建索引1 - Create an index

除非使用门户,服务中必须预先存在一个索引才能加载数据。Unless you are 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. 此步骤使用创建索引 REST APIThe Create Index REST API is used for this step.

索引的所需元素包括名称和字段集合。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 is full-text searchable, filterable, or retrievable in search results). 在索引中,必须将一个 Edm.String 类型的字段指定为文档标识的键。 Within an index, one of the fields of type Edm.String must be designated as the key for document identity.

此索引名为“hotels-quickstart”,使用下面所示的字段定义。This index is named "hotels-quickstart" and has the field definitions you see below. 它是其他演练文章中使用的一个更大 Hotels 索引的子集。It's a subset of a larger Hotels index used in other walk through articles. 为了方便,本快速入门中已对字段定义进行了剪裁。The field definitions have been trimmed in this quickstart for brevity.

  1. 请将此示例粘贴到 PowerShell 中,以创建包含索引架构的 $body 对象。Paste this example into PowerShell to create a $body object containing the index schema.

    $body = @"
    {
        "name": "hotels-quickstart",  
        "fields": [
            {"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true},
            {"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false},
            {"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"},
            {"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
            {"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true},
            {"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true},
            {"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true},
            {"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true},
            {"name": "Address", "type": "Edm.ComplexType", 
            "fields": [
            {"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true},
            {"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
            {"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
            {"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
            {"name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}
            ]
         }
      ]
    }
    "@
    
  2. 设置服务中的索引集合以及 hotels-quickstart 索引的 URI。Set the URI to the indexes collection on your service and the hotels-quickstart index.

    $url = "https://<YOUR-SEARCH-SERVICE>.search.azure.cn/indexes/hotels-quickstart?api-version=2020-06-30"
    
  3. 结合 $url$headers$body 运行该命令,以在服务中创建索引。Run the command with $url, $headers, and $body to create the index on the service.

    Invoke-RestMethod -Uri $url -Headers $headers -Method Put -Body $body | ConvertTo-Json
    

    结果应如下所示(为简明起见,已截断前两个字段后面的内容):Results should look similar to this (truncated to the first two fields for brevity):

    {
        "@odata.context":  "https://mydemo.search.azure.cn/$metadata#indexes/$entity",
        "@odata.etag":  "\"0x8D6EDE28CFEABDA\"",
        "name":  "hotels-quickstart",
        "defaultScoringProfile":  null,
        "fields":  [
                    {
                        "name":  "HotelId",
                        "type":  "Edm.String",
                        "searchable":  true,
                        "filterable":  true,
                        "retrievable":  true,
                        "sortable":  true,
                        "facetable":  true,
                        "key":  true,
                        "indexAnalyzer":  null,
                        "searchAnalyzer":  null,
                        "analyzer":  null,
                        "synonymMaps":  ""
                    },
                    {
                        "name":  "HotelName",
                        "type":  "Edm.String",
                        "searchable":  true,
                        "filterable":  false,
                        "retrievable":  true,
                        "sortable":  true,
                        "facetable":  false,
                        "key":  false,
                        "indexAnalyzer":  null,
                        "searchAnalyzer":  null,
                        "analyzer":  null,
                        "synonymMaps":  ""
                    },
    . . .
    

提示

若要进行验证,还可以在门户中检查“索引”列表。For verification, you could also check the Indexes list in the portal.

2 - 加载文档2 - Load documents

若要推送文档,请对索引的 URL 终结点使用 HTTP POST 请求。To push documents, use a HTTP POST request to your index's URL endpoint. 此任务的 REST API 为添加、更新或删除文档The REST API for this task is Add, Update, or Delete Documents.

  1. 请将此示例粘贴到 PowerShell 中,以创建包含所要上传的文档的 $body 对象。Paste this example into PowerShell to create a $body object containing the documents you want to upload.

    此请求包含两条完整记录和一条不完整的记录。This request includes two full and one partial record. 不完整的记录演示可以上传不完整的文档。The partial record demonstrates that you can upload incomplete documents. @search.action 参数指定如何编制索引。The @search.action parameter specifies how indexing is done. 有效值包括 upload、merge、mergeOrUpload 和 delete。Valid values include upload, merge, mergeOrUpload, and delete. mergeOrUpload 行为将创建 hotelId 为 3 的新文档,如果该文档已存在,则更新内容。The mergeOrUpload behavior either creates a new document for hotelId = 3, or updates the contents if it already exists.

    $body = @"
    {
        "value": [
        {
        "@search.action": "upload",
        "HotelId": "1",
        "HotelName": "Secret Point Motel",
        "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.",
        "Category": "Boutique",
        "Tags": [ "pool", "air conditioning", "concierge" ],
        "ParkingIncluded": false,
        "LastRenovationDate": "1970-01-18T00:00:00Z",
        "Rating": 3.60,
        "Address": 
            {
            "StreetAddress": "677 5th Ave",
            "City": "New York",
            "StateProvince": "NY",
            "PostalCode": "10022",
            "Country": "USA"
            } 
        },
        {
        "@search.action": "upload",
        "HotelId": "2",
        "HotelName": "Twin Dome Motel",
        "Description": "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
        "Category": "Boutique",
        "Tags": [ "pool", "free wifi", "concierge" ],
        "ParkingIncluded": false,
        "LastRenovationDate": "1979-02-18T00:00:00Z",
        "Rating": 3.60,
        "Address": 
            {
            "StreetAddress": "140 University Town Center Dr",
            "City": "Sarasota",
            "StateProvince": "FL",
            "PostalCode": "34243",
            "Country": "USA"
            } 
        },
        {
        "@search.action": "upload",
        "HotelId": "3",
        "HotelName": "Triple Landscape Hotel",
        "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.",
        "Category": "Resort and Spa",
        "Tags": [ "air conditioning", "bar", "continental breakfast" ],
        "ParkingIncluded": true,
        "LastRenovationDate": "2015-09-20T00:00:00Z",
        "Rating": 4.80,
        "Address": 
            {
            "StreetAddress": "3393 Peachtree Rd",
            "City": "Atlanta",
            "StateProvince": "GA",
            "PostalCode": "30326",
            "Country": "USA"
            } 
        },
        {
        "@search.action": "upload",
        "HotelId": "4",
        "HotelName": "Sublime Cliff Hotel",
        "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 1800 palace.",
        "Category": "Boutique",
        "Tags": [ "concierge", "view", "24-hour front desk service" ],
        "ParkingIncluded": true,
        "LastRenovationDate": "1960-02-06T00:00:00Z",
        "Rating": 4.60,
        "Address": 
            {
            "StreetAddress": "7400 San Pedro Ave",
            "City": "San Antonio",
            "StateProvince": "TX",
            "PostalCode": "78216",
            "Country": "USA"
            }
        }
    ]
    }
    "@
    
  2. 将终结点设置为 hotels-quickstart 文档集合,并包含索引操作 (indexes/hotels-quickstart/docs/index)。Set the endpoint to the hotels-quickstart docs collection and include the index operation (indexes/hotels-quickstart/docs/index).

    $url = "https://<YOUR-SEARCH-SERVICE>.search.azure.cn/indexes/hotels-quickstart/docs/index?api-version=2020-06-30"
    
  3. 结合 $url$headers$body 运行该命令,以将文档载入 hotels-quickstart 索引。Run the command with $url, $headers, and $body to load documents into the hotels-quickstart index.

    Invoke-RestMethod -Uri $url -Headers $headers -Method Post -Body $body | ConvertTo-Json
    

    结果应如以下示例所示。Results should look similar to the following example. 应会看到状态代码 201You should see a status code of 201.

    {
        "@odata.context":  "https://mydemo.search.azure.cn/indexes(\u0027hotels-quickstart\u0027)/$metadata#Collection(Microsoft.Azure.Search.V2019_05_06.IndexResult)",
        "value":  [
                    {
                        "key":  "1",
                        "status":  true,
                        "errorMessage":  null,
                        "statusCode":  201
                    },
                    {
                        "key":  "2",
                        "status":  true,
                        "errorMessage":  null,
                        "statusCode":  201
                    },
                    {
                        "key":  "3",
                        "status":  true,
                        "errorMessage":  null,
                        "statusCode":  201
                    },
                    {
                        "key":  "4",
                        "status":  true,
                        "errorMessage":  null,
                        "statusCode":  201
                    }
                ]
    }
    

3 - 搜索索引3 - Search an index

此步骤说明如何使用搜索文档 API 查询索引。This step shows you how to query an index using the Search Documents API.

请务必将搜索 $urls 括在单引号中。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..

  1. 将终结点设置为 hotels-quickstart 文档集合,并添加一个 search 参数以传入查询字符串。Set the endpoint to the hotels-quickstart docs collection and add a search parameter to pass in a query string.

    此字符串执行空搜索 (search=*),返回任意文档的未排名列表 (search score = 1.0)。This string executes an empty search (search=*), returning an unranked list (search score = 1.0) of arbitrary documents. 默认情况下,Azure 认知搜索每次返回 50 个匹配项。By default, Azure Cognitive Search returns 50 matches at a time. 由于已结构化,此查询将返回整个文档结构和值。As structured, this query returns an entire document structure and values. 添加 $count=true 以获取结果中所有文档的计数。Add $count=true to get a count of all documents in the results.

    $url = 'https://<YOUR-SEARCH-SERVICE>.search.azure.cn/indexes/hotels-quickstart/docs?api-version=2020-06-30&search=*&$count=true'
    
  2. 运行将 $url 发送到服务的命令。Run the command to send the $url to the service.

    Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json
    

    结果应如以下输出所示。Results should look similar to the following output.

    {
    "@odata.context":  "https://mydemo.search.azure.cn/indexes(\u0027hotels-quickstart\u0027)/$metadata#docs(*)",
    "@odata.count":  4,
    "value":  [
                  {
                      "@search.score":  0.1547872,
                      "HotelId":  "2",
                      "HotelName":  "Twin Dome Motel",
                      "Description":  "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
                      "Category":  "Boutique",
                      "Tags":  "pool free wifi concierge",
                      "ParkingIncluded":  false,
                      "LastRenovationDate":  "1979-02-18T00:00:00Z",
                      "Rating":  3.6,
                      "Address":  "@{StreetAddress=140 University Town Center Dr; City=Sarasota; StateProvince=FL; PostalCode=34243; Country=USA}"
                  },
                  {
                      "@search.score":  0.009068266,
                      "HotelId":  "3",
                      "HotelName":  "Triple Landscape Hotel",
                      "Description":  "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel\u0027s restaurant services.",
                      "Category":  "Resort and Spa",
                      "Tags":  "air conditioning bar continental breakfast",
                      "ParkingIncluded":  true,
                      "LastRenovationDate":  "2015-09-20T00:00:00Z",
                      "Rating":  4.8,
                      "Address":  "@{StreetAddress=3393 Peachtree Rd; City=Atlanta; StateProvince=GA; PostalCode=30326; Country=USA}"
                  },
                . . . 
    

尝试其他查询示例来了解语法。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.

# Query example 1
# Search the entire index for the terms 'restaurant' and 'wifi'
# Return only the HotelName, Description, and Tags fields
$url = 'https://<YOUR-SEARCH-SERVICE>.search.azure.cn/indexes/hotels-quickstart/docs?api-version=2020-06-30&search=restaurant wifi&$count=true&$select=HotelName,Description,Tags'

# Query example 2 
# Apply a filter to the index to find hotels rated 4 or higher
# Returns the HotelName and Rating. Two documents match.
$url = 'https://<YOUR-SEARCH-SERVICE>.search.azure.cn/indexes/hotels-quickstart/docs?api-version=2020-06-30&search=*&$filter=Rating gt 4&$select=HotelName,Rating'

# Query example 3
# Take the top two results, and show only HotelName and Category in the results
$url = 'https://<YOUR-SEARCH-SERVICE>.search.azure.cn/indexes/hotels-quickstart/docs?api-version=2020-06-30&search=boutique&$top=2&$select=HotelName,Category'

# Query example 4
# Sort by a specific field (Address/City) in ascending order

$url = 'https://<YOUR-SEARCH-SERVICE>.search.azure.cn/indexes/hotels-quickstart/docs?api-version=2020-06-30&search=pool&$orderby=Address/City asc&$select=HotelName, Address/City, Tags, Rating'

清理资源Clean up resources

在自己的订阅中操作时,最好在项目结束时确定是否仍需要已创建的资源。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.

可以使用左侧导航窗格中的“所有资源”或“资源组”链接 ,在门户中查找和管理资源。You can find and manage resources in the portal, using the All resources or Resource groups link in the left-navigation pane.

如果使用的是免费服务,请记住只能设置三个索引、索引器和数据源。If you are using a free service, remember that you are limited to three indexes, indexers, and data sources. 可以在门户中删除单个项目,以不超出此限制。You can delete individual items in the portal to stay under the limit.

后续步骤Next steps

在本快速入门中,已使用 PowerShell 逐步完成了在 Azure 认知搜索中创建和访问内容的基本工作流。In this quickstart, you used PowerShell to step through the basic workflow for creating and accessing content in Azure Cognitive Search. 我们建议,在了解相关概念后,继续学习更高级的方案,例如,从 Azure 数据源编制索引。With the concepts in mind, we recommend moving on to more advanced scenarios, such as indexing from Azure data sources;