Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
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
Usługa Foundry IQ (Wyszukiwanie AI platformy Azure), która zawiera obiekty dla jednej z obsługiwanych operacji listy.
Uprawnienie do wylistowania obiektów w usłudze. Skonfiguruj uwierzytelnianie bez klucza przy użyciu roli Współautor usługi wyszukiwania przypisanej do konta użytkownika (zalecane) lub użyj klucza interfejsu API administratora.
Najnowszy pakiet
Azure.Search.Documentswersji zapoznawczej:dotnet add package Azure.Search.Documents --prereleaseW przypadku uwierzytelniania bezkluczowego pakiet
Azure.Identity:dotnet add package Azure.IdentityNote
Biblioteka klienta musi obsługiwać wersję
2026-10-01lub2026-08-01-previewinterfejsu API REST usługi wyszukiwania. Wersje wcześniejsze niż2026-08-01-previewignorują parametry filtru i stronicowania pokazane w tym artykule.
Najnowszy pakiet
azure-search-documentswersji zapoznawczej:pip install --pre azure-search-documentsW przypadku uwierzytelniania bezkluczowego pakiet
azure-identity:pip install azure-identityNote
Biblioteka klienta musi obsługiwać wersję
2026-10-01lub2026-08-01-previewinterfejsu API REST usługi wyszukiwania. Wersje wcześniejsze niż2026-08-01-previewignorują 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
Authorizationkażdego żądania HTTP.
Konfigurowanie przykładów zestawu SDK
Skonfiguruj środowisko deweloperskie, aby uruchomić przykład.
Ustaw zmienną środowiskową
AZURE_SEARCH_ENDPOINTna 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.Zainstaluj Azure CLI i zaloguj się za pomocą
az login.DefaultAzureCredentialmoż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.nextLinktak, 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
$skiptokenzsearchlubpageSizezwraca 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:
pageSizeWartość domyślna to 3000 elementów na stronę i ma maksymalną dozwoloną wartość 3000.