Foundry IQ(Azure AI 검색) 목록 결과 페이지 탐색

메모

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 패키지를 사용합니다.

사전 요구 사항

  • 최신 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 이전 버전은 이 문서에 표시된 필터 및 페이징 매개 변수를 무시합니다.

SDK 예제 설정

샘플을 실행하도록 개발 환경을 구성합니다.

  1. AZURE_SEARCH_ENDPOINT 환경 변수를 Foundry IQ 서비스 엔드포인트로 설정합니다. 예제에서는 이 값을 읽어 클라이언트가 연결할 Foundry IQ 서비스를 알려줍니다.

  2. 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 버전, 검색 접두사, 선택한 속성 또는 페이지 크기를 변경합니다. $skiptoken HTTP 400과 search 결합하거나 pageSize 반환합니다.

  • 컬렉션 변경 고려: 전달 페이징은 컬렉션이 변경되지 않은 상태로 유지되는 동안에만 안정적입니다. 열거 중에 개체를 추가, 업데이트 또는 삭제하면 중복되거나 생략된 결과가 생성될 수 있습니다.

  • 결과 순서에 의존하지 마세요 . 서비스는 결과의 순서를 보장하지 않습니다.

  • 페이지 크기를 설정합니다.pageSize 는 페이지당 3,000개 항목으로 기본 설정되며 최대 허용 값은 3,000개입니다.