Lernprogramm: Geschachtelte Markdown-Blobs aus Azure Storage mithilfe von REST indizieren

Azure KI-Suche können Markdown-Dokumente und -Arrays in Azure Blob Storage mithilfe eines indexer indizieren, der weiß, wie Markdown-Daten gelesen werden.

In diesem Lernprogramm erfahren Sie, wie Sie Markdown-Dateien mithilfe des oneToMany Markdown-Analysemodus und der REST-APIs des Suchdiensts indizieren.

In diesem Tutorial:

Voraussetzungen

• Ein Azure Konto mit einem aktiven Abonnement. Erstellen Sie kostenlos ein Konto.

• Ein Azure Storage-Konto.

• Ein Azure KI-Suche-Dienst.

• Visual Studio Code mit der REST-Clienterweiterung.

Vorbereiten von Beispieldaten

Erstellen einer Markdown-Datei

Kopieren Sie den folgenden Markdown, und fügen Sie ihn in eine Datei mit dem Namen sample_markdown.mdein. Die Beispieldaten sind eine einzelne Markdown-Datei mit verschiedenen Markdown-Elementen. Wir haben eine Markdown-Datei ausgewählt, um unter den Speichergrenzwerten der Stufe "Kostenlos" zu bleiben.

# Project Documentation

## Introduction
This document provides a complete overview of the **Markdown Features** used within this project. The following sections demonstrate the richness of Markdown formatting, with examples of lists, tables, links, images, blockquotes, inline styles, and more.

---

## Table of Contents
1. [Headers](#headers)
2. [Introduction](#introduction)
3. [Basic Text Formatting](#basic-text-formatting)
4. [Lists](#lists)
5. [Blockquotes](#blockquotes)
6. [Images](#images)
7. [Links](#links)
8. [Tables](#tables)
9. [Code Blocks and Inline Code](#code-blocks-and-inline-code)
10. [Horizontal Rules](#horizontal-rules)
11. [Inline Elements](#inline-elements)
12. [Escaping Characters](#escaping-characters)
13. [HTML Elements](#html-elements)
14. [Emojis](#emojis)
15. [Footnotes](#footnotes)
16. [Task Lists](#task-lists)
17. [Conclusion](#conclusion)

---

## Headers
Markdown supports six levels of headers. Use `#` to create headers:
"# Project Documentation" at the top of the document is an example of an h1 header.
"## Headers" above is an example of an h2 header.
### h3 example
#### h4 example
##### h5 example
###### h6 example
This is an example of content underneath a header.

## Basic Text Formatting
You can apply various styles to your text:
- **Bold**: Use double asterisks or underscores: `**bold**` or `__bold__`.
- *Italic*: Use single asterisks or underscores: `*italic*` or `_italic_`.
- ~~Strikethrough~~: Use double tildes: `~~strikethrough~~`.

## Lists

### Ordered List
1. First item  
2. Second item  
3. Third item  

### Unordered List
- Item A  
- Item B  
- Item C  

### Nested List
1. Parent item  
   - Child item  
   - Child item  

## Blockquotes
> This is a blockquote.  
> Blockquotes are great for emphasizing important information.  
>> Nested blockquotes are also possible!

## Images
![Markdown Logo](https://markdown-here.com/img/icon256.png)

## Links
[Visit Markdown Guide](https://www.markdownguide.org)

## Tables

| Syntax      | Description | Example       |
|-------------|-------------|---------------|
| Header      | Title       | Header Cell   |
| Paragraph   | Text block  | Row Content   |

## Code Blocks and Inline Code

### Inline Code
Use backticks to create `inline code`.

### Code Block
```javascript
// JavaScript example
function greet(name) {
  console.log(`Hello, ${name}!`);
}
greet('World');
```

## Horizontal Rules
Use three or more dashes or underscores to create a horizontal rule.

---
___

## Inline Elements
Sometimes, it’s useful to include `inline code` to highlight code-like content.  

You can also emphasize text like *this* or make it **bold**.

## Escaping Characters
To render special Markdown characters, use backslashes:
- \*Asterisks\*
- \#Hashes\#
- \[Brackets\]

## HTML Elements
You can mix HTML tags with Markdown:

<table>
  <tr>
    <th>HTML Table</th>
    <th>With Markdown</th>
  </tr>
  <tr>
    <td>Row 1</td>
    <td>Data 1</td>
  </tr>
</table>

## Emojis
Markdown supports some basic emojis:
- :smile: 😄  
- :rocket: 🚀  
- :checkered_flag: 🏁  

## Footnotes
This is an example of a footnote[^1]. Footnotes allow you to add notes without cluttering the main text.

[^1]: This is the content of the footnote.

## Task Lists
- [x] Complete the introduction  
- [ ] Add more examples  
- [ ] Review the document 

## Conclusion
Markdown is a lightweight yet powerful tool for writing documentation. It supports a variety of formatting options while maintaining simplicity and readability.

Thank you for reviewing this example!

Laden Sie die Datei hoch, und erhalten Sie die Verbindungszeichenfolge.

Folgen Sie diese Anweisungen zum Hochladen der sample_markdown.md Datei in einen Container in Ihrem Azure Storage-Konto. Sie müssen auch die Speicherkonto-Verbindungszeichenfolge abrufen. Notieren Sie sich die Verbindungszeichenfolge und den Containernamen für die spätere Verwendung.

Kopieren einer Suchdienst-URL und eines API-Schlüssels

Für dieses Lernprogramm erfordern Verbindungen mit Azure KI-Suche einen Endpunkt und einen API-Schlüssel. Sie können diese Werte aus dem Azure Portal abrufen. Alternative Verbindungsmethoden finden Sie unter verwaltete Identitäten.

1. Wechseln Sie zum Suchdienst im Azure-Portal.

2. Wählen Sie im linken Bereich die Option "Übersicht" aus.

3. Notieren Sie sich die URL, die wie https://my-service.search.windows.net folgt aussehen soll.

4. Wählen Sie im linken Bereich Einstellungen>Keys aus.

5. Notieren Sie sich einen Administratorschlüssel für vollständige Rechte für den Dienst. Es gibt zwei austauschbare Administratorschlüssel, die für die Geschäftskontinuität bereitgestellt werden, falls Sie ein Rollover ausführen müssen. Sie können einen der Schlüssel für Anforderungen zum Hinzufügen, Ändern und Löschen von Objekten verwenden.

   

Einrichten der REST-Datei

1. Erstellen Sie eine Datei in Visual Studio Code.

2. Geben Sie Werte für Variablen an, die in der Anforderung verwendet werden.

   @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
   @apiKey = PUT-YOUR-ADMIN-API-KEY-HERE
   @storageConnectionString = PUT-YOUR-STORAGE-CONNECTION-STRING-HERE
   @blobContainer = PUT-YOUR-CONTAINER-NAME-HERE
   

3. Speichern Sie die Datei mit einer .rest Oder .http Dateierweiterung.

Hilfe zum REST-Client finden Sie in der Schnellstartanleitung: Volltextsuche mit REST.

Erstellen einer Datenquelle

Datenquellen – Erstellen (REST-API) erstellt eine Datenquellenverbindung, die angibt, welche Daten indiziert werden sollen.

### Create a data source
POST {{baseUrl}}/datasources?api-version=2026-04-01  HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}

{
    "name" : "sample-markdown-ds",
    "description": null,
    "type": "azureblob",
    "subtype": null,
    "credentials": {
        "connectionString": "{{storageConnectionString}}"
    },
    "container": {
        "name": "{{blobContainer}}",
        "query": null
    },
    "dataChangeDetectionPolicy": null,
    "dataDeletionDetectionPolicy": null
}

Senden Sie die Anforderung. Die Antwort sollte wie folgt aussehen:

HTTP/1.1 201 Created
Transfer-Encoding: chunked
Content-Type: application/json; odata.metadata=minimal; odata.streaming=true; charset=utf-8
ETag: "0x8DCF52E926A3C76"
Location: https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net:443/datasources('sample-markdown-ds')?api-version=2026-04-01
Server: Microsoft-IIS/10.0
Strict-Transport-Security: max-age=2592000, max-age=15724800; includeSubDomains
Preference-Applied: odata.include-annotations="*"
OData-Version: 4.0
request-id: 0714c187-217e-4d35-928a-5069251e5cba
elapsed-time: 204
Date: Fri, 25 Oct 2024 19:52:35 GMT
Connection: close

{
  "@odata.context": "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/$metadata#datasources/$entity",
  "@odata.etag": "\"0x8DCF52E926A3C76\"",
  "name": "sample-markdown-ds",
  "description": null,
  "type": "azureblob",
  "subtype": null,
  "credentials": {
    "connectionString": null
  },
  "container": {
    "name": "markdown-container",
    "query": null
  },
  "dataChangeDetectionPolicy": null,
  "dataDeletionDetectionPolicy": null,
  "encryptionKey": null,
  "identity": null
}

Erstellen eines Indexes

Indizes – Erstellen (REST-API) erstellt einen Suchindex für Ihren Suchdienst. Ein Index gibt alle Felder und deren Attribute an.

In der 1:n-Analyse definiert das Suchdokument die n-Seite der Beziehung. Die im Index angegebenen Felder bestimmen die Struktur des Suchdokuments.

Sie benötigen nur Felder für die Markdown-Elemente, die der Parser unterstützt. Diese Felder sind:

• content: Eine Zeichenfolge, die den unformatierten Markdown enthält, der an einer bestimmten Stelle gefunden wurde, basierend auf den Headermetadaten an diesem Punkt im Dokument.

• sections: Ein Objekt, das Unterfelder für die Headermetadaten bis zur gewünschten Kopfzeilenebene enthält. Wenn beispielsweise markdownHeaderDepth auf h3 gesetzt ist, enthält es die Zeichenfolgenfelder h1, h2 und h3. Diese Felder werden durch Spiegelung dieser Struktur im Index oder durch Feldzuordnungen im Format /sections/h1, /sections/h2usw. indiziert. Kontextbezogene Beispiele finden Sie in den Index- und Indexerkonfigurationen in den folgenden Beispielen. Die enthaltenen Unterfelder sind:

  • h1 - Eine Zeichenfolge, die den h1-Headerwert enthält. Leere Zeichenfolge, wenn sie an diesem Punkt im Dokument nicht festgelegt ist.
  • (Optional) h2- Eine Zeichenfolge, die den h2-Headerwert enthält. Leere Zeichenfolge, wenn sie an diesem Punkt im Dokument nicht festgelegt ist.
  • (Optional) h3- Eine Zeichenfolge, die den h3-Headerwert enthält. Leere Zeichenfolge, wenn sie an diesem Punkt im Dokument nicht festgelegt ist.
  • (Optional) h4- Eine Zeichenfolge, die den h4-Headerwert enthält. Leere Zeichenfolge, wenn sie an diesem Punkt im Dokument nicht festgelegt ist.
  • (Optional) h5- Eine Zeichenfolge, die den h5-Headerwert enthält. Leere Zeichenfolge, wenn sie an diesem Punkt im Dokument nicht festgelegt ist.
  • (Optional) h6- Eine Zeichenfolge, die den h6-Headerwert enthält. Leere Zeichenfolge, wenn sie an diesem Punkt im Dokument nicht festgelegt ist.

• ordinal_position: Ein ganzzahliger Wert, der die Position des Abschnitts innerhalb der Dokumenthierarchie angibt. Dieses Feld wird verwendet, um die Abschnitte in der ursprünglichen, im Dokument angezeigten Reihenfolge zu sortieren, beginnend mit einer Ordnungsposition von 1 und einer sequenziellen Erhöhung für jeden Inhaltsblock.

In dieser Implementierung werden Feldzuordnungen im Indexer verwendet, um den angereicherten Inhalt dem Index zuzuordnen. Weitere Informationen zur analysierten One-to-Many-Dokumentstruktur finden Sie unter Index Markdown-Blobs.

Dieses Beispiel enthält Beispiele zum Indizieren von Daten mit und ohne Feldzuordnungen. In diesem Fall enthält h1 den Titel des Dokuments und ist einem Feld mit dem Namen title zugeordnet. Die Felder h2 und h3 werden jeweils h2_subheader und h3_subheader zugeordnet. Die content- und ordinal_position-Felder erfordern keine Zuordnung, da sie direkt aus dem Markdown in Felder mit diesen Namen extrahiert werden. Ein Beispiel für ein vollständiges Indexschema, das keine Feldzuordnungen erfordert, finden Sie am Ende dieses Abschnitts.

### Create an index
POST {{baseUrl}}/indexes?api-version=2026-04-01  HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}

{
  "name": "sample-markdown-index",  
  "fields": [
    {"name": "id", "type": "Edm.String", "key": true, "searchable": true, "retrievable": true, "filterable": true, "facetable": true, "sortable": true},
    {"name": "content", "type": "Edm.String", "key": false, "searchable": true, "retrievable": true, "filterable": true, "facetable": true, "sortable": true},
    {"name": "title", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "facetable": true, "sortable": true},
    {"name": "h2_subheader", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "facetable": true, "sortable": true},
    {"name": "h3_subheader", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "facetable": true, "sortable": true},
    {"name": "ordinal_position", "type": "Edm.Int32", "searchable": false, "retrievable": true, "filterable": true, "facetable": true, "sortable": true}
  ]
}

Indexschema in einer Konfiguration ohne Feldzuordnungen

Mit Feldzuordnungen können Sie angereicherte Inhalte bearbeiten und filtern, damit sie in die gewünschte Index-Struktur passen. Möglicherweise möchten Sie jedoch nur den erweiterten Inhalt direkt nutzen. In diesem Fall würde das Schema wie folgt aussehen:

{
  "name": "sample-markdown-index",
  "fields": [
    {"name": "id", "type": "Edm.String", "key": true, "searchable": true, "retrievable": true, "filterable": true, "facetable": true, "sortable": true},
    {"name": "content", "type": "Edm.String", "key": false, "searchable": true, "retrievable": true, "filterable": true, "facetable": true, "sortable": true},
    {"name": "sections", 
      "type": "Edm.ComplexType", 
      "fields": [
        {"name": "h1", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "facetable": true, "sortable": true},
        {"name": "h2", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "facetable": true, "sortable": true},
        {"name": "h3", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "facetable": true, "sortable": true}
      ]
    },
    {"name": "ordinal_position", "type": "Edm.Int32", "searchable": false, "retrievable": true, "filterable": true, "facetable": true, "sortable": true}
  ]
}

Um es zu wiederholen, haben wir Unterfelder innerhalb des Abschnittsobjekts bis h3, weil markdownHeaderDepth auf h3 gesetzt ist.

Wenn Sie dieses Schema verwenden, stellen Sie sicher, dass Sie spätere Anforderungen entsprechend anpassen. Dazu müssen die Feldzuordnungen aus der Indexerkonfiguration entfernt und Suchabfragen so aktualisiert werden, dass die entsprechenden Feldnamen verwendet werden.

Erstellen und Ausführen eines Indexers

Indexer – Create (REST API) erstellt einen Indexer für Ihren Suchdienst. Ein Indexer stellt eine Verbindung mit der Datenquelle, lädt und indiziert Daten und bietet optional einen Zeitplan zum Automatisieren der Datenaktualisierung.

### Create and run an indexer
POST {{baseUrl}}/indexers?api-version=2026-04-01  HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}

{
  "name": "sample-markdown-indexer",
  "dataSourceName": "sample-markdown-ds",
  "targetIndexName": "sample-markdown-index",
  "parameters" : { 
    "configuration": { 
      "parsingMode": "markdown",
      "markdownParsingSubmode": "oneToMany",
      "markdownHeaderDepth": "h3"
      }
    },
  "fieldMappings" : [ 
    {
      "sourceFieldName": "/sections/h1",
      "targetFieldName": "title",
      "mappingFunction": null
    }
  ]
}

Wichtige Punkte:

• Der Indexer analysiert nur Kopfzeilen bis zu h3. Alle Kopfzeilen der unteren Ebene (h4,h5,h6) werden als Nur-Text behandelt und im content Feld angezeigt. Aus diesem Grund existieren die Index- und Feldzuordnungen nur bis zu einer Tiefe von h3.

• Für die Felder content und ordinal_position ist keine Feldzuordnung erforderlich, da sie mit diesen Namen im erweiterten Inhalt vorhanden sind.

Ausführen von Abfragen

Sie können mit der Suche beginnen, sobald das erste Dokument geladen wird.

### Query the index
POST {{baseUrl}}/indexes/sample-markdown-index/docs/search?api-version=2026-04-01  HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
  
{
  "search": "*",
  "count": true
}

Senden Sie die Anforderung. Dies ist eine nicht angegebene Volltext-Suchabfrage, die alle felder zurückgibt, die im Index als abrufbar gekennzeichnet sind, zusammen mit einer Dokumentanzahl. Die Antwort sollte wie folgt aussehen:

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json; odata.metadata=minimal; odata.streaming=true; charset=utf-8
Content-Encoding: gzip
Vary: Accept-Encoding
Server: Microsoft-IIS/10.0
Strict-Transport-Security: max-age=2592000, max-age=15724800; includeSubDomains
Preference-Applied: odata.include-annotations="*"
OData-Version: 4.0
request-id: 6b94e605-55e8-47a5-ae15-834f926ddd14
elapsed-time: 77
Date: Fri, 25 Oct 2024 20:22:58 GMT
Connection: close

{
  "@odata.context": "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes('sample-markdown-index')/$metadata#docs(*)",
  "@odata.count": 22,
  "value": [
    <22 search documents here>
  ]
}

Fügen Sie einen search Parameter hinzu, um nach einer Zeichenfolge zu suchen.

### Query the index
POST {{baseUrl}}/indexes/sample-markdown-index/docs/search?api-version=2026-04-01  HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
  
{
  "search": "h4",
  "count": true
}

Senden Sie die Anforderung. Die Antwort sollte wie folgt aussehen:

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json; odata.metadata=minimal; odata.streaming=true; charset=utf-8
Content-Encoding: gzip
Vary: Accept-Encoding
Server: Microsoft-IIS/10.0
Strict-Transport-Security: max-age=2592000, max-age=15724800; includeSubDomains
Preference-Applied: odata.include-annotations="*"
OData-Version: 4.0
request-id: ec5d03f1-e3e7-472f-9396-7ff8e3782105
elapsed-time: 52
Date: Fri, 25 Oct 2024 20:26:29 GMT
Connection: close

{
  "@odata.context": "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes('sample-markdown-index')/$metadata#docs(*)",
  "@odata.count": 1,
  "value": [
    {
      "@search.score": 0.8744742,
      "section_id": "aHR0cHM6Ly9hcmphZ2Fubmpma2ZpbGVzLmJsb2IuY29yZS53aW5kb3dzLm5ldC9tYXJrZG93bi10dXRvcmlhbC9zYW1wbGVfbWFya2Rvd24ubWQ7NA2",
      "content": "#### h4 example\r\n##### h5 example\r\n###### h6 example\r\nThis is an example of content underneath a header.\r\n",
      "title": "Project Documentation",
      "h2_subheader": "Headers",
      "h3_subheader": "h3 example",
      "ordinal_position": 4
    }
  ]
}

Wichtige Punkte:

• Da die markdownHeaderDepth auf h3 eingestellt ist, werden die Kopfzeilen h4, h5 und h6 als Klartext behandelt und im content-Feld angezeigt.

• Hier ist die Ordnungsposition 4. Dieser Inhalt erscheint als vierter von insgesamt 22 Inhaltsabschnitten.

Fügen Sie einen select Parameter hinzu, um die Ergebnisse auf weniger Felder zu beschränken. Fügen Sie eine filter hinzu, um die Suche weiter einzugrenzen.

### Query the index
POST {{baseUrl}}/indexes/sample-markdown-index/docs/search?api-version=2026-04-01  HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
  
{
  "search": "Markdown",
  "count": true,
  "select": "title, content, h2_subheader",
  "filter": "h2_subheader eq 'Conclusion'"
}

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json; odata.metadata=minimal; odata.streaming=true; charset=utf-8
Content-Encoding: gzip
Vary: Accept-Encoding
Server: Microsoft-IIS/10.0
Strict-Transport-Security: max-age=2592000, max-age=15724800; includeSubDomains
Preference-Applied: odata.include-annotations="*"
OData-Version: 4.0
request-id: a6f9bd46-a064-4e28-818f-ea077618014b
elapsed-time: 35
Date: Fri, 25 Oct 2024 20:36:10 GMT
Connection: close

{
  "@odata.context": "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes('sample-markdown-index')/$metadata#docs(*)",
  "@odata.count": 1,
  "value": [
    {
      "@search.score": 1.1029507,
      "content": "Markdown is a lightweight yet powerful tool for writing documentation. It supports a variety of formatting options while maintaining simplicity and readability.\r\n\r\nThank you for reviewing this example!",
      "title": "Project Documentation",
      "h2_subheader": "Conclusion"
    }
  ]
}

Für Filter können Sie auch logische Operatoren (und oder nicht) und Vergleichsoperatoren (eq, ne, gt, lt, ge, le) verwenden. Bei Zeichenfolgenvergleichen wird die Groß-/Kleinschreibung beachtet. Weitere Informationen und Beispiele finden Sie unter Erstellen einer Abfrage.

Zurücksetzen und erneut ausführen

Indexer können zurückgesetzt werden, um den Ausführungsverlauf zu löschen, wodurch eine vollständige Erneute Ausführung möglich ist. Die folgenden Anforderungen setzen den Indexer zurück und führen ihn erneut aus.

### Reset the indexer
POST {{baseUrl}}/indexers/sample-markdown-indexer/reset?api-version=2026-04-01  HTTP/1.1
api-key: {{apiKey}}

### Run the indexer
POST {{baseUrl}}/indexers/sample-markdown-indexer/run?api-version=2026-04-01  HTTP/1.1
api-key: {{apiKey}}

### Check indexer status 
GET {{baseUrl}}/indexers/sample-markdown-indexer/status?api-version=2026-04-01  HTTP/1.1
api-key: {{apiKey}}

Bereinigen von Ressourcen

Wenn Sie in Ihrem eigenen Abonnement arbeiten, empfiehlt es sich, die nicht mehr benötigten Ressourcen am Ende eines Projekts zu entfernen. Ressourcen, die weiterhin ausgeführt werden, können Sie Geld kosten. Sie können Ressourcen einzeln löschen oder die Ressourcengruppe löschen, um den gesamten Satz von Ressourcen zu löschen.

Sie können das Azure Portal verwenden, um Indizes, Indexer und Datenquellen zu löschen.

Nächste Schritte

Nachdem Sie nun mit den Grundlagen der Azure Blob-Indizierung vertraut sind, werfen Sie einen genaueren Blick auf die Indexerkonfiguration für Markdown-Blobs in Azure Storage: