教學課程：使用 REST 從 Azure 儲存體建立巢狀 Markdown Blob 的索引

發行項
11/19/2024

注意

此功能目前處於公開預覽。此預覽版是在沒有服務等級協定的情況下提供，不建議用於生產工作負載。可能不支援特定功能，或可能已經限制功能。如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。

Azure AI 搜尋可以使用知道如何讀取 Markdown 數據的索引器，在 Azure Blob 儲存體中編制 Markdown 檔和數位的索引。

本教學課程說明如何使用 Markdown 剖析模式編製索引的 oneToMany Markdown 檔案編製索引。它會使用 REST 用戶端和搜尋服務 REST API 來執行下列工作：

設定範例資料並設定 azureblob 資料來源
建立 Azure AI 搜尋服務索引以包含可搜尋的內容
建立並執行索引子以讀取容器，並擷取可搜尋的內容
搜尋剛剛建立的索引

如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。

必要條件

Visual Studio Code 具有 REST 用戶端。
Azure 儲存體
Azure AI 搜尋服務 (部分機器翻譯) 在您的目前訂用帳戶下建立或尋找現有的 Azure AI 搜尋服務資源。

注意

您可以使用免費服務來進行本教學課程。免費的搜尋服務會有限制，您只能使用三個索引、三個索引子和三個資料來源。本教學課程會各建立一個。開始之前，請確定您的服務有空間可接受新的資源。

建立 Markdown 檔

將下列 Markdown 複製並貼到名為的 sample_markdown.md檔案中。範例數據是包含各種 Markdown 元素的單一 Markdown 檔案。我們選擇了一個 Markdown 檔案，以保持在免費層的儲存限制之下。

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

複製搜尋服務 URL 與 API 金鑰

在本教學課程中，Azure AI 搜尋服務的連線需要端點和 API 金鑰。您可以從 Azure 入口網站取得這些值。如需替代連線方法，請參閱受控識別。

登入 Azure 入口網站，瀏覽至搜尋服務的 [概觀] 頁面，然後複製 URL。範例端點看起來會像是 https://mydemo.search.windows.net。
在 [設定 > 金鑰] 下面，複製系統管理金鑰。系統管理金鑰可用來新增、修改和刪除物件。有兩個可交換的系統管理密鑰。複製任一個。

設定 REST 檔案

啟動 Visual Studio Code 並建立新的檔案。

提供要求中使用的變數值：

@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

使用 .rest 或 .http 副檔名來儲存檔案。

如果您需要使用 REST 用戶端的協助，請參閱快速入門：使用 REST 進行文字搜尋。

建立資料來源

建立資料來源 (REST) 會建立資料來源連線，指定要編製索引的資料。

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

傳送要求。回應看起來應如下所示：

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
}

建立索引

建立索引 (REST) 會在您的搜尋服務上建立搜尋索引。索引會指定所有欄位及其屬性。

在一對多剖析中，搜尋檔會定義關聯性的「多」端。您在索引中指定的欄位會決定搜尋檔案的結構。

您只需要剖析器支援的 Markdown 元素欄位。這些欄位是：

content：字串，其中包含在特定位置中找到的原始 Markdown，此字串會根據檔中該點的標頭元數據。
sections：物件，包含標頭元數據的子字段，最多可達所需的標頭層級。例如，當設定為時markdownHeaderDepth，會包含字串字段h1、 h2和 h3。h3 這些欄位會透過鏡像索引中的這個結構，或透過格式 /sections/h1、 sections/h2等的欄位對應來編制索引。如需內容中的範例，請參閱下列範例中的索引和索引器組態。包含的子欄位如下：
- h1 - 包含 h1 標頭值的字串。如果目前檔中未設定，則為空字串。
- （選擇性） h2- 包含 h2 標頭值的字串。如果目前檔中未設定，則為空字串。
- （選擇性） h3- 包含 h3 標頭值的字串。如果目前檔中未設定，則為空字串。
- （選擇性） h4- 包含 h4 標頭值的字串。如果目前檔中未設定，則為空字串。
- （選擇性） h5- 包含 h5 標頭值的字串。如果目前檔中未設定，則為空字串。
- （選擇性） h6- 包含 h6 標頭值的字串。如果目前檔中未設定，則為空字串。
ordinal_position：整數值，表示區段在文件階層中的位置。此欄位用於排序其原始序列中的區段，因為它們出現在檔中，從序數位置 1 開始，並依序遞增每個內容區塊。

此實作會利用索引器中的字段對應，從擴充的內容對應到索引。如需剖析的一對多文件結構的詳細資訊，請參閱索引 Markdown Blob。

此範例提供如何使用和不使用字段對應來為數據編製索引的範例。在此情況下，我們知道包含 h1 文件的標題，因此我們可以將它對應至名為 title的欄位。我們也會分別將和 h3 欄位對應h2至 h2_subheader 和 h3_subheader 。 content和 ordinal_position 欄位不需要對應，因為它們會直接從 Markdown 擷取到使用這些名稱的欄位。如需不需要欄位對應的完整索引架構範例，請參閱本節結尾。

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

沒有欄位對應之設定中的索引架構

欄位對應可讓您操作和篩選擴充的內容，以符合您所需的索引圖形，但您可能只想直接取得擴充的內容。在此情況下，架構看起來會像這樣：

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

若要重申，我們在 sections 物件中最多 h3 會有子字段，因為 markdownHeaderDepth 設定為 h3。

如果您選擇使用此架構，請務必據此調整後續要求。這需要從索引器組態中移除欄位對應，並更新搜尋查詢以使用對應的功能變數名稱。

建立並執行索引子

建立索引子會在您的搜尋服務上建立索引子。索引子會連接至資料來源、載入資料並編製索引，以及選擇性地提供排程來將資料重新整理自動化。

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

重點︰

索引器只會剖析標頭至 h3。任何較低層級的標頭（h4，，h5h6）都會被視為純文本，並顯示在content字段中。這就是為什麼索引和欄位對應只存在於的深度 h3。
和 content ordinal_position 欄位不需要欄位對應，因為它們存在於擴充內容中的這些名稱。

執行查詢

第一個文件載入後，您就可以開始查詢。

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

傳送要求。這是未指定的全文檢索搜尋查詢，會傳回所有在索引中標記為可擷取的欄位，以及文件計數。回應看起來應如下所示：

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 參數以搜尋字串。

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

傳送要求。回應看起來應如下所示：

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

重點︰

markdownHeaderDepth因為設定為 h3，所以h4會將、 h5和 h6 標頭視為純文字，因此它們會出現在 content 字段中。
這裡的序數位置為 4。此內容會顯示在22個內容區段中的第四個。

新增 select 參數，將結果限定為較少的欄位。新增 filter 以進一步縮小搜尋範圍。

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

在篩選中，您也可以使用邏輯運算子 (and、or、not) 和比較運算子 (eq、ne、gt、lt、ge、le)。字串比較是區分大小寫的。如需詳細資訊和範例，請參閱建立查詢。

注意

$filter 參數只能在索引建立時標記為可篩選的欄位中使用。

重設並重新執行

您可以重設索引子，清除執行歷程記錄，以便允許完全重新執行。下列 GET 要求適用於重設，然後接著重新執行。

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

清除資源

如果您使用自己的訂用帳戶，當專案結束時，建議您移除不再需要的資源。資源若繼續執行，將需付費。您可以個別刪除資源，或刪除資源群組以刪除整組資源。

您可以使用 Azure 入口網站來移除索引、索引器和資料來源。

下一步

現在您已熟悉 Azure Blob 索引編製的基本概念，讓我們進一步瞭解 Azure 儲存體中 Markdown Blob 的索引器設定。

設定 Markdown Blob 索引編製

共用方式為

教學課程：使用 REST 從 Azure 儲存體建立巢狀 Markdown Blob 的索引

必要條件

建立 Markdown 檔

複製搜尋服務 URL 與 API 金鑰

設定 REST 檔案

建立資料來源

建立索引

沒有欄位對應之設定中的索引架構

建立並執行索引子

執行查詢

重設並重新執行

清除資源

下一步

意見反應

其他資源

共用方式為

教學課程：使用 REST 從 Azure 儲存體 建立巢狀 Markdown Blob 的索引

必要條件

建立 Markdown 檔

複製搜尋服務 URL 與 API 金鑰

設定 REST 檔案

建立資料來源

建立索引

沒有欄位對應之設定中的索引架構

建立並執行索引子

執行查詢

重設並重新執行

清除資源

下一步

意見反應

其他資源

教學課程：使用 REST 從 Azure 儲存體建立巢狀 Markdown Blob 的索引