Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Note
Foundry IQ (Azure KI-Suche) bietet direkte Indizierungs- und Abfrage-APIs zusammen mit Wissensquellen- und Knowledge Base-APIs auf höherer Ebene für den verwalteten Abruf. Verwenden Sie das Azure Portal, REST-APIs oder Azure SDKs, um diese Funktionen zu konfigurieren, oder verbinden Sie Agents mit Wissensdatenbanken im Microsoft Foundry-Portal.
In diesem Artikel wird erläutert, wie Sie Listenergebnisse nach Namenspräfix filtern und wie das serverseitige Paging funktioniert. Beides wird veranschaulicht, indem die Indizes in einer mehrinstanzenübergreifenden Anwendung aufgelistet werden.
Listenvorgänge in den 2026-10-01 UND 2026-11-01-preview REST-APIs verwenden serverseitige Paging, auch als Cursor paginierung bezeichnet. Dient search zum Filtern einer Liste nach Namenspräfix und pageSize zum Festlegen der Anzahl der gewünschten Ergebnisse auf jeder Seite.
Wenn weitere Ergebnisse verfügbar sind, enthält die Antwort eine Fortsetzungs-URL. Das Fortsetzungstoken in dieser URL teilt dem Dienst mit, wo er fortgesetzt werden soll. Um durch die vollständige Liste zu scrollen, folgen Sie jeder Fortsetzungs-URL, bis sie von einer Antwort weggelassen wird.
Die REST-Beispiele verwenden 2026-10-01. In den Beispielen C# und Python werden SDK-Pakete verwendet 2026-08-01-preview und in der Vorschau angezeigt.
Voraussetzungen
Ein Foundry IQ -Dienst (Azure KI-Suche), der Objekte für einen der unterstützten Listenvorgänge enthält.
Berechtigung zum Auflisten von Objekten im Dienst. Konfigurieren Sie die schlüssellose Authentifizierung mit der Rolle "Mitwirkender des Suchdiensts ", die Ihrem Benutzerkonto zugewiesen ist (empfohlen), oder verwenden Sie einen Administrator-API-Schlüssel.
Das neueste
Azure.Search.DocumentsVorschaupaket:dotnet add package Azure.Search.Documents --prereleaseFür die schlüssellose Authentifizierung das Paket
Azure.Identity:dotnet add package Azure.IdentityNote
Die Clientbibliothek muss die
2026-10-01REST-API2026-08-01-previewdes Suchdiensts oder die Version unterstützen. Versionen vor2026-08-01-previewignorieren die Filter- und Pagingparameter, die in diesem Artikel gezeigt werden.
Das neueste
azure-search-documentsVorschaupaket:pip install --pre azure-search-documentsFür die schlüssellose Authentifizierung das Paket
azure-identity:pip install azure-identityNote
Die Clientbibliothek muss die Version
2026-10-01oder2026-08-01-previewder REST-API des Suchdiensts unterstützen. Versionen vor2026-08-01-previewignorieren die in diesem Artikel gezeigten Filter- und Paginierungsparameter.
Die Version 2026-10-01 der REST-API des Suchdiensts.
Fügen Sie für die schlüssellose Authentifizierung ein Microsoft Entra ID-Token in den
AuthorizationHeader jeder HTTP-Anforderung ein.
Einrichten der SDK-Beispiele
Konfigurieren Sie Ihre Entwicklungsumgebung, um das Beispiel auszuführen.
Legen Sie die
AZURE_SEARCH_ENDPOINTUmgebungsvariable auf Ihren Foundry IQ-Dienstendpunkt fest. In den Beispielen wird dieser Wert gelesen, um dem Client mitzuteilen, mit welchem Foundry IQ-Dienst eine Verbindung hergestellt werden soll.Installieren Sie Azure CLI, und melden Sie sich mit
az login.DefaultAzureCredentialkann dieses angemeldete Konto für die Authentifizierung verwenden. Die Rolle Search Service Contributor des Kontos autorisiert die Listenvorgänge.
Weitere lokale Anmeldeoptionen finden Sie unter Authentifizierung für die lokale Entwicklung.
Auswählen eines Listenvorgangs
Die 2026-10-01 REST-API unterstützt das serverseitige Paging für die folgenden Listenvorgänge:
| Operation | Ressourcenpfad |
|---|---|
| Aliasse auflisten | /aliases |
| Datenquellen auflisten | /datasources |
| Indexer auflisten | /indexers |
| Indizes auflisten | /indexes |
| Zusammenfassung der Indexstatistik abrufen | /indexstats |
| Wissensdatenbanken auflisten | /knowledgebases |
| Wissensquellen auflisten | /knowledgesources |
| Wissensquelldateien auflisten | /knowledgesources('{knowledge-source-name}')/files |
| Skillsets auflisten | /skillsets |
| Synonymzuordnungen auflisten | /synonymmaps |
Für REST-Anfragen wird $select für Datenquellen, Indexer, Skillsets, Synonymzuordnungen und die Indexlistenüberladung unterstützt, die ausgewählte Eigenschaften zurückgibt. Gehen Sie nicht davon aus, dass jeder Listenvorgang sie unterstützt.
Nach Namenspräfix filtern
Verwenden Sie den search Parameter, um eine Liste auf die Objekte einzugrenzen, deren Namen mit dem von Ihnen angegebenen Text beginnen.
Mit Ausnahme von Dateinamen sind die von diesen Listenvorgängen zurückgegebenen Namen Kleinbuchstaben. Der Namenspräfixabgleich ignoriert die Groß-/Kleinschreibung. Die API lehnt Großbuchstaben search als ungültige Eingaben ab, anstatt sie in Kleinbuchstaben zu konvertieren.
Die folgenden Parameter steuern den Filter:
| Parameter | Description |
|---|---|
search |
Ein Namenspräfix. Ein nicht zu verwendender Wert muss mit einem Kleinbuchstaben (a-z) oder einer Ziffer (0-9) beginnen und nur Kleinbuchstaben, Ziffern, Bindestriche und Unterstriche enthalten. Die Höchstlänge beträgt 128 Zeichen. Ungültige Werte geben HTTP 400 zurück. Ausgelassene oder leere Werte schränken die Liste nicht ein. |
searchType |
Wie der Dienst search interpretiert.
prefix ist der einzige unterstützte Wert und der Standardwert. Andere Werte geben HTTP 400 zurück. |
Bei Dateiauflistungen entspricht fileName dem zurückgegebenen search-Wert, einschließlich eines relativen Pfads, ohne Berücksichtigung der Groß-/Kleinschreibung. Dateinamen können Großbuchstaben enthalten. Bei dem separaten prefix Pfadfilter wird die Groß-/Kleinschreibung beachtet.
Wählen Sie Mandantenpräfixe aus, die sich nicht überlappen. Gibt z. B. search=contoso- zurück contoso-orders und contoso-products schließt contoso2-orderssie aus. Eine Anforderung mit search=toso gibt ein leeres value-Array zurück, da der Filter mit dem Anfang des Namens übereinstimmt.
Code-Beispiel
Der folgende Code zeigt die Indizes für einen Mandanten in einer Multitenant-Anwendung an. Jeder Indexname beginnt mit einem Mandantenpräfix, z. B. contoso- oder contoso2-.
Der Code filtert die Liste nach dem contoso- Präfix und fordert bis zu 10 Indizes pro Seite an. Für einen Mandanten mit 27 übereinstimmenden Indizes kann der Dienst Seiten zurückgeben, die 10, 10 und 7 Indizes enthalten.
Die Schleife beginnt am Anfang der gefilterten Liste. Übergeben Sie zum Fortsetzen einen gespeicherten page.ContinuationToken Wert an 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 und DefaultAzureCredential
Die äußere Schleife ruft einmal auf AsPages() und das SDK ruft eine Seite in jeder Iteration ab, wobei das Fortsetzungstoken für die nächste Anforderung beibehalten wird. Die äußere Schleife verwendet await , um auf jede Dienstantwort zu warten, ohne den Thread zu blockieren, während die innere Schleife Indizes im Arbeitsspeicher liest. Wenn die letzte Seite über ein null Fortsetzungstoken verfügt, meldet das SDK, dass keine weiteren Seiten vorhanden sind und die Schleife endet.
Die äußere Schleife durchläuft die Seiten. Die innere Schleife durchläuft die Indizes auf jeder Seite.
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)
Reference:SearchIndexClient.list_indexes, ItemPaged.by_page und DefaultAzureCredential
by_page() erstellt den Seiten iterator einmal, fordert dann for page in pages jede Seite mithilfe des in diesem Iterator gespeicherten Fortsetzungstokens an. Die innere Schleife liest die Indizes einer Seite ohne eine weitere Anfrage, während die äußere Schleife endet, wenn die letzte Seite über kein None Fortsetzungstoken verfügt. Ein neuer Iterator beginnt auf der ersten Seite ohne Token oder None, während by_page(continuation_token=token) mit einem gespeicherten Token fortfährt.
Senden Sie eine anfängliche Anforderung, um die Indizes aufzulisten, deren Namen mit contoso- beginnen. Die Anforderung gibt bis zu 10 Indexnamen zurück:
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
Reference:List Indexes
Wenn weitere Ergebnisse verfügbar sind, enthält die Antwort @odata.nextLink, das die vollständige Fortsetzungs-URL und ein undurchsichtiges Token enthält. Eine Seite kann weniger als 10 Ergebnisse enthalten und dennoch eine Fortsetzungs-URL enthalten. Die folgende Antwort wird abgekürzt:
{
"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>"
}
Um die nächste Seite anzufordern, senden Sie eine GET-Anfrage an den vollständigen Wert @odata.nextLink, genau wie er zurückgegeben wurde. Der search Wert und die Seitengröße werden im Fortsetzungstoken codiert. Behalten Sie denselben Authentifizierungs-Header bei:
GET <[email protected]>
Authorization: Bearer <access-token>
Accept: application/json
Reference:List Indexes
Wiederholen Sie die Anforderung mit jedem neuen @odata.nextLink Wert. Die letzte Seite enthält die verbleibenden Indexnamen und weggelassen @odata.nextLink, was angibt, dass keine weiteren Seiten verfügbar sind:
{
"value": [
{
"name": "<next-index-name>"
}
]
}
Serverseitiges Pagingverhalten
Erkennen der letzten Seite: Setzen Sie die Auslagerung fort, während die Antwort enthält
@odata.nextLink, auch wenn eine Seite weniger Ergebnisse enthält als angefordert. Auf der letzten Seite wird diese Eigenschaft weggelassen. Antworten enthalten@odata.countnicht.Fortsetzungszustand beibehalten: Verwenden Sie den Vollständigen
@odata.nextLinkgenau wie zurückgegeben. Erstellen, ändern oder decodieren Sie das Fortsetzungstoken (den$skiptokenWert) nicht, und verwenden Sie es nicht mit einem anderen Listenvorgang. Das Token unterstützt nur Vorwärtsblättern.Änderung von Anforderungsparametern: Starten Sie eine neue anfängliche Anforderung, um den Ressourcenpfad, die API-Version, das Suchpräfix, die ausgewählten Eigenschaften oder die Seitengröße zu ändern. Die Kombination von
$skiptokenmitsearchoderpageSizegibt HTTP 400 zurück.Konto für Sammlungsänderungen: Die Vorwärts paging ist nur stabil, während die Sammlung unverändert bleibt. Das Hinzufügen, Aktualisieren oder Löschen von Objekten während der Enumeration kann doppelte oder ausgelassene Ergebnisse erzeugen.
Verlassen Sie sich nicht auf die Ergebnisreihenfolge: Der Dienst garantiert nicht die Reihenfolge der Ergebnisse.
Legen Sie die Seitengröße fest:
pageSizehat standardmäßig 3.000 Elemente pro Seite und hat einen maximal zulässigen Wert von 3.000.