Tutorial: Mengindeks blob Markdown berlapis dari Azure Storage menggunakan REST

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

Tutorial ini menunjukkan kepada Anda untuk mengindeks file Markdown yang diindeks menggunakan oneToMany mode penguraian Markdown. Ini menggunakan klien REST dan REST API Pencarian untuk melakukan tugas-tugas berikut:

Jika Anda tidak memiliki langganan Azure, buat akun gratis sebelum Anda memulai.

Prasyarat

• Visual Studio Code dengan klien REST.

• Azure Storage

• Pencarian Azure AI. Buat atau temukan sumber daya Azure AI Search yang sudah ada di bawah langganan Anda saat ini.

Membuat dokumen 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!

Menyalin URL layanan pencarian dan kunci API

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

1. Masuk ke portal Azure, navigasikan ke halaman Gambaran Umum layanan pencarian, dan salin URL. Contoh titik akhir mungkin terlihat sepertihttps://mydemo.search.windows.net.

2. Di bawah Kunci Pengaturan>, salin kunci admin. Kunci admin digunakan untuk menambahkan, memodifikasi, dan menghapus objek. Ada dua kunci admin yang dapat dipertukarkan. Salin salah satu.

   

Menyiapkan file REST Anda

1. Mulai Visual Studio Code dan buat file baru.

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 .

Lihat Mulai Cepat: Pencarian teks menggunakan REST jika Anda memerlukan bantuan dengan klien REST.

Membuat sumber data

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

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

Kirim permintaan. Respons akan terlihat seperti ini:

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
}

Buat indeks

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

Dalam penguraian satu-ke-banyak, dokumen pencarian menentukan sisi 'banyak' hubungan. 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 h1string , , h2dan h3. Bidang ini diindeks dengan mencerminkan struktur ini dalam indeks, atau melalui pemetaan bidang dalam format /sections/h1, , sections/h2dll. Lihat konfigurasi indeks dan pengindeks dalam sampel berikut untuk contoh dalam konteks. 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 memanfaatkan 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, kita tahu bahwa h1 berisi judul dokumen, sehingga kita dapat memetakannya ke bidang bernama title. Kami juga akan memetakan h2 bidang dan h3 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=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}
      ]
    }

Skema indeks dalam konfigurasi tanpa pemetaan bidang

Pemetaan bidang memungkinkan Anda memanipulasi dan memfilter konten yang diperkaya agar sesuai dengan bentuk indeks yang Anda inginkan, tetapi 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 memilih untuk menggunakan skema ini, pastikan untuk menyesuaikan permintaan nanti yang sesuai. Ini akan memerlukan penghapusan pemetaan bidang dari konfigurasi pengindeks dan memperbarui kueri pencarian untuk menggunakan nama bidang yang sesuai.

Membuat dan menjalankan pengindeks

Buat Pengindeks 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=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
        }
      ]
    }

Poin utama:

• Pengindeks hanya akan mengurai header hingga h3. Header tingkat bawah apa pun (h4,,)h6 akan diperlakukan sebagai teks biasa dan muncul di contenth5bidang . 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.

Jalankan Kueri

Anda dapat mulai mencari segera setelah dokumen pertama dimuat.

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

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 ini:

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 pada string.

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

Kirim permintaan. Respons akan terlihat seperti ini:

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 utama:

• markdownHeaderDepth Karena diatur ke h3, h4header , h5, dan h6 diperlakukan sebagai teks biasa, sehingga muncul di content bidang .

• 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=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"
    }
  ]
}

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

Atur ulang dan jalankan ulang

Pengindeks dapat diatur ulang, menghapus riwayat eksekusi, yang memungkinkan pengoperasian ulang penuh. Permintaan GET berikut adalah untuk reset, diikuti dengan jalankan ulang.

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

Membersihkan sumber daya

Saat Anda bekerja di langganan Anda sendiri, di akhir proyek, sebaiknya hapus 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 rangkaian sumber daya.

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

Langkah berikutnya

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