Zelfstudie: Geneste Markdown-blobs uit Azure Storage indexeren met behulp van REST

Artikel
11/19/2024

Notitie

Deze functie is momenteel beschikbaar als openbare preview-versie. Deze preview wordt aangeboden zonder service level agreement en wordt niet aanbevolen voor productieworkloads. Misschien worden bepaalde functies niet ondersteund of zijn de mogelijkheden ervan beperkt. Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure-previews voor meer informatie.

Azure AI Search kan Markdown-documenten en -matrices indexeren in Azure Blob Storage met behulp van een indexeerfunctie die weet hoe Markdown-gegevens moeten worden gelezen.

In deze zelfstudie ziet u hoe u Markdown-bestanden indexeert die zijn geïndexeerd met behulp van de oneToMany Markdown-parseringsmodus. Er wordt gebruikgemaakt van een REST-client en de SEARCH REST API's om de volgende taken uit te voeren:

Voorbeeldgegevens instellen en een azureblob gegevensbron configureren
Een Azure AI Search-index maken om doorzoekbare inhoud te bevatten
Een indexeerfunctie maken en uitvoeren om de container te lezen en doorzoekbare inhoud te extraheren
De index doorzoeken die u zojuist hebt gemaakt

Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.

Vereisten

Visual Studio Code met een REST-client.
Azure Storage
Azure AI Search. Maak of zoek een bestaande Azure AI Search-resource onder uw huidige abonnement.

Notitie

U kunt de gratis service voor deze zelfstudie gebruiken. Een gratis zoekservice beperkt u tot drie indexen, drie indexeerfuncties en drie gegevensbronnen. In deze zelfstudie wordt één exemplaar van elk onderdeel gemaakt. Voordat u aan de slag gaat, zorg ervoor dat uw service voldoende ruimte heeft voor de nieuwe resources.

Een Markdown-document maken

Kopieer en plak de volgende Markdown in een bestand met de naam sample_markdown.md. De voorbeeldgegevens zijn één Markdown-bestand met verschillende Markdown-elementen. We hebben één Markdown-bestand gekozen om onder de opslaglimieten van de gratis laag te blijven.

# 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!

Een URL en API-sleutel van een zoekservice kopiëren

Voor deze zelfstudie is voor verbindingen met Azure AI Search een eindpunt en een API-sleutel vereist. U kunt deze waarden ophalen uit Azure Portal. Zie beheerde identiteiten voor alternatieve verbindingsmethoden.

Meld u aan bij Azure Portal, navigeer naar de overzichtspagina van de zoekservice en kopieer de URL. Een eindpunt ziet er bijvoorbeeld uit als https://mydemo.search.windows.net.
Kopieer onder Instellingensleutels> een beheerderssleutel. Beheerderssleutels worden gebruikt om objecten toe te voegen, te wijzigen en te verwijderen. Er zijn twee uitwisselbare beheerderssleutels. Kopieer een van beide.

Uw REST-bestand instellen

Start Visual Studio Code en maak een nieuw bestand.

Geef waarden op voor variabelen die in de aanvraag worden gebruikt:

@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

Sla het bestand op met behulp van een .rest of .http bestandsextensie.

Zie quickstart: Tekst zoeken met REST als u hulp nodig hebt bij de REST-client.

Een gegevensbron maken

Een gegevensbronverbinding maken (REST) maakt een gegevensbronverbinding waarmee wordt aangegeven welke gegevens moeten worden geïndexeert.

### Create a data source
POST {{baseUrl}}/datasources?api-version=2024-11-01-preview  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
    }

Verzend de aanvraag. Het antwoord moet er als volgt uitzien:

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=2024-11-01-preview
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
}

Een index maken

Index maken (REST) maakt een zoekindex voor uw zoekservice. Een index geeft alle velden en de bijbehorende kenmerken aan.

Bij een-op-veel parseren definieert het zoekdocument de 'veel'-kant van de relatie. De velden die u in de index opgeeft, bepalen de structuur van het zoekdocument.

U hebt alleen velden nodig voor de Markdown-elementen die door de parser worden ondersteund. Deze velden zijn:

content: Een tekenreeks die de onbewerkte Markdown bevat die op een specifieke locatie is gevonden, op basis van de metagegevens van de header op dat moment in het document.
sections: Een object met subvelden voor de metagegevens van de header tot het gewenste headerniveau. Wanneer markdownHeaderDepth bijvoorbeeld is ingesteld op h3, bevat tekenreeksvelden h1en h2h3. Deze velden worden geïndexeerd door deze structuur in de index te spiegelen, of door veldtoewijzingen in de indeling /sections/h1, sections/h2enzovoort. Zie index- en indexeerfuncties in de volgende voorbeelden voor voorbeelden in context. De subvelden zijn:
- h1 - Een tekenreeks met de h1-headerwaarde. Lege tekenreeks als deze niet is ingesteld op dit punt in het document.
- (Optioneel) h2- Een tekenreeks met de h2-headerwaarde. Lege tekenreeks als deze niet is ingesteld op dit punt in het document.
- (Optioneel) h3- Een tekenreeks die de h3-headerwaarde bevat. Lege tekenreeks als deze niet is ingesteld op dit punt in het document.
- (Optioneel) h4- Een tekenreeks met de h4-headerwaarde. Lege tekenreeks als deze niet is ingesteld op dit punt in het document.
- (Optioneel) h5- Een tekenreeks met de h5-headerwaarde. Lege tekenreeks als deze niet is ingesteld op dit punt in het document.
- (Optioneel) h6- Een tekenreeks met de h6-headerwaarde. Lege tekenreeks als deze niet is ingesteld op dit punt in het document.
ordinal_position: Een geheel getal dat de positie van de sectie in de documenthiërarchie aangeeft. Dit veld wordt gebruikt voor het ordenen van de secties in de oorspronkelijke volgorde zoals ze worden weergegeven in het document, beginnend met een rangschikking van 1 en het sequentieel verhogen van elk inhoudsblok.

Deze implementatie maakt gebruik van veldtoewijzingen in de indexeerfunctie om van de verrijkte inhoud aan de index toe te wijzen. Zie Markdown-blobs indexeren voor meer informatie over de geparseerde een-op-veel-documentstructuur.

In dit voorbeeld ziet u voorbeelden van het indexeren van gegevens met en zonder veldtoewijzingen. In dit geval weten we dat h1 de titel van het document bevat, zodat we het kunnen toewijzen aan een veld met de naam title. We gaan ook de h2 velden h3 toewijzen aan h2_subheader en h3_subheader respectievelijk. Voor de content velden en ordinal_position velden is geen toewijzing vereist, omdat ze rechtstreeks uit Markdown worden geëxtraheerd in velden die deze namen gebruiken. Zie het einde van deze sectie voor een voorbeeld van een volledig indexschema waarvoor geen veldtoewijzingen nodig zijn.

### Create an index
POST {{baseUrl}}/indexes?api-version=2024-11-01-preview  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 een configuratie zonder veldtoewijzingen

Met veldtoewijzingen kunt u verrijkte inhoud bewerken en filteren zodat deze in de gewenste indexvorm past, maar u kunt de verrijkte inhoud misschien gewoon rechtstreeks gebruiken. In dat geval ziet het schema er als volgt uit:

{
  "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}
  ]
}

Om het nogmaals te herhalen, hebben we subvelden tot h3 in het sectieobject, omdat markdownHeaderDepth deze is ingesteld op h3.

Als u ervoor kiest dit schema te gebruiken, moet u latere aanvragen dienovereenkomstig aanpassen. Hiervoor moet u de veldtoewijzingen uit de configuratie van de indexeerfunctie verwijderen en zoekquery's bijwerken om de bijbehorende veldnamen te gebruiken.

Indexeerfunctie maken en uitvoeren

Indexeerfunctie maken maakt een indexeerfunctie voor uw zoekservice. Een indexeerfunctie maakt verbinding met de gegevensbron, laadt en indexeert gegevens en biedt desgewenst een planning voor het automatiseren van de gegevensvernieuwing.

### Create and run an indexer
POST {{baseUrl}}/indexers?api-version=2024-11-01-preview  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
        }
      ]
    }

Belangrijkste punten:

De indexeerfunctie parseert alleen headers tot h3. Eventuele kopteksten op lager niveau (h4,h5,h6) worden behandeld als tekst zonder opmaak en worden weergegeven in het content veld. Daarom bestaan de index- en veldtoewijzingen alleen tot een diepte van h3.
Voor de content velden is ordinal_position geen veldtoewijzing vereist, omdat deze bestaan met deze namen in de verrijkte inhoud.

Query's uitvoeren

Zodra het eerste document is geladen, kunt u meteen beginnen met zoeken.

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

Verzend de aanvraag. Dit is een niet-opgegeven query voor zoeken op volledige tekst waarmee alle velden worden opgehaald die als Kan worden opgehaald zijn gemarkeerd in de index, samen met het aantal documenten. Het antwoord moet er als volgt uitzien:

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>
  ]
}

Voeg een search parameter toe om te zoeken op een tekenreeks.

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

Verzend de aanvraag. Het antwoord moet er als volgt uitzien:

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
    }
  ]
}

Belangrijkste punten:

Omdat de markdownHeaderDepth waarden zijn ingesteld op h3, worden de h4, h5en h6 kopteksten behandeld als tekst zonder opmaak, zodat ze in het content veld worden weergegeven.
Ordinale positie hier is 4. Deze inhoud wordt vierde van de 22 totale inhoudssecties weergegeven.

Voeg een select parameter toe om de resultaten te beperken tot minder velden. Voeg een filter toe om de zoekopdracht verder te verfijnen.

### Query the index
POST {{baseUrl}}/indexes/sample-markdown-index/docs/search?api-version=2024-11-01-preview  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"
    }
  ]
}

Voor filters kunt u ook logische operatoren (en, of niet) en vergelijkingsoperators (eq, ne, gt, lt, ge, le) gebruiken. Tekenreeksvergelijkingen zijn hoofdlettergevoelig. Zie Een query maken voor meer informatie en voorbeelden.

Notitie

De $filter parameter werkt alleen op velden die zijn gemarkeerd als filterbaar bij het maken van uw index.

Opnieuw instellen en uitvoeren

Indexeerfuncties kunnen opnieuw worden ingesteld, uitvoeringsgeschiedenis wissen, waardoor een volledige uitvoering mogelijk is. De volgende GET-aanvragen zijn voor het opnieuw instellen, gevolgd door opnieuw uitvoeren.

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

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

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

Resources opschonen

Wanneer u in uw eigen abonnement werkt, is het een goed idee om aan het einde van een project te bepalen of u de gemaakte resources nog steeds nodig hebt en of u deze moet verwijderen. Resources die actief blijven, kunnen u geld kosten. U kunt resources afzonderlijk verwijderen, maar u kunt ook de resourcegroep verwijderen als u de volledige resourceset wilt verwijderen.

U kunt Azure Portal gebruiken om indexen, indexeerfuncties en gegevensbronnen te verwijderen.

Volgende stappen

Nu u bekend bent met de basisprincipes van Azure Blob-indexering, gaan we de configuratie van de indexeerfunctie voor Markdown-blobs in Azure Storage nader bekijken.

Markdown-blobindexering configureren

Delen via

Zelfstudie: Geneste Markdown-blobs uit Azure Storage indexeren met behulp van REST

Vereisten

Een Markdown-document maken

Een URL en API-sleutel van een zoekservice kopiëren

Uw REST-bestand instellen

Een gegevensbron maken

Een index maken

Indexschema in een configuratie zonder veldtoewijzingen

Indexeerfunctie maken en uitvoeren

Query's uitvoeren

Opnieuw instellen en uitvoeren

Resources opschonen

Volgende stappen

Feedback

Aanvullende resources