你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
注释
Foundry IQ (Azure AI 搜索) 提供直接索引和查询 API 以及用于托管检索的高级知识库和知识库 API。 使用 Azure 门户、REST API 或Azure SDK配置这些功能,或将代理连接到 Microsoft Foundry 门户中的知识库。
在上一步中,你已将已启用搜索的网站部署到Azure 容器应用。 本文重点介绍建立搜索集成的基本步骤。 将其视为将搜索集成到 Web 应用中的备忘单。
Azure SDK Azure.Search.Documents
API 使用Azure SDK进行Azure AI 搜索:
- NuGet: Azure.Search.Documents
- 参考文档: 客户端库
API 使用 Foundry IQ 服务名称和索引名称通过 SDK 向基于云的 Foundry IQ API 进行身份验证。 在Azure 容器应用中,容器环境提供配置值。 托管标识是默认凭据路径。
托管身份认证
API 中的每个Azure函数都通过共享SearchClient类创建它SearchClientFactory,因此每个函数都以相同的方式进行身份验证。 默认情况下,工厂会生成一个 DefaultAzureCredential 并使用它来请求 Foundry IQ 的令牌。 在Azure 容器应用中,DefaultAzureCredential解析为分配给容器应用的托管标识。
以下来自 SearchClientFactory.cs 的方法创建了该凭据。 当容器应用具有用户分配的托管标识时,会将来自环境变量 AZURE_CLIENT_ID 的客户端 ID 传递给 DefaultAzureCredentialOptions,以避免令牌获取出现歧义。
private static DefaultAzureCredential CreateManagedIdentityCredential()
{
var options = new DefaultAzureCredentialOptions();
if (!string.IsNullOrWhiteSpace(ManagedIdentityClientId))
{
options.ManagedIdentityClientId = ManagedIdentityClientId;
}
return new DefaultAzureCredential(options);
}
Bicep 基础结构在 azd up 期间为托管标识分配对 Foundry IQ 数据平面的访问权限。 此角色分配允许 API 在不将查询密钥存储在容器环境中的情况下查询 good-books 索引。
本地凭据解析与已部署凭据解析
在本地,如果未设置AZURE_CLIENT_ID,DefaultAzureCredential会回退到其标准凭据链,并解析为你已登录的开发人员凭据,例如你用于登录的 Azure CLI 或 Visual Studio Code 帐户。 部署到Azure 容器应用时,Bicep基础结构将 AZURE_CLIENT_ID 设置为用户分配的托管标识的客户端 ID,因此DefaultAzureCredential会专门针对该标识,而不是在主机可公开的多个标识之间发生歧义解析。
若要改用 API 密钥,请在部署之前将 USE_KEYLESS_AUTH 设置为 false:
azd env set USE_KEYLESS_AUTH false
azd up
仅当环境需要密钥身份验证时,才使用密钥身份验证。
本地开发设置
对于本地开发,示例 sample.local.settings.json 文件显示 API 所需的值。 本地设置仅用于开发。 在Azure 容器应用中,部署配置提供等效的容器环境值。
| 设置 | Purpose | 在以下情况下需要 |
|---|---|---|
SearchServiceName |
Foundry IQ 服务的名称。 与 .search.windows.net 生成服务终结点 URI 结合使用。 |
始终 |
SearchIndexName |
要查询的搜索索引的名称。 如果未设置,则默认为 。 | Optional |
SEARCH_USE_KEY_AUTH |
默认值为 false,使用托管标识。
将其设置为 true,以使用 API 密钥而不是托管标识。 |
可选的密钥验证 |
SearchApiKey |
Foundry IQ 的管理密钥。 | 当 SEARCH_USE_KEY_AUTH 为 true 时,为必填项 |
{
"IsEncrypted": false,
"Values": {
"AzureWebJobsStorage": "",
"FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
"SearchServiceName": "",
"SearchIndexName": "good-books"
},
"Host": {
"CORS": "*"
}
}
函数:搜索目录
搜索 API 采用搜索词并搜索搜索索引中的文档,并返回匹配项列表。 通过 Suggest API,当用户输入时,部分字符串会被发送到搜索引擎。 API 根据搜索索引中的文档建议搜索词(如书籍标题和作者),并返回一小系列匹配项。
Azure函数从容器环境中拉取搜索配置信息,创建 Foundry IQ 客户端并完成查询。
搜索建议器 sg是在批量上传期间使用的 架构文件中 定义的。
using Azure;
using Azure.Core.Serialization;
using Azure.Identity;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Http;
using Microsoft.Extensions.Logging;
using System.Net;
using System.Text.Json;
using System.Text.Json.Serialization;
using WebSearch.Models;
using SearchFilter = WebSearch.Models.SearchFilter;
namespace WebSearch.Function
{
public class Search
{
private readonly ILogger<Lookup> _logger;
public Search(ILogger<Lookup> logger)
{
_logger = logger;
}
[Function("search")]
public async Task<HttpResponseData> RunAsync(
[HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequestData req,
FunctionContext executionContext)
{
string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
var data = JsonSerializer.Deserialize<RequestBodySearch>(requestBody);
// Azure AI Search (managed identity by default; API key only when SEARCH_USE_KEY_AUTH=true)
SearchClient searchClient = SearchClientFactory.CreateSearchClient();
SearchOptions options = new()
{
Size = data.Size,
Skip = data.Skip,
IncludeTotalCount = true,
Filter = CreateFilterExpression(data.Filters)
};
options.Facets.Add("authors");
options.Facets.Add("language_code");
SearchResults<SearchDocument> searchResults = searchClient.Search<SearchDocument>(data.SearchText, options);
var facetOutput = new Dictionary<string, IList<FacetValue>>();
foreach (var facetResult in searchResults.Facets)
{
facetOutput[facetResult.Key] = facetResult.Value
.Select(x => new FacetValue { value = x.Value.ToString(), count = x.Count })
.ToList();
}
// Data to return
var output = new SearchOutput
{
Count = searchResults.TotalCount,
Results = searchResults.GetResults().ToList(),
Facets = facetOutput
};
var response = req.CreateResponse(HttpStatusCode.Found);
// Serialize data
var serializer = new JsonObjectSerializer(
new JsonSerializerOptions(JsonSerializerDefaults.Web));
await response.WriteAsJsonAsync(output, serializer);
return response;
}
public static string CreateFilterExpression(List<SearchFilter> filters)
{
if (filters is null or { Count: <= 0 })
{
return null;
}
List<string> filterExpressions = new();
List<SearchFilter> authorFilters = filters.Where(f => f.field == "authors").ToList();
List<SearchFilter> languageFilters = filters.Where(f => f.field == "language_code").ToList();
List<string> authorFilterValues = authorFilters.Select(f => f.value).ToList();
if (authorFilterValues.Count > 0)
{
string filterStr = string.Join(",", authorFilterValues);
filterExpressions.Add($"{"authors"}/any(t: search.in(t, '{filterStr}', ','))");
}
List<string> languageFilterValues = languageFilters.Select(f => f.value).ToList();
foreach (var value in languageFilterValues)
{
filterExpressions.Add($"language_code eq '{value}'");
}
return string.Join(" and ", filterExpressions);
}
}
}
若要独立验证函数,请在请求正文中使用搜索词进行调用 /api/search ,并确认响应包括匹配的书籍文档、总计计数和分面值。
客户端:搜索目录
每当用户输入查询、更改分面筛选器或移动到新结果页时,React 客户端的搜索页就会调用searchAzure函数。 客户端将 POST 正文中的搜索文本、当前页 skip 和 top 值以及任何选定的作者或语言筛选器发送到 /api/search。 该函数返回匹配的书籍文档、总计计数和分面值的列表,页面使用该列表呈现结果列表、寻呼器和分面筛选器。
\client\src\pages\Search\Search.jsx 中的以下代码构建该请求,并将响应存储在组件状态中:
import React, { useEffect, useState, Suspense } from 'react';
import fetchInstance from '../../url-fetch';
import CircularProgress from '@mui/material/CircularProgress';
import { useLocation, useNavigate } from "react-router-dom";
import Grid from '@mui/material/Grid';
import Box from '@mui/material/Box';
import Container from '@mui/material/Container';
import Results from '../../components/Results/Results';
import Pager from '../../components/Pager/Pager';
import Facets from '../../components/Facets/Facets';
import SearchBar from '../../components/SearchBar/SearchBar';
import { SearchMain, SearchBarColumn, SearchBarResults, SearchBarColumnContainer, SearchResultsContainer, PagerStyle } from './styled';
export default function Search() {
let location = useLocation();
const navigate = useNavigate();
const [results, setResults] = useState([]);
const [q, setQ] = useState(new URLSearchParams(location.search).get('q') ?? "*");
const [resultCount, setResultCount] = useState(0);
const [currentPage, setCurrentPage] = useState(1);
const [top] = useState(new URLSearchParams(location.search).get('top') ?? 8);
const [skip, setSkip] = useState(new URLSearchParams(location.search).get('skip') ?? 0);
const [filters, setFilters] = useState([]);
const [facets, setFacets] = useState({});
const [isLoading, setIsLoading] = useState(true);
let resultsPerPage = top;
// Handle page changes in a controlled manner
function handlePageChange(newPage) {
setCurrentPage(newPage);
}
// Calculate skip value and fetch results when relevant parameters change
useEffect(() => {
// Calculate skip based on current page
const calculatedSkip = (currentPage - 1) * top;
// Only update if skip has actually changed
if (calculatedSkip !== skip) {
setSkip(calculatedSkip);
return; // Skip the fetch since skip will change and trigger another useEffect
}
// Proceed with fetch
setIsLoading(true);
const body = {
q: q,
top: top,
skip: skip,
filters: filters
};
fetchInstance('/api/search', { body, method: 'POST' })
.then(response => {
setResults(response.results);
setFacets(response.facets);
setResultCount(response.count);
setIsLoading(false);
})
.catch(error => {
console.log(error);
setIsLoading(false);
});
}, [q, top, skip, filters, currentPage]);
// pushing the new search term to history when q is updated
// allows the back button to work as expected when coming back from the details page
useEffect(() => {
navigate('/search?q=' + q);
setCurrentPage(1);
setFilters([]);
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [q]);
let postSearchHandler = (searchTerm) => {
setQ(searchTerm);
};
// filters should be applied across entire result set,
// not just within the current page
const updateFilterHandler = (newFilters) => {
// Reset paging
setSkip(0);
setCurrentPage(1);
// Set filters
setFilters(newFilters);
};
return (<Container maxWidth={false} component={SearchMain} sx={{ marginTop: 2 }}>
<Grid container spacing={2} sx={{ px: 2, marginTop: 2 }}> {/* Added horizontal padding and top margin */}
<Grid item xs={12} md={3} component={SearchBarColumn} sx={{
padding: '8px 16px 16px 16px',
borderRight: '1px solid #f0f0f0'
}}>
<SearchBarColumnContainer>
<SearchBar postSearchHandler={postSearchHandler} query={q} width={false}></SearchBar>
</SearchBarColumnContainer>
<Facets facets={facets} filters={filters} setFilters={updateFilterHandler}></Facets>
</Grid>
<Grid item xs={12} md={9} component={SearchBarResults}>
{isLoading ? (<Box display="flex" justifyContent="center" p={2}>
<CircularProgress />
</Box>) : (<SearchResultsContainer>
<Results documents={results} top={top} skip={skip} count={resultCount} query={q}></Results>
<PagerStyle>
<Pager currentPage={currentPage} resultCount={resultCount} resultsPerPage={resultsPerPage} onPageChange={handlePageChange}></Pager>
</PagerStyle>
</SearchResultsContainer>)}
</Grid>
</Grid>
</Container>);
}
若要验证此集成,请在网站的搜索栏中输入一个搜索词,并确认结果列表、结果计数和方面是否全部更新。
客户:来自目录的建议
Suggest 函数 API 在 React 应用中的 \client\src\components\SearchBar\SearchBar.jsx 处被调用,作为 Material UI Autocomplete 组件的一部分。 此组件使用输入文本搜索匹配的作者和书籍。 然后,它将这些可能的匹配项显示为下拉列表中的可选项。
import React, { useState, useEffect } from 'react';
import { TextField } from '@mui/material';
import fetchInstance from '../../url-fetch';
import {
SearchAutocomplete,
SearchBox,
SearchButton,
SearchContainer,
} from './styles';
const suggestionListStyles = {
padding: 0,
'& .MuiAutocomplete-option': {
minHeight: '40px',
padding: '8px 14px',
textAlign: 'left',
},
};
export default function SearchBar({ postSearchHandler, query, width }) {
const [q, setQ] = useState(() => query || '');
const [suggestions, setSuggestions] = useState([]);
const search = (value) => {
postSearchHandler(value);
};
useEffect(() => {
if (q) {
const body = { q, top: 5, suggester: 'sg' };
fetchInstance('/api/suggest', { body, method: 'POST' })
.then(response => {
setSuggestions(response.suggestions.map(s => s.text));
})
.catch(error => {
console.log(error);
setSuggestions([]);
});
}
}, [q]);
const onInputChangeHandler = (event, value) => {
setQ(value);
};
const onChangeHandler = (event, value) => {
setQ(value);
search(value);
};
const onEnterButton = (event) => {
if (event.key === 'Enter') {
search(q);
}
};
return (
<SearchContainer $wide={Boolean(width)}>
<SearchBox>
<SearchAutocomplete
freeSolo
value={q}
options={suggestions}
onInputChange={onInputChangeHandler}
onChange={onChangeHandler}
disableClearable
ListboxProps={{ sx: suggestionListStyles }}
renderInput={(params) => (
<TextField
{...params}
id="search-box"
placeholder="What are you looking for?"
onBlur={() => setSuggestions([])}
onClick={() => setSuggestions([])}
onKeyDown={onEnterButton}
/>
)}
/>
<SearchButton variant="contained" onClick={() => search(q)}>
Search
</SearchButton>
</SearchBox>
</SearchContainer>
);
}
若要验证此集成,请在网站的搜索栏中输入文本,并确认匹配的书籍标题和作者显示在自动完成下拉列表中。
函数:获取特定文档
当用户从搜索结果中选中某本图书后,文档查找 API 会检索该图书的完整文档内容。 该函数从请求的查询字符串中读取书籍 id,使用 SearchClientFactory 创建经过身份验证的 SearchClient,并调用 GetDocumentAsync 在 good-books 索引中查找该键。 它返回封装在 LookupOutput 对象中的结果文档。
using Azure;
using Azure.Core.Serialization;
using Azure.Identity;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Http;
using Microsoft.Extensions.Logging;
using System.Net;
using System.Text.Json;
using WebSearch.Models;
namespace WebSearch.Function
{
public class Lookup
{
private readonly ILogger<Lookup> _logger;
public Lookup(ILogger<Lookup> logger)
{
_logger = logger;
}
[Function("lookup")]
public async Task<HttpResponseData> RunAsync(
[HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestData req,
FunctionContext executionContext)
{
// Get Document Id
var query = System.Web.HttpUtility.ParseQueryString(req.Url.Query);
string documentId = query["id"].ToString();
// Azure AI Search (managed identity by default; API key only when SEARCH_USE_KEY_AUTH=true)
SearchClient searchClient = SearchClientFactory.CreateSearchClient();
var getDocumentResponse = await searchClient.GetDocumentAsync<SearchDocument>(documentId);
// Data to return
var output = new LookupOutput
{
Document = getDocumentResponse.Value
};
var response = req.CreateResponse(HttpStatusCode.Found);
// Serialize data
var serializer = new JsonObjectSerializer(
new JsonSerializerOptions(JsonSerializerDefaults.Web));
await response.WriteAsJsonAsync(output, serializer);
return response;
}
}
}
若要独立验证查找函数,请使用有效的图书 ID id调用 /api/lookup,并确认响应返回该书籍的完整文档。
客户端:获取特定文档
当用户从搜索结果中选择书籍时,“详细信息”页需要该书籍的完整文档,包括摘要列表中未显示的字段。 “详细信息”页从路由参数中读取书籍 id ,并在组件装载时通过 /api/lookup 调用文档查找 API。 它将返回的文档存储在组件状态中,并在 “结果” 和 “原始数据” 选项卡中显示该文档。 在组件初始化期间执行此查找的以下代码 \client\src\pages\Details\Details.jsx :
import React, { useState, useEffect } from "react";
import { useParams } from 'react-router-dom';
import Rating from '@mui/material/Rating';
import CircularProgress from '@mui/material/CircularProgress';
import Tabs from '@mui/material/Tabs';
import Tab from '@mui/material/Tab';
import Box from '@mui/material/Box';
import fetchInstance from '../../url-fetch';
import { TabPanel, TabPanelValue, CardBody, ImageContainer, CardTitle, CardText, BoxContent, DetailsBoxParent, DetailsTabBoxHeader, DetailsCustomTabPanelJsonDiv } from './styled';
function CustomTabPanel(props) {
const { children, value, index, ...other } = props;
return (<TabPanel role="tabpanel" hidden={value !== index} id={`simple-tabpanel-${index}`} aria-labelledby={`simple-tab-${index}`} {...other}>
{value === index && <TabPanelValue>{children}</TabPanelValue>}
</TabPanel>);
}
export default function BasicTabs() {
const { id } = useParams();
const [document, setDocument] = useState({});
const [value, setValue] = React.useState(0);
const [isLoading, setIsLoading] = useState(true);
useEffect(() => {
setIsLoading(true);
fetchInstance('/api/lookup', { query: { id: id } })
.then(response => {
console.log(JSON.stringify(response));
const doc = response.document;
setDocument(doc);
setIsLoading(false);
})
.catch(error => {
console.log(error);
setIsLoading(false);
});
}, [id]);
const handleChange = (event, newValue) => {
setValue(newValue);
};
if (isLoading || !id || Object.keys(document).length === 0) {
return (<Box sx={{ display: 'flex', flexDirection: 'column', alignItems: 'center', padding: '2em' }}>
<CircularProgress />
<Box sx={{ mt: 2 }}>Loading...</Box>
</Box>);
}
return (<DetailsBoxParent>
<DetailsTabBoxHeader>
<Tabs value={value} onChange={handleChange} aria-label="book-details-tabs">
<Tab label="Result"/>
<Tab label="Raw Data"/>
</Tabs>
</DetailsTabBoxHeader>
<CustomTabPanel value={value} index={0} component={BoxContent}>
<CardBody>
<CardTitle variant="h5">{document.original_title}</CardTitle>
<ImageContainer src={document.image_url} alt="Book cover"/>
<CardText variant="body1">{document.authors?.join('; ')} - {document.original_publication_year}</CardText>
<CardText variant="body1">ISBN {document.isbn}</CardText>
<Rating name="half-rating-read" value={parseInt(document.average_rating)} precision={0.1} readOnly></Rating>
<CardText variant="body1">{document.ratings_count} Ratings</CardText>
</CardBody>
</CustomTabPanel>
<CustomTabPanel value={value} index={1} component={BoxContent}>
<CardBody>
<DetailsCustomTabPanelJsonDiv>
<pre><code>
{JSON.stringify(document, null, 2)}
</code></pre>
</DetailsCustomTabPanelJsonDiv>
</CardBody>
</CustomTabPanel>
</DetailsBoxParent>);
}
若要验证此集成,请从搜索结果中选择一本书,并确认其详细信息(包括封面图像、作者和分级)显示在“详细信息”页面上。
支持 API 的 C# 模型
Azure Functions API 和大容量导入项目共享一组 C# 模型类。 这些类定义了客户端发送的请求主体,例如搜索文本、分页参数和筛选器。 他们还定义客户端期望的响应形状,例如搜索结果、分面值和单个查找文档。 将这些模型保存在一个文件中可确保搜索、建议和文档查找终结点与 React 客户端的预期保持一致。 以下模型定义在 Models.cs 中,支持此应用中的功能:
using Azure.Search.Documents.Models;
using System.Text.Json.Serialization;
namespace WebSearch.Models
{
public class RequestBodyLookUp
{
[JsonPropertyName("id")]
public string Id { get; set; }
}
public class RequestBodySuggest
{
[JsonPropertyName("q")]
public string SearchText { get; set; }
[JsonPropertyName("top")]
public int Size { get; set; }
[JsonPropertyName("suggester")]
public string SuggesterName { get; set; }
}
public class RequestBodySearch
{
[JsonPropertyName("q")]
public string SearchText { get; set; }
[JsonPropertyName("skip")]
public int Skip { get; set; }
[JsonPropertyName("top")]
public int Size { get; set; }
[JsonPropertyName("filters")]
public List<SearchFilter> Filters { get; set; }
}
public class SearchFilter
{
public string field { get; set; }
public string value { get; set; }
}
public class FacetValue
{
public string value { get; set; }
public long? count { get; set; }
}
class SearchOutput
{
[JsonPropertyName("count")]
public long? Count { get; set; }
[JsonPropertyName("results")]
public List<SearchResult<SearchDocument>> Results { get; set; }
[JsonPropertyName("facets")]
public Dictionary<String, IList<FacetValue>> Facets { get; set; }
}
class LookupOutput
{
[JsonPropertyName("document")]
public SearchDocument Document { get; set; }
}
public class BookModel
{
public string id { get; set; }
public decimal? goodreads_book_id { get; set; }
public decimal? best_book_id { get; set; }
public decimal? work_id { get; set; }
public decimal? books_count { get; set; }
public string isbn { get; set; }
public string isbn13 { get; set; }
public string[] authors { get; set; }
public decimal? original_publication_year { get; set; }
public string original_title { get; set; }
public string title { get; set; }
public string language_code { get; set; }
public double? average_rating { get; set; }
public decimal? ratings_count { get; set; }
public decimal? work_ratings_count { get; set; }
public decimal? work_text_reviews_count { get; set; }
public decimal? ratings_1 { get; set; }
public decimal? ratings_2 { get; set; }
public decimal? ratings_3 { get; set; }
public decimal? ratings_4 { get; set; }
public decimal? ratings_5 { get; set; }
public string image_url { get; set; }
public string small_image_url { get; set; }
}
}
后续步骤
若要继续了解 Foundry IQ 开发,请尝试下一篇有关索引的教程: