Självstudie: Indexa kapslade Markdown-blobar från Azure Storage med hjälp av REST

Artikel
11/19/2024

Kommentar

Den här funktionen är för närvarande i allmänt tillgänglig förhandsversion. Den här förhandsversionen tillhandahålls utan ett serviceavtal och rekommenderas inte för produktionsarbetsbelastningar. Vissa funktioner kanske inte stöds eller kan vara begränsade. Mer information finns i Kompletterande villkor för användning av Microsoft Azure-förhandsversioner.

Azure AI Search kan indexisera Markdown-dokument och matriser i Azure Blob Storage med hjälp av en indexerare som vet hur markdown-data ska läsas.

Den här självstudien visar hur du indexerar Markdown-filer som indexerats med oneToMany markdown-parsningsläget. Den använder en REST-klient och REST-API:er för sökning för att utföra följande uppgifter:

Konfigurera exempeldata och konfigurera en azureblob datakälla
Skapa ett Azure AI Search-index som innehåller sökbart innehåll
Skapa och kör en indexerare för att läsa containern och extrahera sökbart innehåll
Söka i indexet som du precis skapade

Om du inte har någon Azure-prenumeration skapar du ett kostnadsfritt konto innan du börjar.

Förutsättningar

Visual Studio Code med en REST-klient.
Azure Storage
Azure AI Search. Skapa eller hitta en befintlig Azure AI Search-resurs under din aktuella prenumeration.

Kommentar

Du kan använda den kostnadsfria tjänsten för den här självstudien. En kostnadsfri söktjänst begränsar dig till tre index, tre indexerare och tre datakällor. I den här kursen skapar du en av varje. Innan du börjar bör du se till att du har plats för din tjänst för att acceptera de nya resurserna.

Skapa ett Markdown-dokument

Kopiera och klistra in följande Markdown i en fil med namnet sample_markdown.md. Exempeldata är en enda Markdown-fil som innehåller olika Markdown-element. Vi valde en Markdown-fil för att hålla oss under lagringsgränserna för den kostnadsfria nivån.

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

Kopiera en url för söktjänsten och API-nyckeln

I den här självstudien kräver anslutningar till Azure AI Search en slutpunkt och en API-nyckel. Du kan hämta dessa värden från Azure Portal. Alternativa anslutningsmetoder finns i Hanterade identiteter.

Logga in på Azure Portal, gå till översiktssidan för söktjänsten och kopiera URL:en. Här följer ett exempel på hur en slutpunkt kan se ut: https://mydemo.search.windows.net.
Under Inställningar>Nycklar kopierar du en administratörsnyckel. Administratörsnycklar används för att lägga till, ändra och ta bort objekt. Det finns två utbytbara administratörsnycklar. Kopiera någon av dem.

Konfigurera REST-filen

Starta Visual Studio Code och skapa en ny fil.

Ange värden för variabler som används i begäran:

@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

Spara filen med hjälp av ett .rest filnamnstillägg eller .http filnamnstillägg.

Se Snabbstart: Textsökning med REST om du behöver hjälp med REST-klienten.

Skapa en datakälla

Skapa datakälla (REST) skapar en datakällaanslutning som anger vilka data som ska indexeras.

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

Skicka begäran. Svaret ska se ut så här:

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
}

Skapa ett index

Skapa index (REST) skapar ett sökindex i söktjänsten. Ett index anger alla fält och deras attribut.

I en-till-många-parsning definierar sökdokumentet "många"-sidan av relationen. De fält som du anger i indexet avgör sökdokumentets struktur.

Du behöver bara fält för Markdown-elementen som parsern stöder. Dessa fält är:

content: En sträng som innehåller den råa Markdown som finns på en specifik plats, baserat på huvudmetadata vid den tidpunkten i dokumentet.
sections: Ett objekt som innehåller underfält för rubrikmetadata upp till önskad rubriknivå. När är inställt på innehåller till h3exempel markdownHeaderDepth strängfälten h1, h2och h3. Dessa fält indexeras genom att den här strukturen speglas i indexet eller genom fältmappningar i formatet /sections/h1, sections/h2osv. Se index- och indexeringskonfigurationer i följande exempel för kontextexempel. De underfält som ingår är:
- h1 – En sträng som innehåller h1-huvudets värde. Tom sträng om den inte har angetts just nu i dokumentet.
- (Valfritt) h2– En sträng som innehåller h2-huvudets värde. Tom sträng om den inte har angetts just nu i dokumentet.
- (Valfritt) h3– En sträng som innehåller h3-huvudets värde. Tom sträng om den inte har angetts just nu i dokumentet.
- (Valfritt) h4– En sträng som innehåller värdet för h4-huvudet. Tom sträng om den inte har angetts just nu i dokumentet.
- (Valfritt) h5– En sträng som innehåller h5-huvudets värde. Tom sträng om den inte har angetts just nu i dokumentet.
- (Valfritt) h6– En sträng som innehåller h6-huvudets värde. Tom sträng om den inte har angetts just nu i dokumentet.
ordinal_position: Ett heltalsvärde som anger positionen för avsnittet i dokumenthierarkin. Det här fältet används för att sortera avsnitten i den ursprungliga sekvensen som de visas i dokumentet, med början med en ordningsposition på 1 och inkrementellt för varje innehållsblock.

Den här implementeringen utnyttjar fältmappningar i indexeraren för att mappa från det berikade innehållet till indexet. Mer information om den parsade dokumentstrukturen en-till-många finns i indexmarkeringsblobar.

Det här exemplet innehåller exempel på hur du indexar data både med och utan fältmappningar. I det här fallet vet vi att det h1 innehåller dokumentets rubrik, så att vi kan mappa det till ett fält med namnet title. Vi kommer också att mappa fälten h2 och h3 till h2_subheaderh3_subheader respektive. Fälten content och ordinal_position kräver ingen mappning eftersom de extraheras från Markdown direkt till fält med hjälp av dessa namn. Ett exempel på ett fullständigt indexschema som inte kräver fältmappningar finns i slutet av det här avsnittet.

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

Indexschema i en konfiguration utan fältmappningar

Med fältmappningar kan du ändra och filtrera berikat innehåll så att det passar in i önskad indexform, men du kanske bara vill ta det berikade innehållet direkt. I så fall skulle schemat se ut så hä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}
  ]
}

För att upprepa har vi underfält upp till h3 i avsnittsobjektet eftersom markdownHeaderDepth är inställt på h3.

Om du väljer att använda det här schemat måste du justera senare begäranden i enlighet med detta. Detta kräver att fältmappningarna tas bort från indexerarens konfiguration och att sökfrågorna uppdateras för att använda motsvarande fältnamn.

Skapa och köra en indexerare

Skapa Indexer skapar en indexerare i söktjänsten. En indexerare ansluter till datakällan, läser in och indexerar data, och du kan även ange ett schema för att automatisera datauppdateringen.

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

Viktiga punkter:

Indexeraren parsar bara rubriker upp till h3. Alla rubriker på lägre nivå (h4,h5,h6) behandlas som oformaterad text och visas i fältet content . Därför finns index- och fältmappningarna bara upp till ett djup av h3.
Fälten content och ordinal_position kräver ingen fältmappning eftersom de finns med dessa namn i det berikade innehållet.

Köra frågor

Du kan börja söka så snart det första dokumentet har lästs in.

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

Skicka begäran. Det här är en ospecificerad fulltextsökningsfråga som returnerar alla fält som markerats som hämtningsbara i indexet, tillsammans med ett antal dokument. Svaret ska se ut så här:

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

Lägg till en search parameter för att söka efter en sträng.

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

Skicka begäran. Svaret ska se ut så här:

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

Viktiga punkter:

markdownHeaderDepth Eftersom är inställt på h3behandlas rubrikerna h4, h5och som h6 klartext, så de visas i fältetcontent.
Ordningstalet här är 4. Det här innehållet visas på fjärde plats av de 22 totala innehållsavsnitten.

Lägg till en select parameter för att begränsa resultatet till färre fält. Lägg till en filter för att ytterligare begränsa sökningen.

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

För filter kan du också använda logiska operatorer (och eller inte) och jämförelseoperatorer (eq, ne, gt, lt, ge, le). Strängjämförelser är skiftlägeskänsliga. Mer information och exempel finns i Skapa en fråga.

Kommentar

Parametern $filter fungerar bara på fält som har markerats som filterbara när indexet skapas.

Återställa och köra igen

Indexerare kan återställas och rensa körningshistoriken, vilket möjliggör en fullständig omkörning. Följande GET-begäranden är för återställning, följt av omkörning.

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

Rensa resurser

När du arbetar i din egen prenumeration i slutet av ett projekt är det en bra idé att ta bort de resurser som du inte längre behöver. Resurser som fortsätter att köras kostar pengar. Du kan ta bort enstaka resurser eller hela resursgruppen om du vill ta bort alla resurser.

Du kan använda Azure Portal för att ta bort index, indexerare och datakällor.

Nästa steg

Nu när du är bekant med grunderna i Azure Blob-indexering ska vi ta en närmare titt på indexerarens konfiguration för Markdown-blobar i Azure Storage.

Konfigurera Markdown-blobindexering

Dela via

Självstudie: Indexa kapslade Markdown-blobar från Azure Storage med hjälp av REST

Förutsättningar

Skapa ett Markdown-dokument

Kopiera en url för söktjänsten och API-nyckeln

Konfigurera REST-filen

Skapa en datakälla

Skapa ett index

Indexschema i en konfiguration utan fältmappningar

Skapa och köra en indexerare

Köra frågor

Återställa och köra igen

Rensa resurser

Nästa steg

Feedback

Ytterligare resurser