Tutorial: Mengindeks blob Markdown berlapis dari Azure Storage menggunakan REST

Pencarian Azure AI dapat mengindeks dokumen dan array Markdown di Azure Blob Storage menggunakan indexer yang tahu cara membaca data Markdown.

Tutorial ini menunjukkan kepada Anda cara mengindeks file Markdown menggunakan oneToMany mode penguraian Markdown dan REST API Layanan Pencarian.

Dalam tutorial ini, Anda:

Prasyarat

• Akun Azure dengan langganan aktif. Buat akun secara gratis.

• Akun Azure Storage.

• Layanan Pencarian Azure AI.

• Visual Studio Code dengan Ekstensi Klien REST.

Menyiapkan data sampel

Membuat file Markdown

Salin dan tempel Markdown berikut ke dalam file bernama sample_markdown.md. Data sampel adalah satu file Markdown yang berisi berbagai elemen Markdown. Kami memilih satu file Markdown untuk tetap berada di bawah batas penyimpanan tingkat Gratis.

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

Unggah file dan dapatkan string koneksi

Ikuti petunjuk ini untuk mengunggah sample_markdown.md file ke kontainer di akun Azure Storage Anda. Anda juga harus mendapatkan string koneksi akun penyimpanan. Catat string koneksi dan nama kontainer untuk digunakan nanti.

Menyalin URL layanan pencarian dan kunci API

Untuk tutorial ini, koneksi ke Pencarian Azure AI memerlukan titik akhir dan kunci API. Anda bisa mendapatkan nilai-nilai ini dari portal Azure. Untuk metode koneksi alternatif, lihat Identitas terkelola.

1. Buka layanan pencarian Anda di portal Azure.

2. Dari panel kiri, pilih Gambaran Umum.

3. Catat URL, yang akan terlihat seperti https://my-service.search.windows.net.

4. Dari panel kiri, pilih Pengaturan>Tombol.

5. Catat kunci admin untuk hak penuh pada layanan. Terdapat dua kunci admin yang dapat saling dipertukarkan, disediakan untuk keberlangsungan bisnis apabila Anda perlu memperbarui salah satunya. Anda dapat menggunakan salah satu kunci pada permintaan untuk menambahkan, memodifikasi, dan menghapus objek.

   

Menyiapkan file REST Anda

1. Buat file di Visual Studio Code.

2. Berikan nilai untuk variabel yang digunakan dalam permintaan.

   @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. Simpan file menggunakan .rest ekstensi file atau .http .

Untuk bantuan dengan klien REST, lihat Mulai Cepat: Pencarian teks lengkap menggunakan REST.

Membuat sumber data

Sumber Data - Buat (REST API) membuat koneksi sumber data yang menentukan data apa yang akan diindeks.

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

Kirim permintaan. Respons akan terlihat seperti:

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
}

Membuat indeks

Indeks - Buat (REST API) membuat indeks pencarian di layanan pencarian Anda. Indeks menentukan semua bidang dan atributnya.

Dalam penguraian satu-dengan-banyak, dokumen pencarian mendefinisikan sisi 'banyak' dari hubungan tersebut. Bidang yang Anda tentukan dalam indeks menentukan struktur dokumen pencarian.

Anda hanya memerlukan bidang untuk elemen Markdown yang didukung pengurai. Bidang-bidang ini adalah:

• content: String yang berisi Markdown mentah yang ditemukan di lokasi tertentu, berdasarkan metadata header pada saat itu dalam dokumen.

• sections: Objek yang berisi subbidang untuk metadata header hingga tingkat header yang diinginkan. Misalnya, ketika markdownHeaderDepth diatur ke h3, berisi bidang string h1, h2, dan h3. Bidang-bidang ini diindeks dengan mencerminkan struktur ini dalam indeks, atau melalui pemetaan bidang dalam format /sections/h1, , /sections/h2dan sebagainya. Untuk contoh dalam konteks, lihat konfigurasi indeks dan pengindeks dalam sampel berikut. Subbidang yang terkandung adalah:

  • h1 - String yang berisi nilai header h1. String kosong jika tidak diatur pada titik ini dalam dokumen.
  • (Opsional) h2- String yang berisi nilai header h2. String kosong jika tidak diatur pada titik ini dalam dokumen.
  • (Opsional) h3- String yang berisi nilai header h3. String kosong jika tidak diatur pada titik ini dalam dokumen.
  • (Opsional) h4- String yang berisi nilai header h4. String kosong jika tidak diatur pada titik ini dalam dokumen.
  • (Opsional) h5- String yang berisi nilai header h5. String kosong jika tidak diatur pada titik ini dalam dokumen.
  • (Opsional) h6- String yang berisi nilai header h6. String kosong jika tidak diatur pada titik ini dalam dokumen.

• ordinal_position: Nilai bilangan bulat yang menunjukkan posisi bagian dalam hierarki dokumen. Bidang ini digunakan untuk mengurutkan bagian dalam urutan aslinya saat muncul di dokumen, dimulai dengan posisi ordinal 1 dan bertahap secara berurutan untuk setiap blok konten.

Implementasi ini menggunakan pemetaan bidang di pengindeks untuk memetakan dari konten yang diperkaya ke indeks. Untuk informasi selengkapnya tentang struktur dokumen satu-ke-banyak yang diurai, lihat Blob Markdown Indeks.

Contoh ini menyediakan sampel cara mengindeks data baik dengan maupun tanpa pemetaan bidang. Dalam hal ini, h1 berisi judul dokumen dan peta ke bidang bernama title. Bidang h2 dan h3 memetakan ke h2_subheader dan h3_subheader masing-masing. Bidang content dan ordinal_position tidak memerlukan pemetaan karena diekstrak dari Markdown langsung ke bidang menggunakan nama tersebut. Untuk contoh skema indeks lengkap yang tidak memerlukan pemetaan bidang, lihat akhir bagian ini.

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

Skema indeks dalam konfigurasi tanpa pemetaan bidang

Pemetaan bidang memungkinkan Anda memanipulasi dan memfilter konten yang diperkaya agar pas dengan bentuk indeks yang Anda inginkan. Namun, Anda mungkin hanya ingin mengambil konten yang diperkaya secara langsung. Dalam hal ini, skema akan terlihat seperti:

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

Untuk menegaskan kembali, kami memiliki subbidang hingga h3 di objek bagian karena markdownHeaderDepth diatur ke h3.

Jika Anda menggunakan skema ini, pastikan untuk menyesuaikan permintaan di masa mendatang sesuai. Melakukannya memerlukan penghapusan pemetaan bidang dari konfigurasi pengindeks dan memperbarui kueri pencarian untuk menggunakan nama bidang yang sesuai.

Membuat dan menjalankan pengindeks

Pengindeks - Buat (REST API) membuat pengindeks di layanan pencarian Anda. Pengindeks tersambung ke sumber data, memuat dan mengindeks data, dan secara opsional menyediakan jadwal untuk mengotomatiskan refresh data.

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

Poin-poin penting:

• Pengindeks hanya mengurai header hingga h3. Header tingkat bawah apa pun (h4,h5,h6) diperlakukan sebagai teks biasa dan muncul di content bidang . Inilah sebabnya mengapa pemetaan indeks dan bidang hanya ada hingga kedalaman h3.

• Bidang content dan ordinal_position tidak memerlukan pemetaan bidang karena ada dengan nama-nama tersebut dalam konten yang diperkaya.

Menjalankan kueri

Anda dapat mulai mencari segera setelah dokumen pertama dimuat.

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

Kirim permintaan. Ini adalah kueri pencarian teks lengkap yang tidak ditentukan yang mengembalikan semua bidang yang ditandai sebagai dapat diambil dalam indeks, bersama dengan jumlah dokumen. Respons akan terlihat seperti:

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

search Tambahkan parameter untuk mencari string.

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

Kirim permintaan. Respons akan terlihat seperti:

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

Poin-poin penting:

• Karena markdownHeaderDepth diatur ke h3, header h4, h5, dan h6 dianggap sebagai teks biasa, sehingga muncul di kolom content.

• Posisi ordinal di sini adalah 4. Konten ini muncul keempat dari 22 bagian total konten.

select Tambahkan parameter untuk membatasi hasil ke lebih sedikit bidang. filter Tambahkan untuk mempersempit pencarian lebih lanjut.

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

Untuk filter, Anda juga dapat menggunakan operator logis (dan, atau, tidak) dan operator perbandingan (eq, ne, gt, lt, ge, le). Perbandingan string dalam konteks pemrograman adalah peka terhadap huruf besar/kecil. Untuk informasi dan contoh selengkapnya, lihat Membuat kueri.

Reset dan jalankan ulang

Pengindeks dapat diatur ulang untuk menghapus riwayat eksekusi, yang memungkinkan pengoperasian ulang penuh. Permintaan berikut mengatur ulang dan menjalankan ulang pengindeks.

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

Membersihkan sumber daya

Ketika Anda bekerja dalam langganan Anda sendiri, di akhir proyek, ada baiknya untuk menghapus sumber daya yang tidak lagi Anda butuhkan. Sumber daya yang dibiarkan berjalan dapat menghabiskan uang Anda. Anda dapat menghapus sumber daya satu per satu atau menghapus grup sumber daya untuk menghapus seluruh kumpulan sumber daya.

Anda dapat menggunakan portal Azure untuk menghapus indeks, pengindeks, dan sumber data.

Langkah berikutnya

Sekarang setelah Anda terbiasa dengan dasar-dasar pengindeksan blob Azure, lihat lebih dekat konfigurasi pengindeks untuk blob Markdown di Azure Storage: