Ergebnisse der Listenergebnisse von Foundry IQ (Azure KI-Suche)

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

  • Das neueste Azure.Search.Documents Vorschaupaket: dotnet add package Azure.Search.Documents --prerelease

  • Für die schlüssellose Authentifizierung das Paket Azure.Identity: dotnet add package Azure.Identity

    Note

    Die Clientbibliothek muss die 2026-10-01 REST-API 2026-08-01-preview des Suchdiensts oder die Version unterstützen. Versionen vor 2026-08-01-preview ignorieren die Filter- und Pagingparameter, die in diesem Artikel gezeigt werden.

  • Das neueste azure-search-documents Vorschaupaket: pip install --pre azure-search-documents

  • Für die schlüssellose Authentifizierung das Paket azure-identity: pip install azure-identity

    Note

    Die Clientbibliothek muss die Version 2026-10-01 oder 2026-08-01-preview der REST-API des Suchdiensts unterstützen. Versionen vor 2026-08-01-preview ignorieren die in diesem Artikel gezeigten Filter- und Paginierungsparameter.

Einrichten der SDK-Beispiele

Konfigurieren Sie Ihre Entwicklungsumgebung, um das Beispiel auszuführen.

  1. Legen Sie die AZURE_SEARCH_ENDPOINT Umgebungsvariable 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.

  2. Installieren Sie Azure CLI, und melden Sie sich mit az login. DefaultAzureCredential kann 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.count nicht.

  • Fortsetzungszustand beibehalten: Verwenden Sie den Vollständigen @odata.nextLink genau wie zurückgegeben. Erstellen, ändern oder decodieren Sie das Fortsetzungstoken (den $skiptoken Wert) 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 $skiptoken mit search oder pageSize gibt 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:pageSize hat standardmäßig 3.000 Elemente pro Seite und hat einen maximal zulässigen Wert von 3.000.