Indizieren von JSON-Blobs und -Dateien in Azure KI Search
Gilt für: Blobindexer, Dateiindexer
In diesem Artikel erfahren Sie, wie Sie Eigenschaften für Blobs oder Dateien festlegen, die aus JSON-Dokumenten bestehen. JSON-Dateien in Azure Blob Storage oder Azure Files haben üblicherweise eine der folgenden Formen:
- Einzelnes JSON-Dokument
- JSON-Dokument mit einem Array von wohlgeformten JSON-Elementen
- JSON-Dokument mit mehreren Entitäten, die durch einen Zeilenvorschub getrennt sind
Der Blobindexer enthält einen parsingMode-Parameter, um die Ausgabe des Suchdokuments basierend auf der JSON-Struktur zu optimieren. Die Analysemodi umfassen die folgenden Optionen:
| parsingMode | JSON-Dokument | Beschreibung |
|---|---|---|
json |
Ein Dokument pro Blob | (Standard) JSON-Blobs werden als einzelne Textblöcke analysiert. Jedes JSON-Blob wird zu einem einzelnen Suchdokument. |
jsonArray |
Mehrere Dokumente pro Blob | Analysiert ein JSON-Array im Blob. Jedes Element des Arrays wird zu einem separaten Suchdokument. |
jsonLines |
Mehrere Dokumente pro Blob | Analysiert ein Blob, das mehrere JSON-Entitäten (auch ein Array) enthält, wobei die einzelnen Entitäten durch einen Zeilenvorschub getrennt sind. Der Indexer startet nach jeder neuen Zeile ein neues Suchdokument. |
Für jsonArray und jsonLines finden Sie unter Indizieren von Blobs zum Generieren mehrerer Suchdokumente Informationen dazu, wie mit dem Blobindexer die Eindeutigkeit des Dokumentschlüssels für mehrere Suchdokumente gehandhabt wird, die aus dem gleichen Blob generiert wurden.
Innerhalb der Indexerdefinition können Sie optional Feldzuordnungen festlegen, um auszuwählen, welche Eigenschaften des JSON-Quelldokuments zum Auffüllen des Zielsuchindex verwendet werden sollen. Wenn bei Verwendung des jsonArray-Analysemodus das Array beispielsweise als Eigenschaft auf niedrigerer Ebene vorhanden ist, können Sie eine documentRoot-Eigenschaft festlegen, mit der angegeben wird, wo das Array im Blob angeordnet ist.
Hinweis
Wenn ein JSON-Analysemodus verwendet wird, geht Azure KI-Suche davon aus, dass alle Blobs denselben Parser verwenden (entweder für json, jsonArray oder jsonLines). Wenn Sie die Datenquelle verschiedene Dateitypen enthält, sollten Sie Dateierweiterungsfilter verwenden, um festzulegen, welche Dateien importiert werden.
In den folgenden Abschnitten werden die einzelnen Modi ausführlicher beschrieben. Wenn Sie mit Indexerclients und -konzepten nicht vertraut sind, finden Sie entsprechende Informationen unter Erstellen eines Suchindexers. Sie sollten außerdem mit den Details der grundlegenden Konfiguration von Blobindexern vertraut sein, die hier nicht wiederholt wird.
Indizieren einzelner JSON-Dokumente (eines pro Blob)
Standardmäßig analysieren Blobindexer JSON-Blobs als einzelne Textblöcke, jeweils ein Suchdokument für jeden Blob in einem Container. Wenn das JSON-Blob strukturiert ist, kann diese Struktur im Suchdokument wiedergegeben werden, wobei einzelne Elemente als einzelne Felder dargestellt werden. Angenommen, Sie verwenden in Azure Blob Storage das folgende JSON-Dokument:
{
"article" : {
"text" : "A hopefully useful article explaining how to parse JSON blobs",
"datePublished" : "2020-04-13",
"tags" : [ "search", "storage", "howto" ]
}
}
Der Blobindexer löst das JSON-Dokument in ein einzelnes Suchdokument auf und lädt einen Index durch Abgleichen der Elemente „text“, „datePublished“ und „tags“ aus der Quelle mit Zielindexfeldern, die den gleichen Namen und Typ aufweisen. Bei einem Index mit den Feldern „text“, „datePublished“ und „tags“ kann der Blobindexer die richtige Zuordnung ableiten, ohne dass in der Anforderung eine Feldzuordnung enthalten ist.
Obwohl als Standardverhalten ein Suchdokument pro JSON-Blob vorgegeben ist, ändern sich durch Festlegen des json-Analysemodus die internen Feldzuordnungen für den Inhalt, wodurch Felder in content auf tatsächliche Felder im Suchindex heraufgestuft werden. Eine Indexerdefinition für den json-Analysemodus kann beispielsweise wie folgt aussehen:
POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
Content-Type: application/json
api-key: [admin key]
{
"name" : "my-json-indexer",
"dataSourceName" : "my-blob-datasource",
"targetIndexName" : "my-target-index",
"parameters" : { "configuration" : { "parsingMode" : "json" } }
}
Hinweis
Wie bei allen Indexern sollten Sie bei nicht eindeutig übereinstimmenden Feldern davon ausgehen, dass Sie einzelne Feldzuordnungen explizit angeben müssen, es sei denn, Sie verwenden die impliziten Feldzuordnungen, die für Blobinhalte und -metadaten verfügbar sind, wie unter der grundlegenden Konfiguration von Blobindexern beschrieben.
json-Beispiel (JSON-Dateien für einzelne Hotels)
Das Dataset hotel-json-documents auf GitHub ist hilfreich beim Testen der JSON-Analyse, wobei jedes Blob eine strukturierte JSON-Datei darstellt. Sie können die Datendateien in Blob Storage hochladen und den Datenimport-Assistenten verwenden, um schnell auszuwerten, wie dieser Inhalt in einzelne Suchdokumente aufgelöst wird.
Das Dataset besteht aus fünf Blobs, die jeweils ein „Hotel“-Dokument mit einer „Adressen“-Sammlung und einer „Zimmer“-Sammlung enthalten. Der Blobindexer erkennt beide Sammlungen und gibt die Struktur der Eingabedokumente im Indexschema wieder.
Analysieren von JSON-Arrays
Alternativ können Sie auch die JSON-Arrayoption verwenden. Diese Option ist nützlich, wenn Blobs ein Array von wohlgeformten JSON-Objekten enthalten und jedes Element zu einem separaten Suchdokument werden soll. Bei Verwendung von jsonArrays werden mit dem folgenden JSON-Blob drei separate Dokumente generiert, jedes jeweils mit den Feldern "id" und "text".
[
{ "id" : "1", "text" : "example 1" },
{ "id" : "2", "text" : "example 2" },
{ "id" : "3", "text" : "example 3" }
]
Die parameters-Eigenschaft des Indexers enthält Werte für den Analysemodus. Für ein JSON-Array sollte die Indexerdefinition dem folgenden Beispiel ähneln.
POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
Content-Type: application/json
api-key: [admin key]
{
"name" : "my-json-indexer",
"dataSourceName" : "my-blob-datasource",
"targetIndexName" : "my-target-index",
"parameters" : { "configuration" : { "parsingMode" : "jsonArray" } }
}
jsonArrays-Beispiel
Das New York Philharmonic-JSON-Dataset auf GitHub ist hilfreich beim Testen der Analyse von JSON-Arrays. Sie können die Datendateien in Blob Storage hochladen und den Datenimport-Assistenten verwenden, um schnell auszuwerten, wie dieser Inhalt in einzelne Suchdokumente aufgelöst wird.
Das Dataset besteht aus acht Blobs, die jeweils ein JSON-Array von Entitäten enthalten, mit insgesamt 100 Entitäten. Die Entitäten unterscheiden sich darin, welche Felder gefüllt werden, das Endergebnis ist jedoch ein Suchdokument pro Entität aus allen Arrays in allen Blobs.
Analysieren von geschachtelten JSON-Arrays
Damit JSON-Arrays geschachtelte Elemente enthalten, können Sie ein documentRoot-Element angeben, um eine Struktur mit mehreren Ebenen anzugeben. Angenommen, Ihre Blobs sehen folgendermaßen aus:
{
"level1" : {
"level2" : [
{ "id" : "1", "text" : "Use the documentRoot property" },
{ "id" : "2", "text" : "to pluck the array you want to index" },
{ "id" : "3", "text" : "even if it's nested inside the document" }
]
}
}
Verwenden Sie diese Konfiguration, um das in der level2-Eigenschaft enthaltene Array zu indizieren:
{
"name" : "my-json-array-indexer",
... other indexer properties
"parameters" : { "configuration" : { "parsingMode" : "jsonArray", "documentRoot" : "/level1/level2" } }
}
Analysieren von durch Zeilenvorschübe getrennten JSON-Entitäten
Wenn das Blob mehrere JSON-Entitäten enthält, die durch einen Zeilenvorschub getrennt sind, und jedes Element ein separates Suchdokument werden soll, verwenden Sie jsonLines.
{ "id" : "1", "text" : "example 1" }
{ "id" : "2", "text" : "example 2" }
{ "id" : "3", "text" : "example 3" }
Für JSON-Zeilen sollte die Indexerdefinition dem folgenden Beispiel ähneln.
POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
Content-Type: application/json
api-key: [admin key]
{
"name" : "my-json-indexer",
"dataSourceName" : "my-blob-datasource",
"targetIndexName" : "my-target-index",
"parameters" : { "configuration" : { "parsingMode" : "jsonLines" } }
}
Zuordnen von JSON-Feldern zu Suchfeldern
Mit Feldzuordnungen wird in den Fällen, in denen die Feldnamen und Feldtypen nicht identisch sind, ein Quellfeld einem Zielfeld zugeordnet. Feldzuordnungen können außerdem verwendet werden, um Teile eines JSON-Dokuments abzugleichen und auf Felder der obersten Ebene des Suchdokuments „hochzustufen“.
Das folgende Beispiel illustriert dieses Szenario. Weitere allgemeine Informationen zu Feldzuordnungen finden Sie unter Feldzuordnungen.
{
"article" : {
"text" : "A hopefully useful article explaining how to parse JSON blobs",
"datePublished" : "2016-04-13"
"tags" : [ "search", "storage", "howto" ]
}
}
Angenommen, Sie haben einen Suchindex mit den folgenden Feldern: text vom Typ Edm.String, date vom Typ Edm.DateTimeOffset und tags vom Typ Collection(Edm.String). Beachten Sie die Abweichung zwischen „datePublished“ in der Quelle und dem Feld date im Index. Um das JSON-Objekt in der gewünschten Form zuzuordnen, verwenden Sie die folgenden Feldzuordnungen:
"fieldMappings" : [
{ "sourceFieldName" : "/article/text", "targetFieldName" : "text" },
{ "sourceFieldName" : "/article/datePublished", "targetFieldName" : "date" },
{ "sourceFieldName" : "/article/tags", "targetFieldName" : "tags" }
]
Quellfelder werden mit der JSON-Zeiger-Notation angegeben. Sie beginnen mit einem Schrägstrich, um auf das Stammverzeichnis des JSON-Dokuments zu verweisen, und wählen dann mittels eines schrägstrichgetrennten Weiterleitungspfads den Pfad zur gewünschten Eigenschaft (auf beliebiger Schachtelungsebene) aus.
Sie können auch mit einem nullbasierten Index auf einzelne Arrayelemente verweisen. Um z. B. das erste Element des Arrays „tags“ aus dem obigen Beispiel auszuwählen, verwenden Sie eine Feldzuordnung wie folgt:
{ "sourceFieldName" : "/article/tags/0", "targetFieldName" : "firstTag" }
Hinweis
Wenn „sourceFieldName“ auf eine Eigenschaft verweist, die im JSON-Blob nicht vorhanden ist, wird diese Zuordnung ohne Fehler übersprungen. Dieses Verhalten ermöglicht das Fortsetzen der Indizierung für JSON-Blobs, die ein anderes Schema haben (ein häufiger Anwendungsfall). Da keine Validierungsüberprüfung durchgeführt wird, sollten Sie die Zuordnungen sorgfältig auf Tippfehler prüfen, damit keine Dokumente verloren gehen.