메모
Foundry IQ (Azure AI 검색)는 관리형 검색을 위한 상위 수준의 지식 원본 및 지식 베이스 API와 함께 직접 인덱싱 및 쿼리 API를 제공합니다. Azure 포털, REST API 또는 Azure SDK 사용하여 이러한 기능을 구성하거나 Microsoft Foundry 포털의 기술 자료에 에이전트를 연결합니다.
이 문서에서는 이름 접두사로 목록 결과를 필터링하는 방법과 서버 쪽 페이징의 작동 방식을 설명합니다. 다중 테넌트 애플리케이션에 인덱스를 나열하여 둘 다 보여 줍니다.
REST 2026-11-01-preview API의 2026-10-01 목록 작업은 서버 쪽 페이징(커서 페이지 매김이라고도 함)을 사용합니다.
pageSize를 사용하여 이름 접두사로 목록을 필터링하고 search를 사용하여 각 페이지에서 원하는 결과 수를 설정합니다.
더 많은 결과가 있으면 응답에는 continuation URL이 포함됩니다. 해당 URL의 continuation token은 서비스가 어디서부터 이어갈지를 알려줍니다. 전체 목록을 스크롤하려면 응답에 더 이상 포함되지 않을 때까지 각 continuation URL을 따릅니다.
REST 예제에서는 2026-10-01를 사용합니다. C# 및 Python 예제는 2026-08-01-preview 및 미리 보기 SDK 패키지를 사용합니다.
사전 요구 사항
지원되는 목록 작업 중 하나에 대한 개체를 포함하는 foundry IQ(Azure AI 검색) 서비스입니다.
서비스의 개체를 나열할 수 있는 권한입니다. 사용자 계정에 할당된 Search Service 기여자 역할로 키 없는 인증을 구성하거나(권장) 관리자 API 키를 사용합니다.
최신
Azure.Search.Documents미리 보기 패키지:dotnet add package Azure.Search.Documents --prerelease키 없는 인증의 경우 패키지:
Azure.Identitydotnet add package Azure.Identity메모
클라이언트 라이브러리는 Search Service REST API의
2026-08-01-preview또는2026-10-01버전을 지원해야 합니다.2026-08-01-preview이전 버전은 이 문서에 표시된 필터 및 페이징 매개 변수를 무시합니다.
최신
azure-search-documents미리 보기 패키지:pip install --pre azure-search-documents키 없는 인증의 경우 패키지:
azure-identitypip install azure-identity메모
클라이언트 라이브러리는 Search Service REST API의
2026-08-01-preview또는2026-10-01버전을 지원해야 합니다.2026-08-01-preview이전 버전은 이 문서에 표시된 필터 및 페이징 매개 변수를 무시합니다.
Search Service REST API의 2026-10-01 버전입니다.
키 없는 인증의 경우 각 HTTP 요청의 헤더에 Microsoft Entra ID 토큰을
Authorization포함합니다.
SDK 예제 설정
샘플을 실행하도록 개발 환경을 구성합니다.
AZURE_SEARCH_ENDPOINT환경 변수를 Foundry IQ 서비스 엔드포인트로 설정합니다. 예제에서는 이 값을 읽어 클라이언트가 연결할 Foundry IQ 서비스를 알려줍니다.Azure CLI를 설치하고
az login로 로그인합니다.DefaultAzureCredential는 이 로그인 계정을 인증에 사용할 수 있습니다. 계정의 Search Service 기여자 역할은 목록 작업에 권한을 부여합니다.
다른 로컬 로그인 옵션은 로컬 개발을 위한 인증을 참조하세요.
목록 작업 선택
2026-10-01 REST API는 다음 목록 작업에 대해 서버 쪽 페이징을 지원합니다.
| Operation | 원본 경로 |
|---|---|
| 별칭 나열 | /aliases |
| 데이터 원본 나열 | /datasources |
| 인덱서 나열 | /indexers |
| 인덱스 나열 | /indexes |
| 인덱스 통계 요약 가져오기 | /indexstats |
| 기술 자료 나열 | /knowledgebases |
| 지식 소스 목록 | /knowledgesources |
| 기술 자료 파일 나열 | /knowledgesources('{knowledge-source-name}')/files |
| 기술 세트 목록 | /skillsets |
| 동의어 맵 나열 | /synonymmaps |
REST 요청의 경우 $select는 데이터 원본, 인덱서, 기술 세트, 동의어 맵 및 선택한 속성을 반환하는 인덱스 목록 오버로드에 대해 지원됩니다. 모든 목록 작업이 지원된다고 가정하지 마세요.
이름 접두사로 필터링
search 매개변수를 사용하여 이름이 입력한 텍스트로 시작하는 개체로 목록의 범위를 좁힐 수 있습니다.
파일 이름을 제외하고 이러한 목록 작업에서 반환되는 이름은 소문자입니다. 이름 접두사 일치는 대/소문자를 무시합니다. API는 search 값의 대문자 형태를 소문자로 변환하는 대신 잘못된 입력으로 거부합니다.
다음 매개 변수는 필터를 제어합니다.
| Parameter | Description |
|---|---|
search |
이름 접두사입니다. 비어 있지 않은 값은 소문자() 또는 숫자(a-z0-9)로 시작해야 하며 소문자, 숫자, 하이픈 및 밑줄만 포함해야 합니다. 최대 길이는 128자입니다. 잘못된 값은 HTTP 400을 반환합니다. 생략되거나 빈 값은 목록의 범위를 좁히지 않습니다. |
searchType |
search를 서비스가 어떻게 해석하는지.
prefix은 유일하게 지원되는 값이며 기본값입니다. 다른 값은 HTTP 400을 반환합니다. |
파일 목록의 경우 search는 상대 경로를 포함한 반환된 fileName 값과 대/소문자를 구분하지 않고 일치합니다. 파일 이름에는 대문자가 포함될 수 있습니다. 별도의 prefix 경로 필터는 대/소문자를 구분합니다.
겹치지 않는 테넌트 접두사를 선택합니다. 예를 들어 search=contoso-은 contoso-orders 및 contoso-products를 반환하지만 contoso2-orders는 제외합니다.
search=toso이(가) 포함된 요청은 필터가 이름의 시작 부분과 일치하므로 빈 value 배열을 반환합니다.
코드 예제
다음 코드는 다중 테넌트 애플리케이션에서 한 테넌트의 인덱스를 나열합니다. 각 인덱스 이름은 contoso2- 또는 contoso-와 같은 테넌트 접두사로 시작합니다.
코드는 목록을 contoso- 접두사로 필터링하고 페이지당 최대 10개의 인덱스를 요청합니다. 일치하는 인덱스가 27개인 테넌트에서 서비스는 10개, 10개 및 7개의 인덱스를 포함하는 페이지를 반환할 수 있습니다.
루프는 필터링된 목록의 시작 부분에서 시작됩니다. 다시 시작하려면 저장된 page.ContinuationToken 값을 AsPages(token)에 전달합니다.
using System;
using Azure;
using Azure.Identity;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;
string endpoint = Environment.GetEnvironmentVariable(
"AZURE_SEARCH_ENDPOINT")!;
var options = new SearchClientOptions(
SearchClientOptions.ServiceVersion.V2026_08_01_Preview);
var client = new SearchIndexClient(
new Uri(endpoint),
new DefaultAzureCredential(),
options);
// Filter by the tenant prefix and limit each page to 10 indexes
AsyncPageable<SearchIndex> indexes = client.GetIndexesAsync(
search: "contoso-",
pageSize: 10,
searchType: ListingSearchType.Prefix);
// Fetch pages until the service returns no continuation token
await foreach (Page<SearchIndex> page in indexes.AsPages())
{
// Read the indexes in this page without fetching another page
foreach (SearchIndex index in page.Values)
{
Console.WriteLine(index.Name);
}
}
참조:SearchIndexClient.GetIndexesAsync, AsPages, ContinuationToken 및 DefaultAzureCredential
외부 루프는 AsPages()를 한 번 호출하고 SDK는 각 반복에서 페이지를 가져와서 다음 요청에 대한 연속 토큰을 유지합니다. 외부 루프는 각 서비스 응답을 기다리기 위해 await를 사용하며, 스레드를 차단하지 않고 내부 루프는 메모리의 인덱스를 읽습니다. 마지막 페이지에 null 연속성 토큰이 있으면 SDK는 더 이상 페이지가 없다고 보고하고 루프가 종료됩니다.
외부 루프는 페이지를 순회합니다. 내부 루프는 각 페이지의 인덱스를 순회합니다.
import os
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
endpoint = os.getenv("AZURE_SEARCH_ENDPOINT")
with SearchIndexClient(
endpoint,
DefaultAzureCredential(),
api_version="2026-08-01-preview",
) as client:
# Filter by the tenant prefix and limit each page to 10 indexes
indexes = client.list_indexes(
select=["name"],
search="contoso-",
page_size=10,
search_type="prefix",
)
# Create the page iterator once, starting at the first page
pages = indexes.by_page()
# Fetch pages until the service returns no continuation token
for page in pages:
# Read the indexes in this page without fetching another page
for index in page:
print(index.name)
참조:SearchIndexClient.list_indexes, ItemPaged.by_page 및 DefaultAzureCredential
by_page() 는 페이지 반복기를 한 번 만든 다음 for page in pages 해당 반복기에 저장된 연속 토큰을 사용하여 각 페이지를 요청합니다. 내부 루프는 다른 요청 없이 한 페이지의 인덱스를 읽는 반면, 마지막 페이지에 None 연속 토큰이 없으면 외부 루프가 중지됩니다. 새 반복기는 토큰 또는 None 없이 첫 번째 페이지에서 시작되고, by_page(continuation_token=token)는 저장된 토큰에서 다시 시작됩니다.
초기 요청을 보내 이름이 contoso-로 시작하는 인덱스를 나열합니다. 요청은 최대 10가지 인덱스 이름을 반환합니다.
GET https://<search-service-name>.search.windows.net/indexes?api-version=2026-10-01&search=contoso-&searchType=prefix&pageSize=10&$select=name
Authorization: Bearer <access-token>
Accept: application/json
참조:인덱스 나열
더 많은 결과가 있는 경우 응답에는 전체 연속 URL과 불투명 토큰이 포함된 @odata.nextLink가 포함됩니다. 페이지에는 10개 미만의 결과가 포함될 수 있으며 연속 URL이 계속 포함될 수 있습니다. 다음 응답은 약어입니다.
{
"value": [
{
"name": "<index-name>"
}
],
"@odata.nextLink": "https://<search-service-name>.search.windows.net/indexes?api-version=2026-10-01&searchType=prefix&%24select=name&%24skiptoken=<opaque-token>"
}
다음 페이지를 요청하려면 GET 요청을 반환된 대로 정확하게 전체 @odata.nextLink 값으로 보냅니다.
search 값과 페이지 크기는 연속 토큰에 인코딩됩니다. 동일한 인증 헤더를 유지합니다.
GET <[email protected]>
Authorization: Bearer <access-token>
Accept: application/json
참조:인덱스 나열
각 새 @odata.nextLink 값으로 요청을 반복합니다. 마지막 페이지에는 나머지 인덱스 이름이 포함되며 @odata.nextLink는 생략됩니다. 이는 더 이상 사용할 수 있는 페이지가 없음을 나타냅니다.
{
"value": [
{
"name": "<next-index-name>"
}
]
}
서버 쪽 페이징 동작
마지막 페이지를 감지합니다: 페이지에 요청된 것보다 적은 결과가 포함된 경우에도 응답에
@odata.nextLink이 포함되어 있는 동안 페이징을 계속합니다. 마지막 페이지에는 이 속성이 없습니다. 응답에는@odata.count이(가) 포함되지 않습니다.연속 상태를 유지합니다. 반환된 대로 정확하게 전체
@odata.nextLink항목을 사용합니다. 연속 토큰($skiptoken값)을 생성, 수정 또는 디코딩하지 말고 다른 목록 작업과 함께 사용하지 마세요. 토큰은 전달 페이징만 지원합니다.요청 매개 변수 변경: 새 초기 요청을 시작하여 리소스 경로, API 버전, 검색 접두사, 선택한 속성 또는 페이지 크기를 변경합니다.
$skiptokenHTTP 400과search결합하거나pageSize반환합니다.컬렉션 변경 고려: 전달 페이징은 컬렉션이 변경되지 않은 상태로 유지되는 동안에만 안정적입니다. 열거 중에 개체를 추가, 업데이트 또는 삭제하면 중복되거나 생략된 결과가 생성될 수 있습니다.
결과 순서에 의존하지 마세요 . 서비스는 결과의 순서를 보장하지 않습니다.
페이지 크기를 설정합니다.
pageSize는 페이지당 3,000개 항목으로 기본 설정되며 최대 허용 값은 3,000개입니다.