快速入门:使用 REST 在 Azure AI 搜索中创建搜索索引

了解如何使用搜索 REST API 在 Azure AI 搜索中创建、加载和查询搜索索引。

本文使用 Postman 应用。 下载并导入 Postman 集合或使用本文中的说明手动创建请求。

如果没有 Azure 订阅,请在开始前创建一个试用版订阅

先决条件

复制密钥和 URL

REST 调用需要在每个请求中使用服务终结点和 API 密钥。 可以从 Azure 门户获取这些值。

  1. 登录到 Azure 门户,导航到概述页,并复制 URL。 示例终结点可能类似于 https://mydemo.search.azure.cn

  2. 在“设置”>“密钥”下,复制管理密钥。 管理密钥用于添加、修改和删除对象。 有两个可互换的管理密钥。 复制其中任意一个。

    Screenshot of the URL and API keys in the Azure portal.

具有有效的 API 密钥可以在发送请求的应用程序与处理请求的搜索服务之间建立信任关系,这种信任关系以每个请求为基础。

设置集合变量

Postman 在请求中提供了用括号括起来的集合变量,以便在每次请求中重复使用相同的字符串。 我们将集合变量用于特定于客户的值,例如 URI 中的 {{service-name}} 或请求标头中的 {{admin-key}}

具有多个变量的 URI 如下所示:

https://{{service-name}}.search.azure.cn/indexes/{{index-name}}?api-version={{api-version}}

Azure AI 搜索调用的请求标头必须将 Content-Type 设置为 application/json,将 api-key 设置为搜索服务的 API 密钥。 在本快速入门中,请求标头中的 api-key 指定为变量。

  1. 打开 Postman 应用并导入示例集合或创建新集合。

  2. 选择集合的访问菜单,选择“编辑”,并提供搜索服务名称和管理 API 密钥

    Screenshot of the Postman collection variable page.

创建索引

使用创建索引 (REST) 指定架构。 终结点包括 /indexes 集合和索引名称的 hotels-quickstart

  1. 将谓词设置为 PUT。

  2. 复制此 URL https://{{service-name}}.search.azure.cn/indexes/hotels-quickstart?api-version=2023-11-01

  3. 在“标头”下,将 Content-Type 设置为 application/json,并将 api-key 设置为 {{admin-key}}

  4. 在“正文”下粘贴索引定义(下一部分提供了可复制的 JSON)。 确保请求正文选择是“原始” ,并且类型是“JSON”

  5. 选择“发送”。

    Screenshot of the PUT create index request.

索引定义

字段集合定义文档结构。 每个文档必须包含这些字段,每个字段必须具有一个 EDM 数据类型。 字符串字段用于全文搜索。 如果希望数值数据可搜索,请确保数据类型为 Edm.String。 其他数据类型(如 Edm.Int32)可筛选、可排序、可分面、可检索,但不可全文搜索。

字段的属性决定了允许的操作。 默认情况下,REST API 允许很多操作。 例如,默认情况下,所有字符串都是可搜索和可检索的。 对于 REST API,可能只有在需要关闭某个行为时才需要进行属性设置。

{
    "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}
        ]
     }
  ]
}

提交此请求后,会获得 HTTP 201 响应,指示索引已成功创建。 可以验证门户中是否存在索引。

提示

如果收到 HTTP 504,请验证该 URL 是否指定了 HTTPS。 如果看到 HTTP 400 或 404,请检查请求正文,以验证是否没有复制粘贴错误。 HTTP 403 通常指示 API 密钥有问题(密钥无效或指定API 密钥的方式有语法问题)。

加载文档

创建和加载索引是两个独立的步骤。 在 Azure AI 搜索中,索引包含对搜索服务执行的所有可搜索数据和查询。 对于 REST 调用,数据以 JSON 文档的形式提供。 为此任务使用文档 - 索引 REST API

需扩展 URL 以包含 docs 集合与 index 操作。

  1. 将谓词设置为 POST。

  2. 复制此 URL https://{{service-name}}.search.azure.cn/indexes/hotels-quickstart/docs/index?api-version=2023-11-01

  3. 按照上一步的方法设置请求标头。

  4. 在请求正文中提供 JSON 文档(下一部分提供可复制的 JSON)。

  5. 选择“发送”。

    Screenshot of a POST load documents request.

要载入索引的 JSON 文档

请求正文包含四个要添加到 hotels 索引的文档。

{
    "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 Beijing. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make Beijing 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": "Beijing",
        "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"
        }
    }
  ]
}

在几秒钟内,应在会话列表中看到 HTTP 201 响应。 这指示已成功创建文档。

如果收到 207,则指示至少有一个文档无法上传。 如果收到 404,则表示请求的标头或正文有语法错误:请验证是否已更改终结点,使之包括 /docs/index

搜索索引

现在,索引和文档集已加载,可以使用搜索文档 REST API 针对它们发出查询了。

使用 GET 或 POST 查询索引。 在 GET 调用中,指定 URI 上的查询参数。 在 POST 上,用 JSON 指定查询参数。 POST 是设置多个查询参数的首选方式。

需扩展 URL,以包含使用 /docs/search 运算符指定的查询表达式。

  1. 将谓词设置为 GET。

  2. 复制此 URL https://{{service-name}}.search.azure.cn/indexes/hotels-quickstart/docs?search=*&$count=true&api-version=2023-11-01。 此请求没有 JSON 正文。 所有参数都位于 URI 上。 在 GET 请求中,API 版本前面有一个 & 字符。

  3. 选择“发送”。

    此查询为空,在搜索结果中返回文档的计数。 在选择“发送”后,请求和响应应类似于以下针对 Postman 的屏幕截图。 状态代码应为 200。

    Screenshot of a GET query request.

  4. 将谓词设置为 POST。

  5. 复制此 URL https://{{service-name}}.search.azure.cn/indexes/hotels-quickstart/docs/search?api-version=2023-11-01。 在 POST 请求中,API 版本前面有一个 ? 字符。

  6. 复制此 JSON 查询,然后选择“发送”

    {
        "search": "lake view",
        "select": "HotelId, HotelName, Tags, Description",
        "searchFields": "Description, Tags",
        "count": true
    }
    

    请求和响应看起来应当类似于以下屏幕截图。 如需更多查询示例(包括筛选器和排序),请参阅查询示例

获取索引属性

还可以使用获取统计信息来查询文档计数和索引大小:

https://{{service-name}}.search.azure.cn/indexes/hotels-quickstart/stats?api-version=2023-11-01

向 URL 添加 /stats 会返回索引信息。 在 Postman 中,请求应如下所示,响应包括文档计数和所用空间(以字节为单位)。

Screenshot of the Get Statistics request.

清理资源

在自己的订阅中操作时,最好在项目结束时确定是否仍需要已创建的资源。 持续运行资源可能会产生费用。 可以逐个删除资源,也可以删除资源组以删除整个资源集。

可以使用左侧导航窗格中的“所有资源”或“资源组”链接 ,在门户中查找和管理资源。

在免费服务中,请记住三个索引、索引器和数据源的限制。 可以在门户中删除单个项目,以不超出此限制。

后续步骤

了解如何执行基本任务后,请尝试使用高级功能,例如索引器或用于将内容转换添加到索引的扩充管道。 建议阅读以下文章: