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

Az Azure AI Search indexelheti a Markdown-dokumentumokat és -tömböket az Azure Blob Storage-ban egy olyan indexelő használatával, amely ismeri a Markdown-adatok olvasását.

Ez az oktatóanyag bemutatja, hogy a Markdown-elemzési módban indexelt oneToMany Markdown-fájlokat indexelje. REST-ügyfelet és a Search REST API-kat használ a következő feladatok végrehajtásához:

Ha még nincs Azure-előfizetése, kezdés előtt hozzon létre egy ingyenes fiókot.

Előfeltételek

• Visual Studio Code REST-ügyféllel.

• Azure Storage

• Azure AI Search. Hozzon létre vagy keressen egy meglévő Azure AI Search-erőforrást az aktuális előfizetése alatt.

Markdown-dokumentum 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!

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

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

1. Jelentkezzen be az Azure Portalra, lépjen a keresési szolgáltatás áttekintési oldalára, és másolja az URL-címet. A végpontok például a következőképpen nézhetnek ki: https://mydemo.search.windows.net.

2. A Beállítások>kulcsok területen másolja ki a rendszergazdai kulcsot. A rendszergazdai kulcsok objektumok hozzáadására, módosítására és törlésére szolgálnak. Két felcserélhető rendszergazdai kulcs van. Másolja valamelyiket.

   

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

1. Indítsa el a Visual Studio Code-ot, és hozzon létre egy új fájlt.

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

Lásd : Rövid útmutató: Szövegkeresés REST használatával, ha segítségre van szüksége a REST-ügyféllel kapcsolatban.

Adatforrás létrehozása

Az Adatforrás létrehozása (REST) létrehoz egy adatforrás-kapcsolatot, amely meghatározza az indexelendő adatokat.

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

Küldje el a kérést. A válasznak így 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=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
}

Index létrehozása

Az Index létrehozása (REST) 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 adott helyen található nyers Markdownt tartalmazó sztring a dokumentum azon pontján található fejléc metaadatai alapján.

• sections: Olyan objektum, amely a fejléc metaadatainak almezőit tartalmazza a kívánt fejlécszintig. Ha például markdownHeaderDepth be van állítva h3, sztringmezőket h1tartalmaz, h2és h3. Ezek a mezők indexelése a struktúra indexben való tükrözésével, vagy a formátumbeli /sections/h1sections/h2mezőleképezésekkel stb. történik. A környezetbeli példákért tekintse meg az indexelő és az indexelő konfigurációját az alábbi mintákban. Az almezők a következők:

  • h1 - A h1 fejlécértéket tartalmazó sztring. Üres sztring, ha a dokumentum ezen a pontján nincs beállítva.
  • (Nem kötelező) h2- A h2 fejlécértéket tartalmazó sztring. Üres sztring, ha a dokumentum ezen a pontján nincs beállítva.
  • (Nem kötelező) h3- A h3 fejlécértéket tartalmazó sztring. Üres sztring, ha a dokumentum ezen a pontján nincs beállítva.
  • (Nem kötelező) h4- A h4 fejlécértéket tartalmazó sztring. Üres sztring, ha a dokumentum ezen a pontján nincs beállítva.
  • (Nem kötelező) h5- A h5 fejlécértéket tartalmazó sztring. Üres sztring, ha a dokumentum ezen a pontján nincs beállítva.
  • (Nem kötelező) h6- A h6 fejlécértéket tartalmazó sztring. Üres sztring, ha a dokumentum ezen a pontján nincs beállítva.

• ordinal_position: A szakasz dokumentumhierarchián belüli pozícióját jelző egész szám. 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-blobjaiban 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 tudjuk, hogy h1 tartalmazza a dokumentum címét, így leképezhetjük egy nevesített titlemezőre. A mezőket és h3 a h2 mezőket h2_subheaderh3_subheader is megfeleltetjük. A content és ordinal_position a 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=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}
      ]
    }

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 indexalakzatba, de előfordulhat, 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}
  ]
}

Megismétlendő, hogy a szakaszok objektumában markdownHeaderDepth lévő h3 almezők a következőre h3vannak á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

Az Indexelő létrehozása 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=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
        }
      ]
    }

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, mivel azok a bővített tartalomban szereplő névvel együtt léteznek.

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=2024-11-01-preview  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 így 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 paramétert search a sztringben való kereséshez.

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

Küldje el a kérést. A válasznak így 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ítvah3, a program h5h6 egyszerű szövegként kezeli a h4fejléceket, í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=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"
    }
  ]
}

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 sztring-ö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.

Alaphelyzetbe állítás és ismételt futtatás

Az indexelőzmények alaphelyzetbe állíthatók, törölhetik a végrehajtási előzményeket, ami lehetővé teszi a teljes újrafuttatást. A következő GET-kérések alaphelyzetbe állításra, majd újrafuttatva jelennek meg.

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

Az erőforrások eltávolítása

Ha a saját előfizetésében dolgozik, a projekt végén célszerű eltávolítania a már nem szükséges erőforrásokat. A továbbra is futó erőforrások költségekkel járhatnak. Az erőforrásokat törölheti egyesével, vagy az erőforráscsoport törlésével eltávolíthatja a benne lévő összes erőforrást is.

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

Következő lépések

Most, hogy megismerte az Azure Blob-indexelés alapjait, tekintsük át közelebbről a Markdown-blobok Indexelő konfigurációját az Azure Storage-ban.