Stronicuj wyniki listy Foundry IQ (Wyszukiwanie AI platformy Azure)

Note

Foundry IQ (Wyszukiwanie AI platformy Azure) udostępnia bezpośrednie interfejsy API indeksowania i zapytań, a także interfejsy API wyższego poziomu dla źródeł wiedzy i baz wiedzy do zarządzanego pobierania. Użyj portalu Azure, interfejsów API REST lub Azure SDKs, aby skonfigurować te możliwości lub połączyć agentów z bazami wiedzy w portalu Microsoft Foundry.

W tym artykule wyjaśniono, jak filtrować wyniki na liście według prefiksu nazwy i jak działa stronicowanie po stronie serwera. Demonstruje oba te elementy, wyświetlając listę indeksów w aplikacji wielodzierżawnej.

Operacje listy w 2026-10-01 interfejsach API REST i 2026-11-01-preview używają stronicowania po stronie serwera, nazywanego również stronicowaniem kursora. Użyj search, aby filtrować listę według prefiksu nazwy, a pageSize, aby ustawić liczbę wyników na stronę.

Gdy dostępnych jest więcej wyników, odpowiedź zawiera adres URL kontynuacji. Token kontynuacji w tym adresie URL informuje usługę, w którym miejscu ma wznowić działanie. Aby przewinąć pełną listę, postępuj zgodnie z każdym adresem URL kontynuacji, dopóki odpowiedź przestanie go zawierać.

W przykładach REST użyto polecenia 2026-10-01. Przykłady języka C# i Python używają 2026-08-01-preview oraz pakietów SDK w wersji zapoznawczej.

Wymagania wstępne

  • Najnowszy pakiet Azure.Search.Documents wersji zapoznawczej: dotnet add package Azure.Search.Documents --prerelease

  • W przypadku uwierzytelniania bezkluczowego pakiet Azure.Identity: dotnet add package Azure.Identity

    Note

    Biblioteka klienta musi obsługiwać wersję 2026-10-01 lub 2026-08-01-preview interfejsu API REST usługi wyszukiwania. Wersje wcześniejsze niż 2026-08-01-preview ignorują parametry filtru i stronicowania pokazane w tym artykule.

  • Najnowszy pakiet azure-search-documents wersji zapoznawczej: pip install --pre azure-search-documents

  • W przypadku uwierzytelniania bezkluczowego pakiet azure-identity: pip install azure-identity

    Note

    Biblioteka klienta musi obsługiwać wersję 2026-10-01 lub 2026-08-01-preview interfejsu API REST usługi wyszukiwania. Wersje wcześniejsze niż 2026-08-01-preview ignorują parametry filtru i stronicowania pokazane w tym artykule.

  • Wersja 2026-10-01 interfejsu API REST usługi wyszukiwania.

  • W przypadku uwierzytelniania bez klucza dołącz token Microsoft Entra ID w nagłówku Authorization każdego żądania HTTP.

Konfigurowanie przykładów zestawu SDK

Skonfiguruj środowisko deweloperskie, aby uruchomić przykład.

  1. Ustaw zmienną środowiskową AZURE_SEARCH_ENDPOINT na punkt końcowy usługi Foundry IQ. Przykłady odczytują tę wartość, aby poinformować klienta, z którą usługą Foundry IQ ma nawiązać połączenie.

  2. Zainstaluj Azure CLI i zaloguj się za pomocą az login. DefaultAzureCredential może używać tego zalogowanego konta do uwierzytelniania. Rola Współautor usługi wyszukiwania konta autoryzuje operacje listowania.

Aby uzyskać informacje na temat innych opcji logowania lokalnego, zobacz Uwierzytelnianie na potrzeby programowania lokalnego.

Wybierz operację listy

Interfejs 2026-10-01 API REST obsługuje stronicowanie po stronie serwera dla następujących operacji listy:

Operation Ścieżka zasobu
Lista aliasów /aliases
Lista źródeł danych /datasources
Wyświetl indeksatory /indexers
Wyświetl indeksy /indexes
Pobieranie podsumowania statystyk indeksu /indexstats
Lista baz wiedzy /knowledgebases
Lista źródeł wiedzy /knowledgesources
Lista plików źródeł wiedzy /knowledgesources('{knowledge-source-name}')/files
Lista zestawów umiejętności /skillsets
Wyświetl mapy synonimów /synonymmaps

W przypadku żądań $select REST obsługiwane są źródła danych, indeksatory, zestawy umiejętności, mapy synonimów i przeciążenie listy indeksów zwracające wybrane właściwości. Nie zakładaj, że każda operacja listy ją obsługuje.

Filtruj według prefiksu nazwy

Użyj parametru search , aby zawęzić listę do obiektów, których nazwy zaczynają się od podanego tekstu.

Z wyjątkiem nazw plików nazwy zwracane przez te operacje listowania są zapisane małymi literami. Dopasowanie prefiksu nazwy ignoruje wielkość liter. Interfejs API odrzuca wielkie search wartości jako nieprawidłowe dane wejściowe, a nie konwertuje je na małe litery.

Następujące parametry kontrolują filtr:

Parametr Description
search Prefiks nazwy. Niepusta wartość musi zaczynać się od małej litery (a-z) lub cyfry (0-9) i zawierać tylko małe litery, cyfry, łączniki i podkreślenia. Maksymalna długość to 128 znaków. Nieprawidłowe wartości zwracają http 400. Pominięte lub puste wartości nie zawężają listy.
searchType Jak usługa interpretuje search. prefix jest jedyną obsługiwaną wartością i wartością domyślną. Inne wartości zwracają http 400.

W przypadku listowania plików search odpowiada zwróconej wartości fileName, w tym dowolnej ścieżce względnej, bez względu na wielkość liter. Nazwy plików mogą zawierać wielkie litery. Oddzielny prefix filtr ścieżki uwzględnia wielkość liter.

Wybierz prefiksy dzierżawcy, które się nie pokrywają. Na przykład search=contoso- zwraca contoso-orders i contoso-products, ale wyklucza contoso2-orders. Żądanie z search=toso zwraca pustą tablicę value, ponieważ filtr odpowiada początkowi nazwy.

Przykład kodu

Poniższy kod wyświetla listę indeksów dla jednego dzierżawcy w aplikacji wielodzierżawnej. Każda nazwa indeksu rozpoczyna się od prefiksu dzierżawy, takiego jak contoso- lub contoso2-.

Kod filtruje listę według prefiksu contoso- i żąda maksymalnie 10 indeksów na stronę. W przypadku dzierżawcy z 27 pasującymi indeksami usługa może zwracać strony zawierające po 10, 10 i 7 indeksów.

Pętla rozpoczyna się na początku filtrowanej listy. Aby wznowić, przekaż zapisaną page.ContinuationToken wartość do 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);
    }
}

Reference:SearchIndexClient.GetIndexesAsync, AsPages, ContinuationToken i DefaultAzureCredential

Pętla zewnętrzna wywołuje AsPages() raz, a zestaw SDK pobiera stronę na każdej iteracji, zachowując token kontynuacji dla następnego żądania. Pętla zewnętrzna używa await do oczekiwania na każdą odpowiedź usługi bez blokowania wątku, podczas gdy pętla wewnętrzna odczytuje indeksy w pamięci. Gdy ostatnia strona ma null token kontynuacji, zestaw SDK zgłasza, że nie ma więcej stron i kończy się pętla.

Pętla zewnętrzna iteruje na stronach. Pętla wewnętrzna iteruje indeksy na każdej stronie.

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)

Dokumentacja:SearchIndexClient.list_indexes, ItemPaged.by_page i DefaultAzureCredential

by_page() Tworzy iterator strony raz, a następnie for page in pages żąda każdej strony przy użyciu tokenu kontynuacji przechowywanego w tym iteratorze. Pętla wewnętrzna odczytuje indeksy jednej strony bez innego żądania, podczas gdy pętla zewnętrzna zatrzymuje się, gdy ostatnia strona ma None token kontynuacji. Nowy iterator rozpoczyna się na pierwszej stronie bez tokenu lub None, podczas gdy by_page(continuation_token=token) jest wznawiany z zapisanego tokenu.

Wyślij początkowe żądanie, aby wyświetlić listę indeksów, których nazwy zaczynają się od contoso-. Żądanie zwraca maksymalnie 10 nazw indeksów:

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

Odwołanie:Lista indeksów

Gdy dostępnych jest więcej wyników, odpowiedź zawiera element @odata.nextLink, który zawiera pełny adres URL kontynuacji i nieprzezroczysty token. Strona może zawierać mniej niż 10 wyników i nadal zawierać adres URL kontynuacji. Następująca odpowiedź jest skrócona:

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

Aby zażądać następnej strony, wyślij żądanie GET do pełnej wartości @odata.nextLink, dokładnie w postaci, w jakiej została zwrócona. Wartość search i rozmiar strony są kodowane w tokenie kontynuacji. Zachowaj ten sam nagłówek uwierzytelniania:

GET <[email protected]>
Authorization: Bearer <access-token>
Accept: application/json

Odwołanie:Lista indeksów

Powtórz żądanie z każdą nową @odata.nextLink wartością. Ostatnia strona zawiera pozostałe nazwy indeksów i pomija @odata.nextLink, co oznacza, że nie są dostępne żadne strony:

{
  "value": [
    {
      "name": "<next-index-name>"
    }
  ]
}

Zachowanie stronicowania po stronie serwera

  • Wykryj ostatnią stronę: Kontynuuj stronicowanie, gdy odpowiedź zawiera @odata.nextLink, nawet jeśli strona zawiera mniej wyników niż żądane. Ostatnia strona pomija tę właściwość. Odpowiedzi nie zawierają @odata.count.

  • Zachowaj stan kontynuacji: Użyj kompletnego dokładnie @odata.nextLink tak, jak zostało to zwrócone. Nie konstruuj, nie modyfikuj ani nie dekoduj tokenu kontynuacji (wartość $skiptoken) i nie używaj go z inną operacją listowania. Ten token obsługuje tylko stronicowanie do przodu.

  • Zmień parametry żądania: Uruchom nowe początkowe żądanie, aby zmienić ścieżkę zasobu, wersję interfejsu API, prefiks wyszukiwania, wybrane właściwości lub rozmiar strony. Połączenie $skiptoken z search lub pageSize zwraca http 400.

  • Uwzględnij zmiany w kolekcji: Stronicowanie do przodu jest stabilne tylko wtedy, gdy kolekcja pozostaje niezmieniona. Dodawanie, aktualizowanie lub usuwanie obiektów podczas wyliczania może spowodować wygenerowanie zduplikowanych lub pominiętych wyników.

  • Nie polegaj na kolejności wyników: Usługa nie gwarantuje kolejności wyników.

  • Ustaw rozmiar strony:pageSize Wartość domyślna to 3000 elementów na stronę i ma maksymalną dozwoloną wartość 3000.