Öğretici: REST kullanarak Azure Depolama'dan iç içe markdown bloblarını dizine alma

Azure AI Search, Markdown verilerini okumayı bilen bir dizin oluşturucu kullanarak markdown belgelerini ve dizilerini Azure Blob Depolama dizine alabilir.

Bu öğreticide Markdown ayrıştırma modu kullanılarak oneToMany dizine alınan Markdown dosyalarını dizinlemeniz gösterilmektedir. Aşağıdaki görevleri gerçekleştirmek için bir REST istemcisi ve Search REST API'leri kullanır:

Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap oluşturun.

Önkoşullar

• REST istemcisi ile Visual Studio Code.

• Azure Depolama

• Azure AI Arama. Geçerli aboneliğinizin altında mevcut bir Azure AI Search kaynağı oluşturun veya bulun.

Markdown belgesi oluşturma

Aşağıdaki Markdown dosyasını kopyalayıp adlı sample_markdown.mddosyaya yapıştırın. Örnek veriler, çeşitli Markdown öğelerini içeren tek bir Markdown dosyasıdır. Ücretsiz katmanın depolama sınırları altında kalmak için bir Markdown dosyası seçtik.

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

Arama hizmeti URL'si ve API anahtarı kopyalama

Bu öğretici için Azure AI Search bağlantıları için bir uç nokta ve bir API anahtarı gerekir. Bu değerleri Azure portalından alabilirsiniz. Alternatif bağlantı yöntemleri için bkz . yönetilen kimlikler.

1. Azure portalında oturum açın, arama hizmetine Genel Bakış sayfasına gidin ve URL'yi kopyalayın. Örnek uç nokta https://mydemo.search.windows.net şeklinde görünebilir.

2. Ayarlar>Anahtarları'nın altında bir yönetici anahtarı kopyalayın. Yönetici anahtarları nesneleri eklemek, değiştirmek ve silmek için kullanılır. Değiştirilebilir iki yönetici anahtarı vardır. İkisini de kopyalayın.

   

REST dosyanızı ayarlama

1. Visual Studio Code'u başlatın ve yeni bir dosya oluşturun.

2. İstekte kullanılan değişkenler için değerler sağlayın:

   @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. Veya .http dosya uzantısını kullanarak .rest dosyayı kaydedin.

REST istemcisiyle ilgili yardıma ihtiyacınız varsa bkz . Hızlı Başlangıç: REST kullanarak metin araması.

Veri kaynağı oluşturma

Veri Kaynağı Oluştur (REST), hangi verilerin dizine alınacağını belirten bir veri kaynağı bağlantısı oluşturur.

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

İsteği gönderin. Yanıt şöyle görünmelidir:

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
}

Dizin oluşturma

Dizin Oluştur (REST), arama hizmetinizde bir arama dizini oluşturur. Dizin tüm alanları ve bunların özniteliklerini belirtir.

Bire çok ayrıştırmada, arama belgesi ilişkinin 'çok' tarafını tanımlar. Dizinde belirttiğiniz alanlar, arama belgesinin yapısını belirler.

Yalnızca ayrıştırıcının desteklediği Markdown öğeleri için alanlara ihtiyacınız vardır. Bu alanlar aşağıdaki gibidir:

• content: Belgenin o noktasındaki üst bilgi meta verilerini temel alarak belirli bir konumda bulunan ham Markdown'ı içeren dize.

• sections: üst bilgi meta verileri için istenen üst bilgi düzeyine kadar alt alanları içeren bir nesne. Örneğin, markdownHeaderDepth olarak ayarlandığında h3, ve h3dize alanlarını h1h2içerir. Bu alanlar, dizindeki bu yapıyı yansıtarak veya , vb sections/h2biçimindeki /sections/h1alan eşlemeleri aracılığıyla dizinlenir. Bağlam içi örnekler için aşağıdaki örneklerde dizin ve dizin oluşturucu yapılandırmalarına bakın. İçeren alt alanları şunlardır:

  • h1 - h1 üst bilgi değerini içeren bir dize. Belgenin bu noktasında ayarlanmadıysa boş dize.
  • (İsteğe bağlı) h2- h2 üst bilgi değerini içeren bir dize. Belgenin bu noktasında ayarlanmadıysa boş dize.
  • (İsteğe bağlı) h3- h3 üst bilgi değerini içeren bir dize. Belgenin bu noktasında ayarlanmadıysa boş dize.
  • (İsteğe bağlı) h4- h4 üst bilgi değerini içeren bir dize. Belgenin bu noktasında ayarlanmadıysa boş dize.
  • (İsteğe bağlı) h5- h5 üst bilgi değerini içeren bir dize. Belgenin bu noktasında ayarlanmadıysa boş dize.
  • (İsteğe bağlı) h6- h6 üst bilgi değerini içeren bir dize. Belgenin bu noktasında ayarlanmadıysa boş dize.

• ordinal_position: Bölümün belge hiyerarşisi içindeki konumunu gösteren bir tamsayı değeri. Bu alan, 1 sıralı bir konumdan başlayarak ve her içerik bloğu için sıralı olarak artırılarak, bölümleri belgede göründükleri şekilde özgün sıralarında sıralamak için kullanılır.

Bu uygulama, zenginleştirilmiş içerikten dizine eşlemek için dizin oluşturucudaki alan eşlemelerinden yararlanıyor. Ayrıştırılmış bire çok belge yapısı hakkında daha fazla bilgi için bkz . dizin markdown blobları.

Bu örnek, alan eşlemeleriyle ve alan eşlemeleri olmadan verilerin nasıl dizine yüklenip dizine alınmayacaklarına yönelik örnekler sağlar. Bu durumda, belgenin başlığını içerdiğini h1 biliyoruz, böylece bunu adlı titlebir alanla eşleyebiliriz. Ayrıca ve h3 alanlarını h2_subheader sırasıyla ve h3_subheader ile eşleyeceğizh2. content Ve ordinal_position alanları, Markdown'dan doğrudan bu adlar kullanılarak alanlara ayıklandığından eşleme gerektirmez. Alan eşlemeleri gerektirmeyen bir tam dizin şeması örneği için bu bölümün sonuna bakın.

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

Alan eşlemesi olmayan bir yapılandırmada dizin şeması

Alan eşlemeleri, zenginleştirilmiş içeriği istediğiniz dizin şekline sığacak şekilde işlemenize ve filtrelemenize olanak sağlar, ancak zenginleştirilmiş içeriği doğrudan almak isteyebilirsiniz. Bu durumda şema şöyle görünür:

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

Yinelemek için sections h3 nesnesinde alt alanlarımız var çünkü markdownHeaderDepth olarak ayarlanmıştır h3.

Bu şemayı kullanmayı seçerseniz, sonraki istekleri uygun şekilde ayarladığınızdan emin olun. Bunun için alan eşlemelerinin dizin oluşturucu yapılandırmasından kaldırılması ve arama sorgularının ilgili alan adlarını kullanacak şekilde güncelleştirilmesi gerekir.

Dizin oluşturucu oluşturma ve çalıştırma

Dizin Oluşturucu Oluştur, arama hizmetinizde bir dizin oluşturucu oluşturur. Dizin oluşturucu veri kaynağına bağlanır, verileri yükler ve dizinler ve isteğe bağlı olarak veri yenilemeyi otomatikleştirmek için bir zamanlama sağlar.

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

Önemli noktalar:

• Dizin oluşturucu yalnızca öğesine h3kadar olan üst bilgileri ayrıştıracaktır. Alt düzey üst bilgiler (h4,,h5h6) düz metin olarak değerlendirilir ve alanda content gösterilir. Dizin ve alan eşlemelerinin yalnızca derinliğine h3kadar mevcut olmasının nedeni budur.

• content ve ordinal_position alanları, zenginleştirilmiş içerikte bu adlarla var oldukları için alan eşlemesi gerektirmez.

Sorgu çalıştırma

İlk belge yüklenir yüklenmez aramaya başlayabilirsiniz.

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

İsteği gönderin. Bu, dizinde alınabilir olarak işaretlenmiş tüm alanları ve belge sayısını döndüren, belirtilmemiş bir tam metin arama sorgusudur. Yanıt şöyle görünmelidir:

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

Bir search dizede aramak için bir parametre ekleyin.

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

İsteği gönderin. Yanıt şöyle görünmelidir:

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

Önemli noktalar:

• markdownHeaderDepth olarak ayarlandığından h4h3, , h5ve h6 üst bilgileri düz metin olarak değerlendirilir ve bu nedenle alanda content görünürler.

• Sıra konumu buradadır 4. Bu içerik, toplam 22 içerik bölümünden dördüncü sırada görünür.

Sonuçları daha az alanla sınırlamak için bir select parametre ekleyin. Aramayı daha da daraltmak için bir filter ekleyin.

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

Filtreler için Mantıksal işleçleri (ve veya değil) ve karşılaştırma işleçlerini (eq, ne, gt, lt, ge, le) de kullanabilirsiniz. Dize karşılaştırmaları büyük/küçük harfe duyarlıdır. Daha fazla bilgi ve örnek için bkz . Sorgu oluşturma.

Sıfırlama ve yeniden çalıştırma

Dizin oluşturucular sıfırlanabilir ve tam yeniden çalıştırmaya izin veren yürütme geçmişi temizlenebilir. Aşağıdaki GET istekleri sıfırlamaya yöneliktir ve ardından yeniden çalıştırılır.

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

Kaynakları temizleme

Kendi aboneliğinizde çalışırken, bir projenin sonunda artık ihtiyacınız olmayan kaynakları kaldırmak iyi bir fikirdir. Çalışır durumda bırakılan kaynaklar maliyetlerin artmasına neden olabilir. Kaynakları teker teker silebilir veya tüm kaynak grubunu silerek kaynak kümesinin tamamını kaldırabilirsiniz.

Dizinleri, dizin oluşturucuları ve veri kaynaklarını silmek için Azure portalını kullanabilirsiniz.

Sonraki adımlar

Artık Azure Blob dizin oluşturmanın temellerini bildiğinize göre, Azure Depolama'da Markdown blobları için dizin oluşturucu yapılandırmasına daha yakından bakalım.