Azure KI-Suche Client-Bibliothek für JavaScript – Version 13.1.0

Azure KI-Suche (früher bekannt als "Azure Cognitive Search") ist eine KI-gestützte Informationssuchplattform, die Entwicklern hilft, reichhaltige Sucherlebnisse und generative KI-Apps zu erstellen, die große Sprachmodelle mit Unternehmensdaten kombinieren.

Der Azure KI-Suche-Dienst eignet sich gut für die folgenden Anwendungsszenarien:

  • Konsolidieren Sie verschiedene Inhaltstypen in einem einzigen durchsuchbaren Index. Zum Auffüllen eines Indexes können Sie JSON-Dokumente, die Ihre Inhalte enthalten, pushen, oder wenn Ihre Daten bereits in Azure vorhanden sind, einen Index erstellen, um Daten automatisch abzurufen.
  • Fügen Sie Skillsets an einen Indexer an, um durchsuchbare Inhalte aus Bildern und unstrukturierten Dokumenten zu erstellen. Ein Skillset nutzt APIs von Azure AI Services für integrierte OCR,Entitätserkennung, Schlüsselausdruckextraktion, Spracherkennung, Textübersetzung und Stimmungsanalyse. Sie können auch benutzerdefinierte Fähigkeiten hinzufügen, um die externe Verarbeitung Ihrer Inhalte während der Datenaufnahme zu integrieren.
  • Implementieren Sie in einer Suchclientanwendung Abfragelogik und Benutzeroberflächen ähnlich wie kommerzielle Websuchmaschinen und Chat-Apps.

Verwenden Sie die @azure/search-documents Clientbibliothek für folgende Zwecke:

  • Übermitteln von Abfragen mithilfe von Vektor-, Schlüsselwort- und Hybridabfrageformularen.
  • Implementieren Sie gefilterte Abfragen für Metadaten, geospatiale Suche, faceted Navigation oder einschränken Sie Ergebnisse basierend auf Filterkriterien.
  • Erstellen und Verwalten von Suchindizes.
  • Laden Sie Dokumente im Suchindex hoch und aktualisieren Sie sie.
  • Erstellen und verwalten Sie Indexer, die Daten aus Azure in einen Index abrufen.
  • Erstellen und verwalten Sie Skillsets, die KI-Anreicherung zur Datenaufnahme hinzufügen.
  • Erstellen und Verwalten von Analyzern für erweiterte Textanalyse oder mehrsprachige Inhalte.
  • Optimieren Sie Ergebnisse durch semantische Bewertungs- und Bewertungsprofile, um die Geschäftslogik oder Aktualität zu berücksichtigen.

Wichtige Links:

Erste Schritte

Installieren Sie das @azure/search-documents-Paket

npm install @azure/search-documents

Version 13.1.0 zielt standardmäßig auf die 2026-10-01 GA-Service-API ab. Überprüfen Sie beim Upgrade von Version 13.0.0 die fehlerhaften Änderungen von GA-to-GA. Aktualisierte TypeScript- und JavaScript-Beispiele sind in Beispielen/v13 verfügbar.

Derzeit unterstützte Umgebungen

Ausführlichere Informationen finden Sie in der Supportrichtlinie.

Voraussetzungen

Um einen neuen Suchdienst zu erstellen, können Sie das Azure-Portal, Azure PowerShell oder die Azure CLI verwenden. Im Folgenden finden Sie ein Beispiel für die Verwendung der Azure CLI zum Erstellen einer kostenlosen Instanz für die ersten Schritte:

az search service create --name <mysearch> --resource-group <mysearch-rg> --sku free --location westus

Weitere Informationen zu den verfügbaren Optionen finden Sie unter Auswählen eines Tarifs .

Authentifizieren des Clients

Um mit dem Suchdienst zu interagieren, erstellen Sie den passenden Client: SearchClient für Dokumente, SearchIndexClient für Indizes und Wissensressourcen, SearchIndexerClient für Datenquellen/Indexer/Skillsets oder KnowledgeRetrievalClient für die Abruf von Wissensdatenbanken. Zum Instanziieren eines Clientobjekts benötigen Sie einen Endpunkt und Azure-Rollen oder einen API-Schlüssel. Weitere Informationen zu unterstützten Authentifizierungsansätzen mit dem Suchdienst finden Sie in der Dokumentation.

Abrufen eines API-Schlüssels

Ein API-Schlüssel kann ein einfacherer Ansatz sein, um damit zu beginnen, da es keine bereits vorhandenen Rollenzuweisungen erfordert.

Sie können den Endpunkt und einen API-Schlüssel über den Suchdienst im Azure-Portal abrufen. In der Dokumentation finden Sie Anweisungen, wie Sie einen API-Schlüssel erhalten.

Alternativ können Sie den folgenden Azure CLI-Befehl verwenden, um den API-Schlüssel aus dem Suchdienst abzurufen:

az search admin-key show --resource-group <your-resource-group-name> --service-name <your-resource-name>

Es gibt zwei Arten von Schlüsseln, die für den Zugriff auf Ihren Suchdienst verwendet werden: admin-Schlüssel (Lese-/Schreibzugriff) und Abfrageschlüssel(schreibgeschützt). Das Einschränken des Zugriffs und der Vorgänge in Client-Apps ist unerlässlich, um die Suchressourcen in Ihrem Dienst zu schützen. Verwenden Sie immer einen Abfrageschlüssel anstelle eines Administratorschlüssels für jede Abfrage, die von einer Client-App stammt.

Hinweis: Der Beispiel-Azure CLI-Ausschnitt oben ruft einen Admin-Schlüssel ab, sodass es einfacher ist, mit der API-Erkundung zu beginnen, aber er sollte sorgfältig verwaltet werden.

Sobald Sie über einen API-Schlüssel verfügen, können Sie ihn wie folgt verwenden:

import {
  SearchClient,
  AzureKeyCredential,
  SearchIndexClient,
  SearchIndexerClient,
  KnowledgeRetrievalClient,
} from "@azure/search-documents";

// To query and manipulate documents
const searchClient = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>"),
);

// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"));

// To manage indexers, datasources and skillsets
const indexerClient = new SearchIndexerClient("<endpoint>", new AzureKeyCredential("<apiKey>"));

// To retrieve from a knowledge base
const knowledgeRetrievalClient = new KnowledgeRetrievalClient(
  "<endpoint>",
  "<knowledgeBaseName>",
  new AzureKeyCredential("<apiKey>"),
);

Authentifizieren in einer nationalen Cloud

Um sich in einer National Cloud zu authentifizieren, müssen Sie die folgenden Ergänzungen zu Ihrer Clientkonfiguration vornehmen:

  • Legen Sie die Audience in SearchClientOptions
import { DefaultAzureCredential } from "@azure/identity";
import {
  SearchClient,
  KnownSearchAudience,
  SearchIndexClient,
  SearchIndexerClient,
  KnowledgeRetrievalClient,
} from "@azure/search-documents";

const credential = new DefaultAzureCredential({
  authorityHost: "https://login.chinacloudapi.cn",
});

// To query and manipulate documents
const searchClient = new SearchClient("<endpoint>", "<indexName>", credential, {
  audience: KnownSearchAudience.AzureChina,
});

// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient("<endpoint>", credential, {
  audience: KnownSearchAudience.AzureChina,
});

// To manage indexers, datasources and skillsets
const indexerClient = new SearchIndexerClient("<endpoint>", credential, {
  audience: KnownSearchAudience.AzureChina,
});

// To retrieve from a knowledge base
const knowledgeRetrievalClient = new KnowledgeRetrievalClient(
  "<endpoint>",
  "<knowledgeBaseName>",
  credential,
  { audience: KnownSearchAudience.AzureChina },
);

Schlüsselkonzepte

Ein Azure KI-Suche-Dienst enthält einen oder mehrere Indizes, die beständigen Speicher durchsuchbarer Daten in Form von JSON-Dokumenten bereitstellen. (Wenn Sie ganz neu in der Suche sind, können Sie eine sehr grobe Analogie zwischen Indizes und Datenbanktabellen ziehen.) Die @azure/search-documents Client-Bibliothek stellt Operationen auf diesen Ressourcen durch vier Hauptclienttypen offen.

Hinweis: Die Nutzung des Browsers hängt davon ab, ob die ausgewählte Suchoperation und die Ressource CORS konfiguriert haben. Datei-Wissensquellen und Wissensbasen stellen CORS-Einstellungen offen, aber viele Verwaltungsoperationen sind für vertrauenswürdige serverseitige Anwendungen gedacht.

TypeScript/JavaScript-spezifische Konzepte

Urkunden

Ein Element, das in einem Suchindex gespeichert ist. Die Form dieses Dokuments wird im Index mit der Eigenschaft beschrieben fields . Jeder SearchField verfügt über einen Namen, einen Datentyp und zusätzliche Metadaten, z. B. ob er durchsuchbar oder filterbar ist.

Paginierung

In der Regel möchten Sie einem Benutzer jeweils nur eine Teilmenge der Suchergebnisse anzeigen . Um dies zu unterstützen, können Sie die topParameter und skip verwenden, includeTotalCount um eine ausgelagerte Benutzeroberfläche über den Suchergebnissen bereitzustellen.

Dokumentfeldcodierung

Unterstützte Datentypen in einem Index werden in API-Anfragen/-Antworten JSON-Typen zugeordnet. Die JS-Clientbibliothek hält diese meist gleich, mit einigen Ausnahmen:

  • Edm.DateTimeOffset wird in ein JS Dateumgewandelt.
  • Edm.GeographyPoint wird in einen GeographyPoint von der Clientbibliothek exportierten Typ konvertiert.
  • Spezielle Werte des number Typs (NaN, Infinity -Infinity) werden in der REST-API als Zeichenfolgen serialisiert, aber von der Clientbibliothek wieder number konvertiert.

Hinweis: Datentypen werden basierend auf dem Wert konvertiert, nicht nach dem Feldtyp im Indexschema. Dies bedeutet: Wenn Sie über eine ISO8601 Datumszeichenfolge (z. B. "2020-03-06T18:48:27.896Z") als Wert eines Felds verfügen, wird sie unabhängig davon, wie Sie es in Ihrem Schema gespeichert haben, in ein Datum konvertiert.

Beispiele

Die folgenden Beispiele zeigen die Grundlagen - schauen Sie sich unsere Beispiele an, um mehr zu erfahren.

Die untenstehenden Beispiele verwenden die stabile 2026-10-01 Service-API, die die Standardeinstellung des Clients ist. Sie erweitern die bestehenden Workflows für Index, Indexer, Wissensquelle und Abrufe, anstatt eine separate Gruppe von Clients zu benötigen.

Für vollständige lauffähige Workflows umfassen die Beispielquellen außerdem indexierte SQL-Inhaltsspalten, private Ingestion- und service-selected Analyzer, Content Understanding Bildbeschreibungsmodelle und semantische Chunking, Service-/Indexer-Laufzeitbudgets sowie sucheigene Zitations-URLs. Die optionalen Ressourceneinstellungen und Voraussetzungen sind in sample.env aufgeführt.

Ähnliche Dokumente finden

Verwenden Sie moreLikeThis mit einem vorhandenen Dokumentschlüssel und lassen Sie Suchtext weg. Wählen Sie durchsuchbare Textfelder auf oberster Ebene explizit aus: Komplexe Felder werden von dieser Operation nicht unterstützt. Der Index muss weitere Dokumente enthalten, um nützliche Übereinstimmungen zu liefern.

import { SearchClient } from "@azure/search-documents";
import { DefaultAzureCredential } from "@azure/identity";

const client = new SearchClient("<endpoint>", "<indexName>", new DefaultAzureCredential());

const response = await client.search(undefined, {
  moreLikeThis: "1",
  searchFields: ["hotelName", "description"],
  select: ["hotelId", "hotelName"],
  top: 5,
});
for await (const result of response.results) {
  console.log(result.document);
}

Eine Wissensdatenbank konfigurieren

Verwenden Sie eine gefüllte Wissensquelle mit konfigurierter semantischer Suche. Stellen Sie das konfigurierte Chatmodell bereit und geben Sie der verwalteten Identität des Suchdienstes Cognitive Services OpenAI User auf der Azure OpenAI-Ressource. Der Bereitstellungsname und der Modellname sind getrennte Einstellungen; eine Bereitstellung kann einen benutzerdefinierten Namen haben. Der Anrufer benötigt Search Service Contributor , um Wissensdatenbanken zu verwalten.

Speicheranweisungen, Ausgabemodus und Denkanstrengungen können aktualisiert werden, ohne die Wissensquellen zu ersetzen. answerSynthesis verwendet das konfigurierte Modell; extractiveData gibt extrahierten Inhalt zurück, ohne eine Antwort zu synthetisieren. GA-Denkmodi sind minimal, low, und medium. Explizite Anfrageabsichten umgehen die Planung von Modellabfragen.

import { SearchIndexClient } from "@azure/search-documents";
import { DefaultAzureCredential } from "@azure/identity";

const client = new SearchIndexClient("<endpoint>", new DefaultAzureCredential());

const knowledgeBase = await client.createKnowledgeBase({
  name: "hotel-knowledge-base",
  knowledgeSources: [{ name: "<existingKnowledgeSourceName>" }],
  models: [
    {
      kind: "azureOpenAI",
      azureOpenAIParameters: {
        resourceUrl: "<azureOpenAIEndpoint>",
        deploymentId: "<chatDeploymentName>",
        modelName: "gpt-5.4-mini",
      },
    },
  ],
  retrievalReasoningEffort: { kind: "low" },
  outputMode: "answerSynthesis",
  retrievalInstructions: "Prioritize hotel amenities and pricing information.",
  answerInstructions: "Answer concisely and cite the supporting sources.",
});

knowledgeBase.outputMode = "extractiveData";
await client.createOrUpdateKnowledgeBase(knowledgeBase);

Ressourcen mit Paging-Steuerungen auflisten

Filtern Sie die ursprüngliche Listung nach dem Namenspräfix und lassen Sie das SDK undurchsichtigen Fortsetzungslinks folgen. Die Pager SearchIndexClient zeigen byPage(). Die bestehenden Methoden zur Synonym-Map-, Indexer-, Datenquellen- und Fähigkeitsauflistung geben nach dem Sammeln aller Seiten weiterhin Arrays zurück; Protokollclients stellen die entsprechenden gepageten Operationen offen.

import { SearchIndexClient } from "@azure/search-documents";
import { DefaultAzureCredential } from "@azure/identity";

const client = new SearchIndexClient("<endpoint>", new DefaultAzureCredential());

for await (const page of client
  .listIndexes({
    search: "hotel",
    searchType: "prefix",
    pageSize: 10,
  })
  .byPage()) {
  console.log(page.map((index) => index.name));
}

SharePoint-Dokumentberechtigungen konfigurieren

Registrieren Sie die SharePoint-Connector-Anwendung und deren föderierte Anmeldedaten, bevor Sie den Index erstellen. applicationId federatedCredentialId und sind gemeinsam erforderlich; können bereitgestellt werden, tenantId wenn sie sich vom Suchdienst-Tenant unterscheiden. Der Anrufer benötigt Search Service Contributor.

Eine organisationsbezogene Freigabegewährung verwendet orgLink:<tenantId> im userIds Berechtigungsfeld. organizationAccessExpiration Identifiziert seinen Ablaufzeitstempel. Höchstens ein oberes Edm.DateTimeOffset Feld kann dies ermöglichen. Der Dienst validiert den Tenant und den Zeitstempel des Benutzers während berechtigungsgefilterten Abfragen; das allein deklarieren dieser Felder gewährt keinen Zugriff.

import { SearchIndexClient } from "@azure/search-documents";
import { DefaultAzureCredential } from "@azure/identity";

const client = new SearchIndexClient("<endpoint>", new DefaultAzureCredential());

await client.createIndex({
  name: "sharepoint-permissions",
  permissionFilterOption: "enabled",
  sharePointConnectorAppRegistration: {
    applicationId: "<applicationId>",
    federatedCredentialId: "<federatedCredentialId>",
  },
  fields: [
    { name: "id", type: "Edm.String", key: true },
    { name: "content", type: "Edm.String", searchable: true },
    {
      name: "userIds",
      type: "Collection(Edm.String)",
      filterable: true,
      permissionFilter: "userIds",
    },
    {
      name: "organizationLinkExpiresAt",
      type: "Edm.DateTimeOffset",
      organizationAccessExpiration: true,
    },
  ],
});

SharePoint-Websiteinhalte indexieren

Die GA SharePoint-Bereiche umfassen AllSiteLists, AllSitePages, und AllSiteContent, zusätzlich zu den bestehenden Bibliotheksbereichen. Geben Sie die Connector-Verbindungszeichenfolge über die Umgebung weiter, anstatt ein Anwendungsgeheimnis im Quellcode einzubetten.

import { SearchIndexClient, KnownIndexedSharePointContainerName } from "@azure/search-documents";
import { DefaultAzureCredential } from "@azure/identity";

const client = new SearchIndexClient("<endpoint>", new DefaultAzureCredential());
const connectionString = process.env.SHAREPOINT_CONNECTION_STRING;
if (!connectionString) {
  throw new Error("Set SHAREPOINT_CONNECTION_STRING before creating the knowledge source.");
}

await client.createKnowledgeSource({
  name: "sharepoint-site",
  kind: "indexedSharePoint",
  indexedSharePointParameters: {
    connectionString,
    containerName: KnownIndexedSharePointContainerName.AllSiteContent,
  },
});

Unveränderte ADLS Gen2-Berechtigungen aktualisieren

Für einen bestehenden ADLS Gen2-Indexer, der Berechtigungen einnimmt, aktualisiert er Berechtigungsmetadaten, refreshAllAcls selbst wenn sich der Inhalt des Dokuments nicht geändert hat. Standardmäßig läuft truees auf , läuft höchstens einmal alle 24 Stunden und verarbeitet weder Inhalte noch Bereicherung neu. Stellen Sie es ein, false um die Aktualisierung zu deaktivieren.

import { SearchIndexerClient } from "@azure/search-documents";
import { DefaultAzureCredential } from "@azure/identity";

const client = new SearchIndexerClient("<endpoint>", new DefaultAzureCredential());
const indexer = await client.getIndexer("<existingAdlsGen2Indexer>");

indexer.parameters = {
  ...indexer.parameters,
  configuration: {
    ...indexer.parameters?.configuration,
    refreshAllAcls: true,
  },
};
await client.createOrUpdateIndexer(indexer);

Abruf aus einer Wissensdatenbank

import {
  KnowledgeRetrievalClient,
  AzureKeyCredential,
  KnownKnowledgeRetrievalReasoningEffortKind,
} from "@azure/search-documents";

const client = new KnowledgeRetrievalClient(
  "<endpoint>",
  "<knowledgeBaseName>",
  new AzureKeyCredential("<apiKey>"),
);

const response = await client.retrieve({
  intents: [{ type: "semantic", search: "What information is available?" }],
  retrievalReasoningEffort: { kind: KnownKnowledgeRetrievalReasoningEffortKind.Low },
  includeActivity: true,
});

console.log(response.response);

Wissensabruf im Fluss

Der typisierte Iterator verwendet eine SSE-Verbindung, übernimmt Framing und Herzschläge und hört nach response.completed oder errorauf. Die Fertigstellung kann vollständige (200) oder teilweise (206) Ergebnisse anzeigen. Rufen Sie an, controller.abort() um die Anfrage zu stornieren. Unbekannte Ereignisnamen werden ignoriert; Token-Delta-Ereignisse sind nicht Teil dieser API. Siehe das Streaming-Beispiel für die Behandlung von Aktivitätskorrelation und Abbruch.

import { KnowledgeRetrievalClient, AzureKeyCredential } from "@azure/search-documents";

const client = new KnowledgeRetrievalClient(
  "<endpoint>",
  "<knowledgeBaseName>",
  new AzureKeyCredential("<apiKey>"),
);

const controller = new AbortController();
for await (const event of await client.retrieveStream(
  {
    intents: [{ type: "semantic", search: "Summarize the indexed information." }],
    includeActivity: true,
  },
  { abortSignal: controller.signal },
)) {
  if (event.event === "activity.completed") {
    console.log(`Activity ${event.data.id} took ${event.data.elapsedInMs}ms`);
  } else if (event.event === "response.completed") {
    console.log(event.data.statusCode === 206 ? "Partial results" : "Complete results");
    console.log(event.data.response.response);
  } else if (event.event === "error") {
    throw new Error(event.data.error.message);
  }
}

Laden Sie eine Wissensquellendatei hoch und aktualisieren Sie sie

import { SearchIndexClient, AzureKeyCredential } from "@azure/search-documents";

const client = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"));
const body = {
  metadata: { fileName: "manuals/example.txt", metadata: { category: "manual" } },
  content: {
    contents: new TextEncoder().encode("Azure AI Search retrieves relevant information."),
    contentType: "text/plain",
    filename: "example.txt",
  },
};

const uploaded = await client.uploadKnowledgeSourceFileMultipart("<knowledgeSourceName>", body);
if (!uploaded.fileId) {
  throw new Error("The service did not return an uploaded file ID.");
}

await client.updateKnowledgeSourceFile("<knowledgeSourceName>", uploaded.fileId, {
  ...body,
  metadata: { ...body.metadata, metadata: { category: "updated-manual" } },
});
for await (const file of client.listKnowledgeSourceFiles("<knowledgeSourceName>", {
  prefix: "manuals/",
  pageSize: 10,
})) {
  console.log(file.fileName, file.parsingMode, file.extractionMode);
}

Prüfen Sie die Kapazität der Dateiwissensquellen

Der Status einer Dateiwissensquelle zeigt fileCapacity (KnowledgeSourceFileCapacity) die verbleibende Dateianzahl und das Byteselimit pro Datei. Überprüfen Sie es vor dem Hochladen; andere Arten von Wissensquellen melden dieses Feld nicht. Direkte Uploads benötigen Search Service Contributor, und die verwaltete Identität des Suchdienstes benötigt den Cognitive Services OpenAI User auf der Embedding-Ressource.

import { SearchIndexClient } from "@azure/search-documents";
import { DefaultAzureCredential } from "@azure/identity";

const client = new SearchIndexClient("<endpoint>", new DefaultAzureCredential());
const status = await client.getKnowledgeSourceStatus("<fileKnowledgeSourceName>");

if (!status.fileCapacity) {
  throw new Error("The knowledge source did not report File upload capacity.");
}
console.log(`Remaining files: ${status.fileCapacity.remainingFileCount}`);
console.log(`Maximum file size: ${status.fileCapacity.maxFileSizeBytes} bytes`);

Erstellen eines Indexes

import { SearchIndexClient, AzureKeyCredential } from "@azure/search-documents";

const indexClient = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"));

const result = await indexClient.createIndex({
  name: "example-index",
  fields: [
    {
      type: "Edm.String",
      name: "id",
      key: true,
    },
    {
      type: "Edm.Double",
      name: "awesomenessLevel",
      sortable: true,
      filterable: true,
      facetable: true,
    },
    {
      type: "Edm.String",
      name: "description",
      searchable: true,
    },
    {
      type: "Edm.ComplexType",
      name: "details",
      fields: [
        {
          type: "Collection(Edm.String)",
          name: "tags",
          searchable: true,
        },
      ],
    },
    {
      type: "Edm.Int32",
      name: "hiddenWeight",
      hidden: true,
    },
  ],
});

console.log(`Index created with name ${result.name}`);

Abrufen eines bestimmten Dokuments aus einem Index

Ein bestimmtes Dokument kann anhand seines Primärschlüsselwerts abgerufen werden:

import { SearchClient, AzureKeyCredential } from "@azure/search-documents";

const searchClient = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>"),
);

const result = await searchClient.getDocument("1234");

Hinzufügen von Dokumenten zu einem Index

Sie können mehrere Dokumente in einen Index in einem Batch hochladen:

import { SearchClient, AzureKeyCredential } from "@azure/search-documents";

const searchClient = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>"),
);

const uploadResult = await searchClient.uploadDocuments([
  // JSON objects matching the shape of the client's index
  {},
  {},
  {},
]);
for (const result of uploadResult.results) {
  console.log(`Uploaded ${result.key}; succeeded? ${result.succeeded}`);
}

Durchführen einer Suche nach Dokumenten

Um alle Ergebnisse einer bestimmten Abfrage aufzulisten, können Sie eine Suchzeichenfolge verwenden search , die eine einfache Abfragesyntax verwendet:

import { SearchClient, AzureKeyCredential } from "@azure/search-documents";

const searchClient = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>"),
);

const searchResults = await searchClient.search("wifi -luxury");
for await (const result of searchResults.results) {
  console.log(result);
}

Für eine erweiterte Suche, die die Lucene-Syntax verwendet, geben Sie Folgendes anqueryType:full

import { SearchClient, AzureKeyCredential } from "@azure/search-documents";

const searchClient = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>"),
);

const searchResults = await searchClient.search('Category:budget AND "recently renovated"^3', {
  queryType: "full",
  searchMode: "all",
});
for await (const result of searchResults.results) {
  console.log(result);
}

Abfragen mit TypeScript

In TypeScript wird ein generischer Parameter verwendet, SearchClient der die Modellform Ihrer Indexdokumente darstellt. Auf diese Weise können Sie stark typierte Nachschlagevorgänge von Feldern ausführen, die in Ergebnissen zurückgegeben werden. TypeScript ist auch in der Lage, nach Feldern zu suchen, die beim Angeben eines select Parameters zurückgegeben werden.

import { SearchClient, AzureKeyCredential, SelectFields } from "@azure/search-documents";

// An example schema for documents in the index
interface Hotel {
  hotelId?: string;
  hotelName?: string | null;
  description?: string | null;
  descriptionVector?: Array<number>;
  parkingIncluded?: boolean | null;
  lastRenovationDate?: Date | null;
  rating?: number | null;
  rooms?: Array<{
    beds?: number | null;
    description?: string | null;
  }>;
}

const searchClient = new SearchClient<Hotel>(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>"),
);

const searchResults = await searchClient.search("wifi -luxury", {
  // Only fields in Hotel can be added to this array.
  // TS will complain if one is misspelled.
  select: ["hotelId", "hotelName", "rooms/beds"],
});

// These are other ways to declare the correct type for `select`.
const select = ["hotelId", "hotelName", "rooms/beds"] as const;
// This declaration lets you opt out of narrowing the TypeScript type of your documents,
// though the AI Search service will still only return these fields.
const selectWide: SelectFields<Hotel>[] = ["hotelId", "hotelName", "rooms/beds"];
// This is an invalid declaration. Passing this to `select` will result in a compiler error
// unless you opt out of including the model in the client constructor.
const selectInvalid = ["hotelId", "hotelName", "rooms/beds"];

for await (const result of searchResults.results) {
  // result.document has hotelId, hotelName, and rooms with only the beds property.
  // Trying to access result.document.description would emit a TS error.
  console.log(result.document.hotelName);
}

Abfragen mit OData-Filtern

Mit dem filter query-Parameter können Sie einen Index mit der Syntax eines OData-$filter-Ausdrucks abfragen.

import { SearchClient, AzureKeyCredential, odata } from "@azure/search-documents";

const searchClient = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>"),
);

const baseRateMax = 200;
const ratingMin = 4;
const searchResults = await searchClient.search("WiFi", {
  filter: odata`Rooms/any(room: room/BaseRate lt ${baseRateMax}) and Rating ge ${ratingMin}`,
  orderBy: ["Rating desc"],
  select: ["hotelId", "hotelName", "Rating"],
});
for await (const result of searchResults.results) {
  // Each result will have "HotelId", "HotelName", and "Rating"
  // in addition to the standard search result property "score"
  console.log(result);
}

Abfragen mit Vektoren

Texteinbettungen können über den vector Suchparameter abgefragt werden. Weitere Informationen finden Sie unter Abfragevektoren und Filtern von Vektorabfragen .

import { SearchClient, AzureKeyCredential } from "@azure/search-documents";

const searchClient = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>"),
);

const queryVector: number[] = [
  // Embedding of the query "What are the most luxurious hotels?"
];
const searchResults = await searchClient.search("*", {
  vectorSearchOptions: {
    queries: [
      {
        kind: "vector",
        vector: queryVector,
        fields: ["descriptionVector"],
        kNearestNeighborsCount: 3,
      },
    ],
  },
});
for await (const result of searchResults.results) {
  // These results are the nearest neighbors to the query vector
  console.log(result);
}

Abfragen mit Facets

Facetten werden verwendet, um einem Benutzer Ihrer Anwendung zu helfen, eine Suche nach vorkonfigurierten Dimensionen zu verfeinern. Die Facettensyntax bietet die Optionen, Facetwerte zu sortieren und einzuordnen.

import { SearchClient, AzureKeyCredential } from "@azure/search-documents";

const searchClient = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>"),
);

const searchResults = await searchClient.search("WiFi", {
  facets: ["category,count:3,sort:count", "rooms/baseRate,interval:100"],
});
console.log(searchResults.facets);

Beim Abrufen von Ergebnissen ist eine facets Eigenschaft verfügbar, die die Anzahl der Ergebnisse angibt, die in die einzelnen Facetten-Buckets fallen. Dies kann verwendet werden, um die Verfeinerung voranzutreiben (z. B. indem eine Folgesuche durchgeführt wird, die danach filtert, ob sie Rating größer oder gleich 3 und kleiner als 4 ist).

Fehlerbehebung

Protokollierung

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in den @azure/Logger-Paketdokumenten.

Nächste Schritte

Beitragend

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den Beitragsleitfaden , um mehr über das Erstellen und Testen des Codes zu erfahren.

Dieses Projekt begrüßt Beiträge und Vorschläge. Die meisten Beiträge erfordern, dass Sie einem Mitwirkenden-Lizenzvertrag (CLA) zustimmen, der erklärt, dass Sie das Recht haben, uns tatsächlich die Rechte zur Nutzung Ihres Beitrags zu gewähren. Weitere Informationen finden Sie unter cla.microsoft.com.

Dieses Projekt hat den Microsoft Open Source Code of Conductübernommen. Weitere Informationen finden Sie im Code of Conduct FAQ oder wenden Sie sich an [email protected] mit weiteren Fragen oder Kommentaren.