Oktatóanyag: Beágyazott Markdown-blobok indexelése Azure Storage REST használatával

Megjegyzés

Azure AI Keresés a Azure portálon, REST API-kon és Azure SDK-k keresztül érhető el. Emellett a Foundry IQ-t is támogatja, amely a vállalati tartalmakat újrafelhasználható, engedélytudatos tudásbázisokká alakítja át az Microsoft Foundry portálon található ügynökök számára.

Azure AI Keresés, egy indexer használatával, indexelheti a Markdown-dokumentumokat és -tömböket az Azure Blob Storage-ban, amely képes kezelni a Markdown-adatokat.

Ez az oktatóanyag bemutatja, hogyan indexelheti a Markdown-fájlokat a oneToMany Markdown-elemzési mód és a Search Service REST API-k használatával.

Ebben az oktatóanyagban ön:

  • Mintaadatok beállítása és adatforrás konfigurálása azureblob
  • Kereshető tartalmakat tartalmazó Azure AI Keresés index létrehozása
  • Indexelő létrehozása és futtatása a tároló olvasásához és kereshető tartalom kinyeréséhez
  • Keresés az imént létrehozott indexben

Előfeltételek

Megjegyzés

Ehhez az oktatóanyaghoz ingyenes keresési szolgáltatást használhat. Az ingyenes szint három indexre, három indexelőre és három adatforrásra korlátozza. Ez az oktatóanyag mindegyikből egyet hoz létre. Mielőtt hozzákezd, győződjön meg arról, hogy a szolgáltatásnak van helye az új erőforrások elfogadásához.

Mintaadatok előkészítése

Markdown-fájl létrehozása

Másolja és illessze be a következő Markdownt egy nevű sample_markdown.mdfájlba. A mintaadatok egyetlen Markdown-fájl, amely különböző Markdown-elemeket tartalmaz. Egy Markdown-fájlt választottunk, amely az ingyenes szint tárolási korlátai alatt marad.

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

Töltse fel a fájlt és szerezze be a csatlakozási karakterláncot

Kövesse these utasításokat a sample_markdown.md fájl feltöltéséhez a Azure Storage-fiók egyik tárolójába. A tárhely-fiók kapcsolati karakterláncát is meg kell szereznie. Jegyezze fel a kapcsolati karakterlánc és a tároló nevét későbbi használatra.

Keresési szolgáltatás URL-címének és API-kulcsának másolása

Ebben az oktatóanyagban a Azure AI Keresés való kapcsolatokhoz végpontra és API-kulcsra van szükség. Ezeket az értékeket a Azure portálon szerezheti be. Alternatív kapcsolati módszerekért tekintse meg a felügyelt identitásokat.

  1. Nyissa meg a keresőszolgáltatást a Azure portálon.

  2. A bal oldali panelen válassza az Áttekintés lehetőséget.

  3. Jegyezze fel az URL-címet, amelynek így kell kinéznie https://my-service.search.windows.net.

  4. A bal oldali panelen válassza a Beállítások>kulcsok lehetőséget.

  5. Jegyezze fel egy rendszergazdai kulcsot a szolgáltatás teljes jogosultságaihoz. Két felcserélhető rendszergazdai kulcs áll rendelkezésre az üzletmenet folytonossága érdekében, ha át kell gördítenie egyet. Az objektumok hozzáadására, módosítására és törlésére irányuló kérelmekhez bármelyik kulcsot használhatja.

    URL és API-kulcsok képernyőképe az Azure portálon.

A REST-fájl beállítása

  1. Hozzon létre egy fájlt a Visual Studio Code-ban.

  2. Adja meg a kérelemben használt változók értékeit.

    @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. Mentse a fájlt a .rest vagy .http fájlkiterjesztés használatával.

A REST-ügyféllel kapcsolatos segítségért tekintse meg a következő rövid útmutatót: Teljes szöveges keresés REST használatával.

Adatforrás létrehozása

Adatforrások – A létrehozás (REST API) létrehoz egy adatforrás-kapcsolatot, amely meghatározza az indexelendő adatokat.

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

Küldje el a kérést. A válasznak a következőképpen kell kinéznie:

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
}

Index létrehozása

Indexek – A létrehozás (REST API) létrehoz egy keresési indexet a keresési szolgáltatásban. Az index az összes mezőt és attribútumot meghatározza.

Az egy-a-többhöz elemzés során a keresési dokumentum a kapcsolat "több" oldalát határozza meg. Az indexben megadott mezők határozzák meg a keresési dokumentum szerkezetét.

Csak az elemző által támogatott Markdown-elemek mezőire van szükség. Ezek a mezők a következők:

  • content: Egy karakterlánc, amely a dokumentum egy adott pontján található fejléc metaadatai alapján meghatározott helyen lévő nyers Markdown szöveget tartalmazza.

  • sections: Olyan objektum, amely a fejléc metaadatainak almezőit tartalmazza a kívánt fejlécszintig. Például, amikor a markdownHeaderDepth be van állítva h3, akkor sztringmezőket tartalmaz, mint például h1, h2 és h3. Ezeket a mezőket a rendszer úgy indexeli, hogy tükrözi ezt a struktúrát az indexben, vagy a formátumbeli /sections/h1/sections/h2mezőleképezéseken keresztül stb. A környezetbeli példákért tekintse meg az index és az indexelő konfigurációit az alábbi mintákban. Az almezők a következők:

    • h1 - h1 fejlécértéket tartalmazó string. Üres karakterlánc, ha a dokumentum ezen a pontján nincs beállítva.
    • (Nem kötelező) h2- Egy h2 fejlécértéket tartalmazó karakterlánc. Üres karakterlánc, ha a dokumentum ezen a pontján nincs beállítva.
    • (Nem kötelező) h3- Egy karakterlánc, amely a h3 fejlécértéket tartalmazza. Üres karakterlánc, ha a dokumentum ezen a pontján nincs beállítva.
    • (Nem kötelező) h4- A h4 fejlécértéket tartalmazó sztring. Üres karakterlánc, ha a dokumentum ezen a pontján nincs beállítva.
    • (Nem kötelező), h5- A h5 fejléc értékét tartalmazó karakterlánc. Üres karakterlánc, ha a dokumentum ezen a pontján nincs beállítva.
    • (Nem kötelező)h6 - A h6 fejlécértéket tartalmazó karakterlánc. Üres karakterlánc, ha a dokumentum ezen a pontján nincs beállítva.
  • ordinal_position: Egész szám, amely a szakasz dokumentumhierarchián belüli pozícióját jelzi. Ez a mező arra szolgál, hogy az eredeti sorrendben rendezze a szakaszokat, ahogy azok megjelennek a dokumentumban, kezdve az 1 sorszámmal és az egyes tartalomblokkok sorrendjének növelésével.

Ez az implementáció az indexelő mezőleképezéseit használja a bővített tartalomról az indexre való leképezéshez. Az egy-a-többhöz elemzett dokumentumstruktúráról további információt az Index Markdown-blobokban talál.

Ez a példa példákat tartalmaz arra, hogyan indexelhet adatokat mezőleképezésekkel és anélkül is. Ebben az esetben a h1 tartalmazza a dokumentum címét, és leképezi egy elnevezett title mezőre. A h2 és a h3 mezők a h2_subheader és a h3_subheader mezőkkel vannak megfeleltetve. A content mezők és ordinal_position mezők nem igényelnek leképezést, mert a Markdownból közvetlenül a névvel rendelkező mezőkbe nyerik ki őket. A mezőleképezést nem igénylő teljes indexséma példáját a szakasz végén találja.

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

Indexséma mezőleképezések nélküli konfigurációban

A mezőleképezésekkel manipulálhatja és szűrheti a bővített tartalmakat, hogy illeszkedjenek a kívánt indexalakzathoz. Előfordulhat azonban, hogy csak közvetlenül szeretné használni a bővített tartalmat. Ebben az esetben a séma a következőképpen néz ki:

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

Ismételten hangsúlyozzuk, hogy a szakaszok objektumában megtalálható h3 almezők azért vannak markdownHeaderDepth a következőre h3 állítva.

Ha ezt a sémát használja, mindenképpen módosítsa a későbbi kéréseket ennek megfelelően. Ehhez el kell távolítania a mezőleképezéseket az indexelő konfigurációjából, és frissítenie kell a keresési lekérdezéseket a megfelelő mezőnevek használatára.

Indexelő létrehozása és futtatása

Indexelők – A létrehozás (REST API) létrehoz egy indexelőt a keresési szolgáltatásban. Az indexelő csatlakozik az adatforráshoz, betölti és indexeli az adatokat, és opcionálisan ütemezést biztosít az adatfrissítés automatizálásához.

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

Főbb pontok:

  • Az indexelő csak a fejléceket elemzi felfelé h3. Az alsó szintű fejlécek (h4,h5)h6 egyszerű szövegként lesznek kezelve, és megjelennek a content mezőben. Ezért az index- és mezőleképezések csak mélységig léteznek h3.

  • A content mezők és ordinal_position mezők nem igényelnek mezőleképezést, mert a bővített tartalomban ezek a nevek szerepelnek.

Lekérdezések futtatása

Az első dokumentum betöltése után azonnal megkezdheti a keresést.

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

Küldje el a kérést. Ez egy meghatározatlan teljes szöveges keresési lekérdezés, amely az indexben lekérdezhetőként megjelölt mezőket és a dokumentumok számát adja vissza. A válasznak a következőképpen kell kinéznie:

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

Adjon hozzá egy search paramétert egy karakterlánc kereséséhez.

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

Küldje el a kérést. A válasznak a következőképpen kell kinéznie:

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

Főbb pontok:

  • Mivel a markdownHeaderDepth be van állítva h3, a h4, h5 és h6 fejlécek egyszerű szövegként vannak kezelve, így azok megjelennek a content mezőben.

  • Az ordinális pozíció itt van 4. Ez a tartalom a 22 teljes tartalomszakasz közül a negyedikként jelenik meg.

Adjon hozzá egy paramétert select , amely kevesebb mezőre korlátozza az eredményeket. Adjon hozzá egy elemet filter a keresés további szűkítéséhez.

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

Szűrők esetén logikai operátorokat (és vagy nem) és összehasonlító operátorokat (eq, ne, gt, lt, ge, le) is használhat. A karakterlánc-összehasonlítások megkülönböztetik a kis- és nagybetűket. További információkért és példákért lásd: Lekérdezés létrehozása.

Megjegyzés

A $filter paraméter csak az index létrehozásakor szűrhetőként megjelölt mezőkön működik.

Alaphelyzetbe állítás és újrafuttatás

Az indexelők visszaállíthatók, hogy töröljék a végrehajtási előzményeket, ami lehetővé teszi a teljes újrafuttatást. Az alábbi kérések alaphelyzetbe állítását és az indexelő újrafuttatését kéri.

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

Erőforrások törlése

Ha a saját előfizetésében dolgozik, a projekt végén célszerű eltávolítani a már nem szükséges erőforrásokat. Az elhagyottan futó erőforrások plusz költségeket okozhatnak. Az erőforrásokat egyenként is törölheti, vagy törölheti az erőforráscsoportot a teljes erőforráskészlet törléséhez.

A Azure portál használatával törölheti az indexeket, indexelőket és adatforrásokat.

Következő lépések

Most, hogy már ismeri a Azure blobindexelés alapjait, tekintse meg közelebbről a Markdown-blobok indexelő konfigurációját Azure Storage: